{{lastupdated_at}} by {{lastupdated_by}} {{>toc}} h1. GammaLib directory structure This page explains the directory structure of GammaLib. Note that this description applies to the directory that is obtained by cloning the Git repository. For a source code release, Python wrapper files will be present, and also some documentation will be shipped in pdf format. The directory structure of a source code release will thus differ in details. The directory structure is shown here as it would appear using the @ls -la@ command on a Linux machine. Note that file sizes may differ for your actual copy of the source code as the software evolves. h2. GammaLib directory The @gammalib@ directory after cloning from the GammaLib Git repository will have the following content:
drwxr-xr-x 13 jurgen staff 442 12 oct 21:35 .git <= Git information -rw-r--r-- 1 jurgen staff 218 12 oct 21:35 AUTHORS -rw-r--r-- 1 jurgen staff 35146 12 oct 21:35 COPYING -rw-r--r-- 1 jurgen staff 6358 12 oct 21:35 ChangeLog -rw-r--r-- 1 jurgen staff 11397 12 oct 21:35 INSTALL -rw-r--r-- 1 jurgen staff 6139 12 oct 21:35 Makefile.am <- automake input file -rw-r--r-- 1 jurgen staff 2770 12 oct 21:35 NEWS -rw-r--r-- 1 jurgen staff 11606 12 oct 21:35 README -rwxr-xr-x 1 jurgen staff 228 12 oct 21:35 autogen.sh <- autotools generation script -rw-r--r-- 1 jurgen staff 52654 12 oct 21:35 configure.ac <- autoconf input file drwxr-xr-x 9 jurgen staff 306 12 oct 21:35 dev <= code development utilities drwxr-xr-x 8 jurgen staff 272 12 oct 21:35 doc <= GammaLib documentation drwxr-xr-x 3 jurgen staff 102 12 oct 21:35 examples <= GammaLib usage examples -rw-r--r-- 1 jurgen staff 397 12 oct 21:35 gammalib.pc.in <- pkgconfig input file drwxr-xr-x 129 jurgen staff 4386 12 oct 21:35 include <= include files for instrument independent code drwxr-xr-x 6 jurgen staff 204 12 oct 21:35 inst <= instrument dependent code drwxr-xr-x 12 jurgen staff 408 12 oct 21:35 m4 <= autoconf macros drwxr-xr-x 128 jurgen staff 4352 12 oct 21:35 pyext <= Python binding definition files (for swig) drwxr-xr-x 18 jurgen staff 612 12 oct 21:35 src <= instrument independent code drwxr-xr-x 52 jurgen staff 1768 12 oct 21:35 test <= code for unit testing -rwxr-xr-x 1 jurgen staff 1418 12 oct 21:35 testall.sh <- extended test scriptGammaLib uses autotools for configuration (see below). There are two central input files that will be used by autotools: @Makefile.am@ will be used to generate @Makefile@, which is the script invoked by the @make@ command. @configure.ac@ will be used to generate @configure@, which is the script that is called for configuration of the software prior to compilation. GammaLib supports the "pkg-config helper system":http://www.freedesktop.org/wiki/Software/pkg-config. The file @gammalib.pc.in@ will be used to generate @gammalib.pc@ using the autotools. In the following, the subdirectories of the @gammalib@ directory are described. h2. dev The @dev@ directory contains are couple of scripts and files that are useful for GammaLib development and GammaLib release. Most developers will not need to use one of these scripts. Below the content of the @dev@ directory:
-rw-r--r-- 1 jurgen staff 925 12 oct 21:35 license_new.txt <- New license text (used by replace_license.py) -rw-r--r-- 1 jurgen staff 308 12 oct 21:35 license_old.txt <- Old license text (used by replace_license.py) -rwxr-xr-x 1 jurgen staff 5122 12 oct 21:35 macosx_package.sh <- Create a GammaLib / ctools binary for packaging -rwxr-xr-x 1 jurgen staff 13654 12 oct 21:35 macosx_testconf.sh <- Tests GammaLib under various Mac OS X configurations -rwxr-xr-x 1 jurgen staff 12016 12 oct 21:35 macosx_testpkg.sh <- Tests GammaLib / ctools Mac OS X package prior to release -rwxr-xr-x 1 jurgen staff 2997 12 oct 21:35 release_gammalib.sh <- Create a GammaLib release -rwxr-xr-x 1 jurgen staff 2586 12 oct 21:35 replace_license.py <- Replace license text in all source and include filesh2. doc The @doc@ directory contains the GammaLib documentation. Here the content of the directory:
-rw-r--r-- 1 jurgen staff 57183 12 oct 21:35 Doxyfile <- Configuration file for generation of Doxygen documentation drwxr-xr-x 8 jurgen staff 272 12 oct 21:35 dev <= Development documentation drwxr-xr-x 14 jurgen staff 476 12 oct 21:35 html <= Web documentation drwxr-xr-x 3 jurgen staff 102 12 oct 21:35 um <= User ManualGammaLib uses Doxygen to generate the reference documentation. The file @Doxyfile@ contains the Doxygen configuration that is applied for this generation. The @dev@ directory contains all documentation that is relevant for code development. It contains a number of subdirectories, one for each development document (except of the @tn@ directory which contains all technical notes of the project). Here the actual content of @dev@:
drwxr-xr-x 4 jurgen staff 136 12 oct 21:35 coding <= Coding and Design Conventions drwxr-xr-x 7 jurgen staff 238 12 oct 21:35 inst <= Instrument specific interface drwxr-xr-x 5 jurgen staff 170 12 oct 21:35 maths <= Mathematical Implementation drwxr-xr-x 6 jurgen staff 204 12 oct 21:35 sdd <= Software Design Description drwxr-xr-x 4 jurgen staff 136 12 oct 21:35 srs <= Software Requirement Specification drwxr-xr-x 4 jurgen staff 136 12 oct 21:35 tn <= Technical NotesThe @html@ directory contains all Web documentation of GammaLib. The Web documentation is published at the following sourceforge site: http://gammalib.sourceforge.net/ The @um@ directory contains the User Manual for GammaLib. *Note that much of the documentation is not up to date.* The only document that can be considered reasonably complete are the "Coding and Design Conventions". h2. examples This directory contains example code that illustrates the usage of GammaLib. So far, only a single example named @readmodel@ exists. To compile this example, step into the @examples/readmodel@ directory and type
$ makeNote that GammaLib needs to be installed prior to compilation. Also, the @Makefile@ assumes that GammaLib has been installed in the path @/usr/local/gamma@. If GammaLib is installed in a different location, please adjust the @Makefile@. h2. include The @include@ directory contains all instrument independent header files for GammaLib. The directory is flat, i.e. no structuration into modules exists. To add a new class to GammaLib, simply add a header file to this directory. Add the name of the header file also to the @Makefile.am@ script, and add a
#include "GClass.hpp"directive to @GammaLib.hpp@ to include the new header in the GammaLib master header file (in this example we supposed that the new header file is named @GClass.hpp@). h2. inst This directory contains the instrument specific source code. There is one directory per instrument. The @Makefile.am@ gathers information for all subdirectories, and it is one of the files that needs to be adapted when a new instrument should be added. A typical instrument specific directory has the following structure (here the example of @cta@):
-rw-r--r-- 1 jurgen staff 2732 12 oct 21:35 Makefile.am <- automake input file drwxr-xr-x 15 jurgen staff 510 12 oct 21:35 caldb <= calibration data drwxr-xr-x 21 jurgen staff 714 12 oct 21:35 include <= include files drwxr-xr-x 20 jurgen staff 680 12 oct 21:35 pyext <= Python binding definition files (for swig) drwxr-xr-x 24 jurgen staff 816 12 oct 21:35 src <= source code drwxr-xr-x 18 jurgen staff 612 12 oct 21:35 test <= code for unit testingThe @Makefile.am@ is the input file that will be used by automake to generate a @Makefile@. This file needs to be modified if code is added to the interface. The structure of the @caldb@ directory depends strongly on the instrument. The data contained in this directory will be used for unit testing, and will be installed together with the software. The @include@ directory is a flat directory, containing all header files for the instrument dependent code. It's structure is similar to the @include@ directory of the instrument independent code. Instead of the @GammaLib.hpp@ file (which gathers all headers for the instrument independent code), a file gathering all headers for the instrument dependent code will exist (for CTA this file is named @GCTALib.hpp@). The @pyext@ directory is a flat directory, containing all interface files that will be processed by @swig@ to create the Python wrapper files. There is one interface file for each class. All interface files a gathered in a summary file (for CTA this file is named @cta.i@). If a class interface should be added it is sufficient to add the respective file to the summary file. The @src@ directory is a flat directory, containing all source code. The @test@ directory contains all code and data needed for unit testing. In addition, it may contain an (arbitrary) number of test scripts and programs that are useful for testing the functionalities of the instrument specific interface. Here the example for the @cta@ interface:
-rw-r--r-- 1 jurgen staff 982 12 oct 21:35 README drwxr-xr-x 14 jurgen staff 476 12 oct 21:35 data -rwxr-xr-x 1 jurgen staff 2338 12 oct 21:35 example_binned_ml_fit.py -rwxr-xr-x 1 jurgen staff 1672 12 oct 21:35 example_make_model.py -rwxr-xr-x 1 jurgen staff 3889 12 oct 21:35 example_sim_photons.py -rw-r--r-- 1 jurgen staff 20474 12 oct 21:35 test_CTA.cpp -rw-r--r-- 1 jurgen staff 3868 12 oct 21:35 test_CTA.hpp -rwxr-xr-x 1 jurgen staff 1578 12 oct 21:35 test_CTA.py -rwxr-xr-x 1 jurgen staff 1998 12 oct 21:35 test_gauss.py -rwxr-xr-x 1 jurgen staff 5056 12 oct 21:35 test_irf_offset.py -rwxr-xr-x 1 jurgen staff 1561 12 oct 21:35 test_irf_trafo.py -rwxr-xr-x 1 jurgen staff 6408 12 oct 21:35 test_model.py -rwxr-xr-x 1 jurgen staff 3388 12 oct 21:35 test_npred_computation.py -rwxr-xr-x 1 jurgen staff 3492 12 oct 21:35 test_npred_intergation.py -rwxr-xr-x 1 jurgen staff 2393 12 oct 21:35 test_radial_acceptance.py -rwxr-xr-x 1 jurgen staff 1944 12 oct 21:35 test_response_table.pyThe @README@ file contains more information about the various test files that exist in this directory. The @data@ directory contains data needed for unit testing. The files @test_CTA.cpp@ and @test_CTA.hpp@ are used for unit testing of the C++ code, the file @test_CTA.py@ is used for unit testing of the Python interface. h2. m4 This directory contains autoconf macros. Some of the macros are actually used by the @configure@ script during testing of the system configuration, other macros are still there for legacy. In case you need to add a test to the @configure@ script that makes use of a non-standard macro, please add the macro to this folder to make sure that it will be available during the configuration step. h2. pyext The @pyext@ directory contains all interface files that will be processed by @swig@ to create the Python wrapper files. There is one interface file for each class. All these files are directly located in the @pyext@ directory. The Python interface is organized into modules, mainly to reduce the size of the Python wrapper code. The definitions of the modules are found in the @gammalib@ subdirectory, which has the following content:
-rw-r--r-- 1 jurgen staff 2194 12 oct 21:35 app.i -rw-r--r-- 1 jurgen staff 3024 12 oct 21:35 fits.i -rw-r--r-- 1 jurgen staff 2234 12 oct 21:35 linalg.i -rw-r--r-- 1 jurgen staff 3101 12 oct 21:35 model.i -rw-r--r-- 1 jurgen staff 2209 12 oct 21:35 numerics.i -rw-r--r-- 1 jurgen staff 2543 12 oct 21:35 obs.i -rw-r--r-- 1 jurgen staff 2225 12 oct 21:35 opt.i -rw-r--r-- 1 jurgen staff 2348 12 oct 21:35 sky.i -rw-r--r-- 1 jurgen staff 2070 12 oct 21:35 support.i -rw-r--r-- 1 jurgen staff 2186 12 oct 21:35 test.i -rw-r--r-- 1 jurgen staff 2298 12 oct 21:35 xml.iEach of these files is a summary file for one module. By means of @%include@ directives, each summary file includes the interface files that should be gathered into the module. If a new class should be added to a module you have to add an @%include@ directive to the respective module. Please make sure that a given interface file is not included in several modules. The @pyext@ directory contains a @Makefile.am@ that defines how the modules will be built. The files needs to be modified when a new module (or a new instrument) should be added. If a new class is added to an existing module, no modification is required. The directory also contains a file @setup.py.in@ that is used for building and installing the Python wrappers. This file will be converted into a file @setup.py@ by the configuration step. The files needs to be modified when a new module (or a new instrument) should be added. If a new class is added to an existing module, no modification is required. h2. src The @src@ directory is where all instrument independent source code lives. The directory has the following content:
-rw-r--r-- 1 jurgen staff 2074 12 oct 21:35 Makefile.am drwxr-xr-x 8 jurgen staff 272 12 oct 21:35 app drwxr-xr-x 36 jurgen staff 1224 12 oct 21:35 fits -rwxr-xr-x 1 jurgen staff 814 12 oct 21:35 gammalib-init.csh -rwxr-xr-x 1 jurgen staff 793 12 oct 21:35 gammalib-init.sh -rw-r--r-- 1 jurgen staff 5636 12 oct 21:35 gammalib-setup.in drwxr-xr-x 13 jurgen staff 442 12 oct 21:35 linalg drwxr-xr-x 35 jurgen staff 1190 12 oct 21:35 model drwxr-xr-x 8 jurgen staff 272 12 oct 21:35 numerics drwxr-xr-x 25 jurgen staff 850 12 oct 21:35 obs drwxr-xr-x 7 jurgen staff 238 12 oct 21:35 opt drwxr-xr-x 15 jurgen staff 510 12 oct 21:35 sky drwxr-xr-x 8 jurgen staff 272 12 oct 21:35 support drwxr-xr-x 4 jurgen staff 136 12 oct 21:35 template drwxr-xr-x 7 jurgen staff 238 12 oct 21:35 test drwxr-xr-x 12 jurgen staff 408 12 oct 21:35 xmlEach subdirectory presents a specific module. As example, the content of the @app@ subdirectory is
-rw-r--r-- 1 jurgen staff 20078 12 oct 21:35 GApplication.cpp -rw-r--r-- 1 jurgen staff 8383 12 oct 21:35 GException_app.cpp -rw-r--r-- 1 jurgen staff 26817 12 oct 21:35 GLog.cpp -rw-r--r-- 1 jurgen staff 32253 12 oct 21:35 GPar.cpp -rw-r--r-- 1 jurgen staff 39490 12 oct 21:35 GPars.cpp -rw-r--r-- 1 jurgen staff 499 12 oct 21:35 Makefile.amThese directories contain the code for all GammaLib classes. Typically, there is one file per class. The @Makefile.am@ in these subdirectories gather the names of all files that need be compiled. If a new file is added to the subdirectory, @Makefile.am@ needs to be updated. Often, the subdirectories contain a file named @GException_xxx.cpp@, where @xxx@ is the name of the module. This file implements the exception classes that are relevant for this module. The definition of these exception classes are found in the file @GException.hpp@, situated in the @gammalib/include@ directory. The @src@ directory also contains a @Makefile.am@ which gathers informations about all modules and instrument interfaces that are present. If a module is added ot if a new instrument interface is added, this file needs to be modified. Finally, the @src@ directory contains the scripts @gammalib-init.csh@, @gammalib-init.sh@, and @gammalib-setup.in@. These scripts will be installed in the @bin@ directory of the GammaLib installation, and will serve to configure the GammaLib environment. If modifications to the environment are required, the file @gammalib-setup.in@ should be changed. h2. test The @test@ directory contains all code and data that are needed for unit testing. In addition, it may contain any kind of script that is useful for testing some functionalities of GammaLib. Here is a selected list of files or folders that are present in the directory:
-rw-r--r-- 1 jurgen staff 5513 12 oct 21:35 Makefile.am <- automake input file -rw-r--r-- 1 jurgen staff 755 12 oct 21:35 README drwxr-xr-x 7 jurgen staff 238 12 oct 21:35 data <= test data directory drwxr-xr-x 3 jurgen staff 102 12 oct 21:35 reports <= test reports directory -rw-r--r-- 1 jurgen staff 4960 12 oct 21:35 test_GApplication.cpp <- source code for C++ module test -rw-r--r-- 1 jurgen staff 2454 12 oct 21:35 test_GApplication.hpp <- header file for C++ module test -rwxr-xr-x 1 jurgen staff 4115 12 oct 21:35 test_GApplication.py <- script for Python module test drwxr-xr-x 13 jurgen staff 442 12 oct 21:35 testinst <= Instrument for testing of instrument interfaceThe @Makefile.am@ file is the input file from which automake will generate a @Makefile@. This @Makefile@ will be executed when @make check@ is invoked. If a new module or a new instrument is added, this file needs to be modified. For each module there is a C++ source code file, a C++ header file and a Python script. These files will be used during @make check@ to perform the C++ and Python unit tests for a given module. The @testinst@ directory implements a test instrument that is used to test the instrument interface. The test instrument is realized by header files only, hence no compilation is performed. To include the test instrument in any unit test, the @testinst/GTestLib.hpp@ file needs to be included in the test. See @test_GObservation.cpp@ for an example.