1 @cindex standards conformance, ANSI C
3 @cindex C extensions, compatible use of
5 This chapter describes how to compile programs that use GSL, and
6 introduces its conventions.
10 * Compiling and Linking::
15 * Portability functions::
16 * Alternative optimized functions::
17 * Support for different numeric types::
18 * Compatibility with C++::
19 * Aliasing of arrays::
21 * Deprecated Functions::
25 @node An Example Program
26 @section An Example Program
28 The following short program demonstrates the use of the library by
29 computing the value of the Bessel function @math{J_0(x)} for @math{x=5},
32 @verbatiminclude examples/intro.c
36 The output is shown below, and should be correct to double-precision
37 accuracy,@footnote{The last few digits may vary slightly depending on
38 the compiler and platform used---this is normal.}
41 @verbatiminclude examples/intro.out
45 The steps needed to compile this program are described
46 in the following sections.
48 @node Compiling and Linking
49 @section Compiling and Linking
50 @cindex compiling programs, include paths
51 @cindex including GSL header files
52 @cindex header files, including
53 The library header files are installed in their own @file{gsl}
54 directory. You should write any preprocessor include statements with a
55 @file{gsl/} directory prefix thus,
58 #include <gsl/gsl_math.h>
62 If the directory is not installed on the standard search path of your
63 compiler you will also need to provide its location to the preprocessor
64 as a command line flag. The default location of the @file{gsl}
65 directory is @file{/usr/local/include/gsl}. A typical compilation
66 command for a source file @file{example.c} with the GNU C compiler
70 $ gcc -Wall -I/usr/local/include -c example.c
74 This results in an object file @file{example.o}. The default
75 include path for @code{gcc} searches @file{/usr/local/include} automatically so
76 the @code{-I} option can actually be omitted when GSL is installed
77 in its default location.
80 * Linking programs with the library::
81 * Linking with an alternative BLAS library::
84 @node Linking programs with the library
85 @subsection Linking programs with the library
86 @cindex compiling programs, library paths
87 @cindex linking with GSL libraries
88 @cindex libraries, linking with
89 The library is installed as a single file, @file{libgsl.a}. A shared
90 version of the library @file{libgsl.so} is also installed on systems
91 that support shared libraries. The default location of these files is
92 @file{/usr/local/lib}. If this directory is not on the standard search
93 path of your linker you will also need to provide its location as a
96 To link against the library you need to specify
97 both the main library and a supporting @sc{cblas} library, which
98 provides standard basic linear algebra subroutines. A suitable
99 @sc{cblas} implementation is provided in the library
100 @file{libgslcblas.a} if your system does not provide one. The following
101 example shows how to link an application with the library,
104 $ gcc -L/usr/local/lib example.o -lgsl -lgslcblas -lm
108 The default library path for @code{gcc} searches @file{/usr/local/lib}
109 automatically so the @code{-L} option can be omitted when GSL is
110 installed in its default location.
112 @node Linking with an alternative BLAS library
113 @subsection Linking with an alternative BLAS library
115 The following command line shows how you would link the same application
116 with an alternative @sc{cblas} library called @file{libcblas},
119 $ gcc example.o -lgsl -lcblas -lm
123 For the best performance an optimized platform-specific @sc{cblas}
124 library should be used for @code{-lcblas}. The library must conform to
125 the @sc{cblas} standard. The @sc{atlas} package provides a portable
126 high-performance @sc{blas} library with a @sc{cblas} interface. It is
127 free software and should be installed for any work requiring fast vector
128 and matrix operations. The following command line will link with the
129 @sc{atlas} library and its @sc{cblas} interface,
132 $ gcc example.o -lgsl -lcblas -latlas -lm
136 For more information see @ref{BLAS Support}.
138 @comment The program @code{gsl-config} provides information on the local version
139 @comment of the library. For example, the following command shows that the
140 @comment library has been installed under the directory @file{/usr/local},
143 @comment $ gsl-config --prefix
145 @comment @end example
147 @comment Further information is available using the command @code{gsl-config --help}.
149 @node Shared Libraries
150 @section Shared Libraries
151 @cindex shared libraries
152 @cindex libraries, shared
153 @cindex LD_LIBRARY_PATH
154 To run a program linked with the shared version of the library the
155 operating system must be able to locate the corresponding @file{.so}
156 file at runtime. If the library cannot be found, the following error
161 ./a.out: error while loading shared libraries:
162 libgsl.so.0: cannot open shared object file: No such
167 To avoid this error, define the shell variable @code{LD_LIBRARY_PATH} to
168 include the directory where the library is installed.
170 For example, in the Bourne shell (@code{/bin/sh} or @code{/bin/bash}),
171 the library search path can be set with the following commands:
174 $ LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
175 $ export LD_LIBRARY_PATH
180 In the C-shell (@code{/bin/csh} or @code{/bin/tcsh}) the equivalent
184 % setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH
188 The standard prompt for the C-shell in the example above is the percent
189 character @samp{%}, and should not be typed as part of the command.
191 To save retyping these commands each session they should be placed in an
192 individual or system-wide login file.
194 To compile a statically linked version of the program, use the
195 @code{-static} flag in @code{gcc},
198 $ gcc -static example.o -lgsl -lgslcblas -lm
201 @node ANSI C Compliance
202 @section ANSI C Compliance
204 The library is written in ANSI C and is intended to conform to the ANSI
205 C standard (C89). It should be portable to any system with a working
208 The library does not rely on any non-ANSI extensions in the interface it
209 exports to the user. Programs you write using GSL can be ANSI
210 compliant. Extensions which can be used in a way compatible with pure
211 ANSI C are supported, however, via conditional compilation. This allows
212 the library to take advantage of compiler extensions on those platforms
215 When an ANSI C feature is known to be broken on a particular system the
216 library will exclude any related functions at compile-time. This should
217 make it impossible to link a program that would use these functions and
218 give incorrect results.
220 To avoid namespace conflicts all exported function names and variables
221 have the prefix @code{gsl_}, while exported macros have the prefix
224 @node Inline functions
225 @section Inline functions
227 @cindex inline functions
229 The @code{inline} keyword is not part of the original ANSI C standard
230 (C89) and the library does not export any inline function definitions by
231 default. However, the library provides optional inline versions of
232 performance-critical functions by conditional compilation. The inline
233 versions of these functions can be included by defining the macro
234 @code{HAVE_INLINE} when compiling an application,
237 $ gcc -Wall -c -DHAVE_INLINE example.c
241 If you use @code{autoconf} this macro can be defined automatically. If
242 you do not define the macro @code{HAVE_INLINE} then the slower
243 non-inlined versions of the functions will be used instead.
245 Note that the actual usage of the inline keyword is @code{extern
246 inline}, which eliminates unnecessary function definitions in @sc{gcc}.
247 If the form @code{extern inline} causes problems with other compilers a
248 stricter autoconf test can be used, see @ref{Autoconf Macros}.
253 In general, the algorithms in the library are written for double
254 precision only. The @code{long double} type is not supported for
257 One reason for this choice is that the precision of @code{long double}
258 is platform dependent. The IEEE standard only specifies the minimum
259 precision of extended precision numbers, while the precision of
260 @code{double} is the same on all platforms.
262 However, it is sometimes necessary to interact with external data in
263 long-double format, so the vector and matrix datatypes include
264 long-double versions.
266 It should be noted that in some system libraries the @code{stdio.h}
267 formatted input/output functions @code{printf} and @code{scanf} are
268 not implemented correctly for @code{long double}. Undefined or
269 incorrect results are avoided by testing these functions during the
270 @code{configure} stage of library compilation and eliminating certain
271 GSL functions which depend on them if necessary. The corresponding
272 line in the @code{configure} output looks like this,
275 checking whether printf works with long double... no
279 Consequently when @code{long double} formatted input/output does not
280 work on a given system it should be impossible to link a program which
281 uses GSL functions dependent on this.
283 If it is necessary to work on a system which does not support formatted
284 @code{long double} input/output then the options are to use binary
285 formats or to convert @code{long double} results into @code{double} for
288 @node Portability functions
289 @section Portability functions
291 To help in writing portable applications GSL provides some
292 implementations of functions that are found in other libraries, such as
293 the BSD math library. You can write your application to use the native
294 versions of these functions, and substitute the GSL versions via a
295 preprocessor macro if they are unavailable on another platform.
297 For example, after determining whether the BSD function @code{hypot} is
298 available you can include the following macro definitions in a file
299 @file{config.h} with your application,
302 /* Substitute gsl_hypot for missing system hypot */
305 #define hypot gsl_hypot
310 The application source files can then use the include command
311 @code{#include <config.h>} to replace each occurrence of @code{hypot} by
312 @code{gsl_hypot} when @code{hypot} is not available. This substitution
313 can be made automatically if you use @code{autoconf}, see @ref{Autoconf
316 In most circumstances the best strategy is to use the native versions of
317 these functions when available, and fall back to GSL versions otherwise,
318 since this allows your application to take advantage of any
319 platform-specific optimizations in the system library. This is the
320 strategy used within GSL itself.
322 @node Alternative optimized functions
323 @section Alternative optimized functions
325 @cindex alternative optimized functions
326 @cindex optimized functions, alternatives
327 The main implementation of some functions in the library will not be
328 optimal on all architectures. For example, there are several ways to
329 compute a Gaussian random variate and their relative speeds are
330 platform-dependent. In cases like this the library provides alternative
331 implementations of these functions with the same interface. If you
332 write your application using calls to the standard implementation you
333 can select an alternative version later via a preprocessor definition.
334 It is also possible to introduce your own optimized functions this way
335 while retaining portability. The following lines demonstrate the use of
336 a platform-dependent choice of methods for sampling from the Gaussian
341 #define gsl_ran_gaussian gsl_ran_gaussian_ratio_method
344 #define gsl_ran_gaussian my_gaussian
349 These lines would be placed in the configuration header file
350 @file{config.h} of the application, which should then be included by all
351 the source files. Note that the alternative implementations will not
352 produce bit-for-bit identical results, and in the case of random number
353 distributions will produce an entirely different stream of random
356 @node Support for different numeric types
357 @section Support for different numeric types
359 Many functions in the library are defined for different numeric types.
360 This feature is implemented by varying the name of the function with a
361 type-related modifier---a primitive form of C++ templates. The
362 modifier is inserted into the function name after the initial module
363 prefix. The following table shows the function names defined for all
364 the numeric types of an imaginary module @code{gsl_foo} with function
369 gsl_foo_long_double_fn long double
370 gsl_foo_float_fn float
372 gsl_foo_ulong_fn unsigned long
374 gsl_foo_uint_fn unsigned int
375 gsl_foo_short_fn short
376 gsl_foo_ushort_fn unsigned short
378 gsl_foo_uchar_fn unsigned char
382 The normal numeric precision @code{double} is considered the default and
383 does not require a suffix. For example, the function
384 @code{gsl_stats_mean} computes the mean of double precision numbers,
385 while the function @code{gsl_stats_int_mean} computes the mean of
388 A corresponding scheme is used for library defined types, such as
389 @code{gsl_vector} and @code{gsl_matrix}. In this case the modifier is
390 appended to the type name. For example, if a module defines a new
391 type-dependent struct or typedef @code{gsl_foo} it is modified for other
392 types in the following way,
396 gsl_foo_long_double long double
399 gsl_foo_ulong unsigned long
401 gsl_foo_uint unsigned int
403 gsl_foo_ushort unsigned short
405 gsl_foo_uchar unsigned char
409 When a module contains type-dependent definitions the library provides
410 individual header files for each type. The filenames are modified as
411 shown in the below. For convenience the default header includes the
412 definitions for all the types. To include only the double precision
413 header file, or any other specific type, use its individual filename.
416 #include <gsl/gsl_foo.h> All types
417 #include <gsl/gsl_foo_double.h> double
418 #include <gsl/gsl_foo_long_double.h> long double
419 #include <gsl/gsl_foo_float.h> float
420 #include <gsl/gsl_foo_long.h> long
421 #include <gsl/gsl_foo_ulong.h> unsigned long
422 #include <gsl/gsl_foo_int.h> int
423 #include <gsl/gsl_foo_uint.h> unsigned int
424 #include <gsl/gsl_foo_short.h> short
425 #include <gsl/gsl_foo_ushort.h> unsigned short
426 #include <gsl/gsl_foo_char.h> char
427 #include <gsl/gsl_foo_uchar.h> unsigned char
430 @node Compatibility with C++
431 @section Compatibility with C++
432 @cindex C++, compatibility
433 @cindex exceptions, C++
434 The library header files automatically define functions to have
435 @code{extern "C"} linkage when included in C++ programs. This allows
436 the functions to be called directly from C++.
438 To use C++ exception handling within user-defined functions passed to
439 the library as parameters, the library must be built with the
440 additional @code{CFLAGS} compilation option @option{-fexceptions}.
442 @node Aliasing of arrays
443 @section Aliasing of arrays
444 @cindex aliasing of arrays
445 The library assumes that arrays, vectors and matrices passed as
446 modifiable arguments are not aliased and do not overlap with each other.
447 This removes the need for the library to handle overlapping memory
448 regions as a special case, and allows additional optimizations to be
449 used. If overlapping memory regions are passed as modifiable arguments
450 then the results of such functions will be undefined. If the arguments
451 will not be modified (for example, if a function prototype declares them
452 as @code{const} arguments) then overlapping or aliased memory regions
456 @section Thread-safety
458 The library can be used in multi-threaded programs. All the functions
459 are thread-safe, in the sense that they do not use static variables.
460 Memory is always associated with objects and not with functions. For
461 functions which use @dfn{workspace} objects as temporary storage the
462 workspaces should be allocated on a per-thread basis. For functions
463 which use @dfn{table} objects as read-only memory the tables can be used
464 by multiple threads simultaneously. Table arguments are always declared
465 @code{const} in function prototypes, to indicate that they may be
466 safely accessed by different threads.
468 There are a small number of static global variables which are used to
469 control the overall behavior of the library (e.g. whether to use
470 range-checking, the function to call on fatal error, etc). These
471 variables are set directly by the user, so they should be initialized
472 once at program startup and not modified by different threads.
474 @node Deprecated Functions
475 @section Deprecated Functions
476 @cindex deprecated functions
478 From time to time, it may be necessary for the definitions of some
479 functions to be altered or removed from the library. In these
480 circumstances the functions will first be declared @dfn{deprecated} and
481 then removed from subsequent versions of the library. Functions that
482 are deprecated can be disabled in the current release by setting the
483 preprocessor definition @code{GSL_DISABLE_DEPRECATED}. This allows
484 existing code to be tested for forwards compatibility.
488 @cindex code reuse in applications
489 @cindex source code, reuse in applications
490 Where possible the routines in the library have been written to avoid
491 dependencies between modules and files. This should make it possible to
492 extract individual functions for use in your own applications, without
493 needing to have the whole library installed. You may need to define
494 certain macros such as @code{GSL_ERROR} and remove some @code{#include}
495 statements in order to compile the files as standalone units. Reuse of
496 the library code in this way is encouraged, subject to the terms of the
497 GNU General Public License.