This section explains how to compile a program that uses the Cogitant's class library. Like any other library, Cogitant needs you to take care when compiling programs so that the compiler can access headers files of the library and that the linker can link the produced executable to the library. We assume the library has already been compiled (and installed in directories correctly configured, in the case of a Unix system). Otherwise, see Installing Cogitant. Depending on the compiling mode, which was chosen for the library (use of the configure script, or use of Cmake), compiling of programs using Cogitant is done through different ways. So this section is divided into two sub-sections, which correspond to the two methods for compiling Cogitant.
This section describes how to compile programs using Cogitant library, when this library was built by ./configure, make, make install, method that can be used under Unix, as well as under MS Windows provided you use Cygwin or Mingw. If the compiling of Cogitant was done by Cmake, refer to the section Compilation based on Cmake.
In order to ease the management of parameters to be passed to the compiler (path of headers files, specific symbols of the pre-processor (#define)) and to the linker (path containing the library, library name), we used a mechanism similar to the one introduced by the GTK+ library (http://www.gtk.org), which consists in using a shell script file returning parameters to be past to the compiler or the linker. It is the use of this file which is described below. However, this script being written in sh, it cannot be used under MS Windows (except in the case of using Cygwin on Mingw).
The cg-config file is the shell script which returns the various parameters to be passed to the compiler and to the linker in order to enable the generation of executables based on Cogitant. This file is automatically copied into the directory containing the binaries (/usr/bin or /usr/local/bin) at the time of the platform installation (make install or package installation). This file must be in a folder belonging to the path. To check this, just type:
If the script is found, the execution of this script will display the version of the platform installed and the parameters which can be passed to the script. Nevertheless, you can use this script even if it is not in the path. In this case, you have obviously to prefix every call to the script by the name of the directory in which it is located. This feature allows you to use the platform even if you do not have administrator rights on the system (writing in /usr). In this case, however, it is recommended, as for any library, to create in its user directory a usr hierarchy reproducing the /usr structure (i.e. containing subfolders bin (in the path), doc, include, lib (in the LD_LIBRARY_PATH), etc.), and to give the location of this directory to the configuration script (configure) of the platform's sources.
The purpose of this documentation is not to describe the use of Unix, we will not describe manipulations to be done in order to get this result and we assume in the future that the platform files are correctly installed in directories. Refer to the "Unix guru" at your disposal if you do not feel able to perform these tasks. Obviously, you do not have to do these manipulations if the platform is installed in /usr, whether after an installation from sources with administrator rights, or after an installation from a RPM package.
Specific parameters to be passed to the compiler involve two areas:
ASSERT_MODE) and for the display of certain information which ease debugging (LOG_MODE). These two symbols must be defined exactly the same way as when compiling platform's source, otherwise you may get link editing errors or erroneous behaviors: These parameters do not depend on the application built with CoGITaNT but on the way the library was constructed. #include. Such parameters are sent to standard output when the script cg-config is called with the –cflags parameter. So, in order to compile a file main.cpp using Cogitant's classes, you can define a dependency in the Makefile of your program in the following way:
Parameters to be passed to the linker concern the path in which Cogitant's library (dynamically linked archive or library) is stored. These parameters are sent to standard output when the script cg-config is called with the –libs parameter. So, for editing links of a program called test and built from a single object file called main.o, you can define this dependency :
The following file can be used as a model for compiling programs using the library (construction of an executable named minimum from a source file minimal.cpp). You may need to modify the line PROGRAM= in order to choose the name of the executable result and the line SOURCES= to specify the names of the source files that constitute the program to be built (cpp extension, use the space as a separator).
If the library is compiled from sources (and not installed from a package), you can build programs using it without installing the files of the library into a hierarchy usr (i.e. without running make install). This requires, when calling the cg-config script, the specification of the path containing the library (i.e. the path containing the directories src, include, and so on, obtained after uncompressing the archive containing the sources). You can use for that the parameter –prefix, which must be passed to the script before all others. For example, in this case where files of the platform reside in ../cogitant relatively to the current directory, compilation dependency becomes:
Makefile changes concern the script file name, and more particularly the specification of the directory containing this file, and the use of the –prefix parameter which obliges the script to return paths relative to ../cogitant for headers files and the library archive.
Note that if you create an executable with dynamic linking (on systems providing this possibility, such as GNU/Linux, where the result of a link editing is by default a dynamically linked executable), you have obviously to define the LD_LIBRARY_PATH environment variable, otherwise the execution of the result program will not be possible because the dynamic library will not be accessible (see Unix manual on this subject: man ldd).
This section describes how to compile programs using Cogitant's library, in the case where the library was built with Cmake, method used under MS Windows with VisualC++, but which can also be used under Unix. If the compiling of Cogitant was done by a ./configure, make, make install, refer to section Compilation based on configure/make.
When compiling Cogitant, Cmake has created a number of files needed for the used compiler. These files are different depending on the chosen compiler. But in all cases, these files reside in a directory that can be the directory containing Cogitant's sources or another one (which is recommended). In Cogitant's documentation, we took the example of a Cogitant compiling in the D:\cogitant-5.x.x\cmake directory under MS Windows (chose into Where to build the binaries of Cmake) and in the cmake subdirectory of the directory containing Cogitant's sources under Unix. From now on, we'll call this directory build directory of Cogitant. This build directory contains a part of the source directory aborescence, and the file that particularly concerns us is in include/cogitant and is called CMakeCogitant.txt. It is produced by Cmake, depending on the choices made by the user when setting up the compiling of Cogitant. This file defines a number of Cmake variables that will allow us to easily write a file CMakeLists.txt in order to compile our own program using Cogitant. Actually, you just have to include this file in its CMakeLists.txt and then declare its own program, which will automatically be compiled using Cogitant's directory containing header files. For example, to compile an application from two source files f1.cpp and f2.cpp and based on Cogitant, we could use the following CMakeLists.txt file:
The COGITANTDIR variable of the file will require, as value, the build directory of Cogitant in order to include the right file (not the directory containing Cogitant's sources). Once the CMakeLists.txt file has been was created, compiling your application can be done by the usual way with Cmake, i.e. by first calling Cmake so that it analyzises CMakeLists.txt files and creates the files required by the compiling (Makefile or projects files), then the compiler on the created files. For a more detailed use of CMakeCogitant.txt, you can consult that file and see which variables are defined. Likewise, do not hesitate to consult Cmake documentation for more information.