This document describes several technical aspects of the source code distribution of the CAPD library. This library can be downloaded from the CAPD website at capd.ii.uj.edu.pl and is distributed under the terms of the GNU General Public License.
This document is divided into the following sections:
The initial version of this document was prepared by Pawel Pilarczyk on April 3-4, 2005.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License.
The system configurations for which the CAPD library is being developped, but not on all well tested, are listed below.
The system configurations in which the CAPD library is being developped, and therefore properly tested, are as follows:
Some other systems not mentioned above may also be supported without notice.
In order to compile the CAPD library, one can follow the steps listed below:
Since the number of library modules and related programs is quite large, be prepared for the compilation to take several minutes.
The files contained in the source code distribution of the CAPD library are split among the following subdirectories:
Important note: Since all the object files of the programs are stored in one directory, their names must be mutually different, even if they belong to different programs linked with the library.
Hint: It is possible to change the location where the results of compilation are stored. For this purpose it is enough to add the definitions of the BIN=, LIB= and OBJ= variables in the configuration file(s) found in the config subdirectory. See make/makedirs for the default values of these variables.
The source code of the CAPD library is grouped into modules which contain sets of header files and other source code files. Each module has its own subdirectory in the src directory and the name of this subdirectory is the name of the module. All the cpp files contained there are compiled into the corresponding module library called libcapdmodule, and all the cpp files from all the modules are also gathered in the library file libcapd. The header files of the module are located in the module's subdirectory of the include directory.
The following modules are currently available in the CAPD library:
Note that the above list of modules may change without notice, as the CAPD library is in continuous development.
The following files, all located in the make directory, are used to automatically compile the CAPD library and dependent programs:
Instead of compiling the entire CAPD library with all the programs, one can call make with arguments listed below for selective compilation, or other actions related to the compiled files:
Most of the files in the make directory are well commented. Reading them may give insight into more configuration possibilities.
Configuration files in the make/config directory define various system-dependent aspects of compilation. The following files are supplied in the CAPD source code distribution:
The variables defined in each configuration file contained in the make/config directory are described below. Some example settings are quoted in parentheses for clarity.
Groups of programs that use the CAPD library are located in one of the followind directories: examples, tests, programs, private. The latter directory is not included in the source code distribution, because it is supposed to keep the user's own programs which must be compiled with the CAPD library.
Each group of programs is gathered in a subdirectory of one of the directories mentioned above and is supplied with makefile. This file defines the following variables (space-separated lists):
Since the directory include alone is added to the compiler's search path for #include'd files, in the source code of the programs it is necessary to specify each module subdirectory explicitly.
The successful compilation of each progrm group requires that the corresponding libraries are compiled first. Moreover, the file makedeps is also necessary; it is generated and updated automatically by the program filedeps and it is silently skipped if the program bin/filedeps does not exist. The source code of the filedeps program with a corresponding makefile is contained in the utils/filedeps directory of the CAPD source code distribution and may be compiled by simply invoking the make command in that directory.
Note that due to the construction of the makefiles supplied with the CAPD library, the names of program groups must be mutually different, and also different from the module names.
While compiling a program that uses the CAPD library, it is necessary to add the include directory to the path at which the C++ compiler searches for files included with the #include directive. Moreover, it is necessary to link such a program with an appropriate library file, libcapd.a for instance. In order to achieve this with least effort, two solutions are proposed below.
After the CAPD library has been successfully compiled, one can install it in the system by copying the contents of the include directory to the system compiler's include directory, and the contents of the lib directory to the directory in which the system compiler's library files are located.
While linking programs that use the CAPD library, one must add a specific argument to the compiler command line to link these programs with the CAPD library (-l libcapd for GNU C++). Note that in some cases other libraries must be linked with as well; see the SYSLIB and SYSLIBG variables in the corresponding file in the make/config directory for a hint.
If one does not want to interfere the system C++ compiler, a convenient solution for the automated compilation of the user's programs is already built in the CAPD library makefiles. In order to use this solution, the user should create the subdirectory private in the main CAPD directory, and put groups of programs in its subdirectories (e.g., private/lorenz3d). Note that the source code files in each group of programs should consist of files with the .cpp extension, and, optionally, some other files as well (e.g., header files).
The user must create makefile and list all the .cpp files which give rise to programs (i.e., contain the main function) in the PROGS variable, and all the other .cpp files with which these programs should be linked—in the OTHERS variable. The last line of makefile should include ../../make/makeprog. Some other variables may also be defined there, and they are described in the previous section. Please, see the makefiles contained in the examples, tests and programs subdirectories for specific examples.
Now it is enough to type make (or make target=TARGET) in the program group's subdirectory to compile these programs and link them with the CAPD library. The program groups located in the private directory are also automatically compiled if the entire CAPD library is compiled with all its components by typing make (or make target=TARGET) in the make directory of CAPD.
Note that in order to be able to use this way of automated compilation of one's programs, one must first compile the filedeps program which generates a file makedeps for each group of programs. The source code of the filedeps program with a corresponding makefile is located in the utils/filedeps subdirectory of the CAPD library source code distribution.
Another important requirement is that the names of the user's .cpp files are different from all the .cpp files found in the library modules and all the other groups of programs. A simple Perl script utils/checknames.pl can be used to verify this uniqueness-of-filenames property in a convenient and quick way.
All trademarks, registered trademarks or brand names are property of the respective holders and used in this document for descriptive purposes only. Copyright © 2005 by the CAPD Group. All rights reserved.