12.1.3 Summary and example on libraries ¶

After the mostly abstract discussions of Headers and Linking, we will give a small tutorial here. But before that, let’s recall the general steps of how your source code is prepared, compiled and linked to the libraries it depends on so you can run it:

1. The preprocessor includes the header (.h) files into the function definition (.c) files, expands preprocessor macros. Generally the preprocessor prepares the human-readable source for compilation (reviewed in Headers).
2. The compiler will translate (compile) the human-readable contents of each source (merged .c and the .h files, or generally the output of the preprocessor) into the computer-readable code of .o files.
3. The linker will link the called function definitions from various compiled files to create one unified object. When the unified product has a main function, this function is the product’s only entry point, enabling the operating system or user to directly interact with it, so the product is a program. When the product does not have a main function, the linker’s product is a library and it is exported functions can be linked to other executables (it has many entry points).

The GNU Compiler Collection (or GCC for short) will do all three steps. So as a first example, from Gnuastro’s source, go to tests/lib/. This directory contains the library tests, you can use these as some simple tutorials. For this demonstration, we will compile and run the arraymanip.c. This small program will call Gnuastro library for some simple operations on an array (open it and have a look). To compile this program, run this command inside the directory containing it.

$ gcc arraymanip.c -lgnuastro -lm -o arraymanip

The two -lgnuastro and -lm options (in this order) tell GCC to first link with the Gnuastro library and then with C’s math library. The -o option is used to specify the name of the output executable, without it the output file name will be a.out (on most OSs), independent of your input file name(s).

If your top Gnuastro installation directory (let’s call it $prefix, see Installation directory) is not recognized by GCC, you will get preprocessor errors for unknown header files. Once you fix it, you will get linker errors for undefined functions. To fix both, you should run GCC as follows: additionally telling it which directories it can find Gnuastro’s headers and compiled library (see Headers and Linking):

$ gcc -I$prefix/include -L$prefix/lib arraymanip.c -lgnuastro -lm     \
      -o arraymanip

This single command has done all the preprocessor, compilation and linker operations. Therefore no intermediate files (object files in particular) were created, only a single output executable was created. You are now ready to run the program with:

$ ./arraymanip

The Gnuastro functions called by this program only needed to be linked with the C math library. But if your program needs WCS coordinate transformations, needs to read a FITS file, needs special math operations (which include its linear algebra operations), or you want it to run on multiple CPU threads, you also need to add these libraries in the call to GCC: -lgnuastro -lwcs -lcfitsio -lgsl -lgslcblas -pthread -lm. In Gnuastro library, where each function is documented, it is mentioned which libraries (if any) must also be linked when you call a function. If you feel all these linkings can be confusing, please consider Gnuastro’s BuildProgram program.