usage.texi

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY without ev

@cindex standards conformance, ANSI C
@cindex ANSI C, use of
@cindex C extensions, compatible use of
@cindex compatibility
This chapter describes how to compile programs that use GSL, and
introduces its conventions.  

@menu
* An Example Program::          
* Compiling and Linking::       
* Shared Libraries::            
* ANSI C Compliance::           
* Inline functions::            
* Long double::                 
* Portability functions::       
* Alternative optimized functions::  
* Support for different numeric types::  
* Compatibility with C++::      
* Aliasing of arrays::          
* Thread-safety::               
* Deprecated Functions::        
* Code Reuse::                  
@end menu

@node   An Example Program
@section An Example Program

The following short program demonstrates the use of the library by
computing the value of the Bessel function @math{J_0(x)} for @math{x=5},

@example
@verbatiminclude examples/intro.c
@end example

@noindent
The output is shown below, and should be correct to double-precision
accuracy,

@example
@verbatiminclude examples/intro.out
@end example

@noindent
The steps needed to compile this program are described in the following
sections.

@node Compiling and Linking
@section Compiling and Linking
@cindex compiling programs, include paths
@cindex including GSL header files
@cindex header files, including
The library header files are installed in their own @file{gsl}
directory.  You should write any preprocessor include statements with a
@file{gsl/} directory prefix thus,

@example
#include <gsl/gsl_math.h>
@end example

@noindent
If the directory is not installed on the standard search path of your
compiler you will also need to provide its location to the preprocessor
as a command line flag.  The default location of the @file{gsl}
directory is @file{/usr/local/include/gsl}.  A typical compilation
command for a source file @file{example.c} with the GNU C compiler
@code{gcc} is,

@example
$ gcc -Wall -I/usr/local/include -c example.c
@end example

@noindent
This results in an object file @file{example.o}.   The default
include path for @code{gcc} searches @file{/usr/local/include} automatically so
the @code{-I} option can actually be omitted when GSL is installed 
in its default location.

@menu
* Linking programs with the library::  
* Linking with an alternative BLAS library::  
@end menu

@node Linking programs with the library
@subsection Linking programs with the library
@cindex compiling programs, library paths
@cindex linking with GSL libraries
@cindex libraries, linking with
The library is installed as a single file, @file{libgsl.a}.  A shared
version of the library @file{libgsl.so} is also installed on systems
that support shared libraries.  The default location of these files is
@file{/usr/local/lib}.  If this directory is not on the standard search
path of your linker you will also need to provide its location as a
command line flag.

To link against the library you need to specify
both the main library and a supporting @sc{cblas} library, which
provides standard basic linear algebra subroutines.  A suitable
@sc{cblas} implementation is provided in the library
@file{libgslcblas.a} if your system does not provide one.  The following
example shows how to link an application with the library,

@example
$ gcc -L/usr/local/lib example.o -lgsl -lgslcblas -lm
@end example

@noindent
The default library path for @code{gcc} searches @file{/usr/local/lib}
automatically so the @code{-L} option can be omitted when GSL is
installed in its default location.

@node Linking with an alternative BLAS library
@subsection Linking with an alternative BLAS library

The following command line shows how you would link the same application
with an alternative @sc{cblas} library called @file{libcblas},

@example
$ gcc example.o -lgsl -lcblas -lm
@end example

@noindent
For the best performance an optimized platform-specific @sc{cblas}
library should be used for @code{-lcblas}.  The library must conform to
the @sc{cblas} standard.  The @sc{atlas} package provides a portable
high-performance @sc{blas} library with a @sc{cblas} interface.  It is
free software and should be installed for any work requiring fast vector
and matrix operations.  The following command line will link with the
@sc{atlas} library and its @sc{cblas} interface,

@example
$ gcc example.o -lgsl -lcblas -latlas -lm
@end example

@noindent
For more information see @ref{BLAS Support}.

@comment  The program @code{gsl-config} provides information on the local version
@comment  of the library.  For example, the following command shows that the
@comment  library has been installed under the directory @file{/usr/local},

@comment  @example
@comment  $ gsl-config --prefix
@comment  /usr/local
@comment  @end example
@comment  @noindent
@comment  Further information is available using the command @code{gsl-config --help}.

@node Shared Libraries
@section Shared Libraries
@cindex shared libraries
@cindex libraries, shared
@cindex LD_LIBRARY_PATH
To run a program linked with the shared version of the library the
operating system must be able to locate the corresponding @file{.so}
file at runtime.  If the library cannot be found, the following error
will occur:

@example
$ ./a.out 
./a.out: error while loading shared libraries: 
libgsl.so.0: cannot open shared object file: No such 
file or directory
@end example

@noindent
To avoid this error, define the shell variable @code{LD_LIBRARY_PATH} to
include the directory where the library is installed.

For example, in the Bourne shell (@code{/bin/sh} or @code{/bin/bash}),
the library search path can be set with the following commands:

@example
$ LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH 
$ export LD_LIBRARY_PATH
$ ./example
@end example

@noindent
In the C-shell (@code{/bin/csh} or @code{/bin/tcsh}) the equivalent
command is,

@example
% setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH
@end example

@noindent
The standard prompt for the C-shell in the example above is the percent
character @samp{%}, and should not be typed as part of the command.

To save retyping these commands each session they should be placed in an
individual or system-wide login file.

To compile a statically linked version of the program, use the
@code{-static} flag in @code{gcc},

@example
$ gcc -static example.o -lgsl -lgslcblas -lm
@end example

@node ANSI C Compliance
@section ANSI C Compliance

The library is written in ANSI C and is intended to conform to the ANSI
C standard (C89).  It should be portable to any system with a working
ANSI C compiler.

The library does not rely on any non-ANSI extensions in the interface it
exports to the user.  Programs you write using GSL can be ANSI
compliant.  Extensions which can be used in a way compatible with pure
ANSI C are supported, however, via conditional compilation.  This allows
the library 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 at compile-time.  This should
make it impossible to link a program that would use these functions and
give incorrect results.

To avoid namespace conflicts all exported function names and variables
have the prefix @code{gsl_}, while exported macros have the prefix
@code{GSL_}.

@node Inline functions
@section Inline functions

@cindex inline functions
@cindex HAVE_INLINE
The @code{inline} keyword is not part of the original ANSI C standard
(C89) and the library does not export any inline function definitions by
default. However, the library provides optional inline versions of
performance-critical functions by conditional compilation.  The inline
versions of these functions can be included by defining the macro
@code{HAVE_INLINE} when compiling an application,

@example
$ gcc -Wall -c -DHAVE_INLINE example.c
@end example

@noindent
If you use @code{autoconf} this macro can be defined automatically.  If
you do not define the macro @code{HAVE_INLINE} then the slower
non-inlined versions of the functions will be used instead.

Note that the actual usage of the inline keyword is @code{extern
inline}, which eliminates unnecessary function definitions in @sc{gcc}.