When it comes to learning something new, I am a minimalist: I am usually daunted by long complicated tutorials and page filling explanations with lots of details I don't (yet) care about. When learning something new, I like to be able to see results as soon as possible. In a way this is the "Hello World" approach to learning, which encapsulates very well how to get a working result on your screen in the minimal amount of time possible.

So when I started to learn about LibraryLink, I needed to have something like a "Hello World" program for it. There are many excellent demo examples in the LibraryLink
documentation, but even these are more complicated than I can consume easily.

LibraryLink is a useful tool in the Wolfram Language to extend it by compiling and linking in C code. In a way LibraryLink is very similar to MathLink (to be known as WolframLink in the future and in the rest of this post) in the sense that both frameworks extend the Wolfram Language by defining interfaces to the C language.

The difference between LibraryLink and WolframLink is that WolframLink always generates a separate executable binary over which communication takes place, whereas LibraryLink creates dynamically loadable libraries. Both have their advantages and disadvantages, which are described in detail in the section 'Alternatives to Wolfram Library Functions' of this documentation page:

http://reference.wolfram.com/language/LibraryLink/tutorial/Introduction.html

So let's start with the absolute minimal example for LibraryLink: Adding a new function to the Wolfram Language which takes no arguments, does nothing and returns nothing. Let's call this function 'DoNothing'.

The usefulness of this function is to learn about everything you need to know to make even the simplest example work, since this is the code that any more complicated function will also need.

So here is the C code for 'DoNothing', which we will put in a file called DoNothing.c:



Now let's look at this line by line. The first line loads the header file for LibraryLink. This header file is called WolframLibrary.h and is included with any Mathematica installation. It is located under $InstallationDirectory/SystemFiles/IncludeFiles/C and includes definitions to all
the LibraryLink functions that are available. 

The second line is the actual C function that will be called from the Wolfram Language. It starts with DLLEXPORT, which takes care of making the function visible/public so the Wolfram Language can access it. Omitting it will cause an error it you attempt to load the function from the library.

The next part of that line is 'int' which is the error return code. There are various types of error you can return, but if everything is OK you return the 'no error' code which is LIBRARY_NO_ERROR.

The name of the function can be anything you want it to be, but there are always four arguments required to this function. The first argument (WolframLibraryData libData) essentially takes care of all the bookkeeping of the data. It is needed even if you don't explicitly use it in your function. The second argument (Argc) is an integer which holds the number of arguments to your Wolfram Language function. The third argument is an array to the actual arguments passed from your Wolfram Language function.
The last argument can hold any data that needs to be returned as the result for your Wolfram Language function.

Note that in this very simple example, none of these arguments are explicitly used.

The second main part of adding a LibraryLink function to the WolframLanguage is done with Wolfram Language code itself. Here is the code to do this, in this case three lines of code:



The first line loads a package called CCompilerDriver which defines the CreateLibrary function used below it. The second line takes care of compiling your C code and creating the appropriate library in a place that can easily be found by the Wolfram Language. To see details on what goes on behind the scenes, just add the option "Debug"->True to this function and it will print out the compilation command and other useful information. The CreateLibrary function creates a library called 'DoNothing' (followed by a operating system appropriate filename extension).

The last line actually loads the library functions and sets it to the Wolfram Language function 'DoNothing'. The first argument to LibraryFunctionLoad refers to the library, the second argument to a function in the library, the third argument to the Wolfram Language function argument (no arguments in this simple case) and the last argument refers to the expected return expression type (Null or void in this simple case).

Now we can try running this code in the Wolfram Language:



Loading the DoNothing.m package will compile the C code, create the library and load the new function into the Wolfram Language. Next calling DoNothing[] with no arguments returns nothing (as it should in this case).

With this all figured out, we can now write a Hello World function with LibraryLink.