This chapter describes how to compile programs that use GSL. The library is written in ANSI C and is intended to conform to the standard. The library does not make use of any extensions in the interface it exports to the user, except where they can be implemented in a way compatible with pure ANSI C. Thus programs you write using GSL should be portable to any system with a working ANSI C compiler but will also be able to take advantage of compiler extensions on those platforms which support them. When an ANSI C feature is known to be broken on a particular system the library will exclude any related functions so that it is impossible to link a program that would use them and give incorrect results.

Compiling and Linking
=====================

The library header files are installed in their own gsl directory. To include them you can write,

     #include <gsl/gsl_math.h>

and provide the appropriate path to the preprocessor where necessary. For example, if the files are installed in the default location of /usr/local/include then the command line,

     gcc -I/usr/local/include -c file.c

It is also possible to write #include <gsl_math.h> instead if you specify the full path to the directory as a compilation option.

The libraries themselves are also installed in a separate gsl directory. To link against the libraries you need to specify the location of this directory. For example, the following compilation options,

     gcc -L/usr/local/lib/gsl file.o -lgslspecfunc

would apply for a program using the libgslspecfunc.a special functions library installed in the default location. The individual libraries are interdependent and it is often necessary to link with several to provide all the necessary functions.

Inline functions
================

The inline keyword is not part of ANSI C, only C++. Since the library header files conform to the ANSI standard this prevents the use of inline. The library does not export any inline function definitions by default, but for some frequently used functions we provide equivalent inline definitions. These can be turned on by defining the macro HAVE_INLINE when compiling an application. If you use autoconf this can be done automatically using the following test,

     AC_C_INLINE

     if test "$ac_cv_c_inline" != no ; then
       AC_DEFINE(HAVE_INLINE,1)
       AC_SUBST(HAVE_INLINE)
     fi

and then including the file config.h before including any library headers.  If you do not define the macro HAVE_INLINE then the slower non-inlined versions of the functions are used instead.

Long double
===========

The extended numerical type long double is part of the ANSI C standard and should be available in every modern compiler.  However, the precision of long double is platform dependent, and this should be considered when using it. The IEEE standard only specifies the minimum precision of long double (extended precision), while double is the same on all platforms.

In some system libraries the stdio.h formatted input/output functions printf and scanf are not implemented correctly for long double. Undefined or incorrect results are avoided by testing these functions during the configure stage of library compilation and eliminating certain GSL functions which depend on them if necessary,

     checking whether printf/scanf works with long double... no

Consequently when long double formatted input/output does not work on a given system then it will not be possible to link a program which uses GSL functions relying on long double formatted i/o.

If it is necessary to work on a system which does not support formatted long double i/o then the options are to use binary formats or to convert long double results into double for reading and writing.

Alternative optimized functions
===============================

The implementation of some frequently-used functions may not be optimal on all architectures. For example, the routine for Gaussian random variates can be implemented using different algorithms (e.g. polar method or ratio method).  The relative speeds of the algorithms depend on different factors, so the choice of the fastest algorithm is platform-dependent. In these cases an alternate implementation of the function has been provided with exactly the same interface. If you write your application using calls to the standard implementations of the functions you can select the alternative versions later via a preprocessor macro. It is also possible to introduce your own optimized functions this way while retaining portability. For example,

     #ifdef SPARC
     #define gsl_ran_gaussian gsl_ran_gaussian_ratio_method
     #endif
     #ifdef INTEL
     #define gsl_ran_gaussian my_gaussian
     #endif

Note that the alternative implementations will not produce bit-for-bit identical results, and in the case of random number distributions will produce an entirely different stream of random variates.