GSL-- Documentation 0.11 Introduction. This package contains some C++ wrappers for the C API provided by the GNU Scientific library (GSL). Documentation The code it self is documented extensively. That is, the interfaces are explained. However, the underlying concepts - for example: what is `Simulated Annealing' - isn't explained. Please refer to the documentation that came with your GSL installation, and the references there in. The references in the GSL documentation are rather good, so I deemed it a bl**dy waste of time repeating it. The GSL documentation usally comes as info pages and a Postscript file. To read the info pages, do prompt> info gsl-ref or however you prefer to read info pages (Emacs!?). GSL-- does not come with info pages I'm afraid. That's because I use Doxygen, which currently can not export to Texinfo (however, it can export to LaTeX, so presumably, it shouldn't be that difficult to implement that in Doxygen :-). Using the class library Simply include the class declaration files you need in your code. The library provide three helper facilities to compile against the header files. One is the application gslmm-config which will report various features of GSL--. The second is an Autoconf macro AC_GLMM_PATH that will define GSLMM_CPPFLAGS in your make file. Use that with AM_CPPFLAGS to include the proper search path for the GSL-- header files. Finally, there a pkgconfig file that can be used in a similar way as the Autoconf macro. Organisation of the code As almost all of the classes are implemented as templates, the library mainly consists of header files. This has the advantage, that the user can easily select the level of optimisation and specialisation as needed. The header files generally live in a subdirectory that corresponds to the module that the class belongs to. So for example, all the fourier transformation classes live in the the subdirectory fourier. Note, that the complex number classes live in compleks rather than complex, as some older GCC version have a problem when you do # include (one of the ISO/IEC C++ header files). This means you should use a rather long path to include the header files into your code. For example, to include the histogram class header, you need to do #ifndef GSLMM_histogram #include <gslmm/histogram/histogram.hh> #endif The reason for this, is mainly maintainability, but it does provide a bit of clarity. Please also refer to the modules pages. Conding conventions. As far as possible, member functions are implmented as inline for speed optimisation. As far as possible, the classes are implmented as template specialisations. To make the specialisations, the headers use macro expansion to help do that. All classes are in the gslmm namespace, to pollute the users namespace as little as possible. Class and member names are in small letters, and words are sperated by an underscore. Data member names start with an underscore. Names are spelled out, so that they are easier to read. Specialisations and headers Many of the classes in this class library have explicit specialistions for double, float, int, long, and so on. To use these specialisations, include the proper header file in your code. For example, if you want to use complex number that has float values, you can do #ifndef GSLMM_complex_float #include <gslmm/compleks/complex_float.hh> #endif (The preprocessor guard is a common idiom to speed up compilation). Note, that these headers are automatically created at build time, using the corresponding _skel.hh file. In that way, I needn't duplicate the code for the specialisations, and still have seperate headers. The headers without an explicit type name in the file name, include all possible specialisations. For after #ifndef GSLMM_complex #inclucde <gslmm/compleks/complex.hh> #endif the specialisations gslmm::complex<double>, gslmm::complex<long double> and gslmm::complex<float> will be defined and can be used in the client application. There are also headers endinding in `_base.hh' - these are the base template declarations. For example #ifndef GSLMM_vector_base #inclucde <gslmm/vectormatrix/vector_base.hh> #endif will declare the template gslmm::vector<typename T, typname T1>, and although many of the member functions are defined, they do not use the GSL optimised functions. In other words, include these headers with care. The test As the library consists only of header files, and no compiled code, the only code that is compiled during installation are the various tests. This is to ensure that everything in fact works. Therefor it is highly recommended that you run the checks after building, that is you should run make check. All the tests supports the command line options -h that gives a short help message and -v that turns on verbose output from the tests (see also the class description of gslmm::test_suite). When I compile the tests, I usually invoke a slew of options to GCC (I'm currently using 2.95.4 and 3.2.2). These options are -fno-elide-constructors: Prevents Return Value Optimisation, which is an optional feature of the C++ standard -Werror: Do not allow warnings. -W: Give some more warnings -ansi -pedantic: Be strictly ANSI (ISO/IEC) compliant -Wnon-virtual-dtor: Be sure not to make un-inheritable classes -Weffc++: Warnings about style from Scott Meyer's book' - make nicer code. This option isn't invoked per default, as it would make the compilation fail. The reason is, that some of the libstdc++ from GCC does not follow the guidelines set forth by Scott Meyer. Therefor, this option is only invoked if the option --enable-effc++-warnings and --enable-maintainer-mode is given to the ./configure script. Another interesting option in this respect is --disable-Werror that suppresses the -Werror option to GCC. -Wold-style-cast: Warn about ugly C-style casts. Better code -Woverloaded-virtual: We want to overload - not hide, so the signatures should match.