usage.texi

GNU Scientific Library,C语言开发的数值方面的函数库

@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::               
* 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 be omitted when GSL is installed in its default
location.

@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 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.

The following command line shows how you would link the same application
with an alternative blas 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}.

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

@example
$ gsl-config --prefix
/usr/local
@end example
@noindent
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 it may be
necessary to 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 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.  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 ANSI C 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}.
If the form @code{extern inline} causes problems with other compilers a
stricter autoconf test can be used, see @ref{Autoconf Macros}.

@node Long double
@section Long double
@cindex long double
The extended numerical type @code{long double} is part of the ANSI C