Quick links: Tutorial - Examples - Files - Symbols.
Classes: Hierarchy - Index - List - Members.
Namespaces: Index - base - cs - display.
Cette page est disponible en français.

Installing Cogitant from source

Introduction

This section explains how to compile and install the Cogitant library from source. Different procedures must be followed depending on the operating system and the compiler. The table below sums up the different architectures and compilers with which the library has been tested.

SystemVersionCompiler

Tested version

GNU/Linux Debian 9.3 GNU C++ 6.3.0 5.3.2
- - LLVM Clang 3.9.1 5.3.2
MS Windows 10 Microsoft Visual C++ 2017 Community (15.5.0)5.3.2
- - Microsoft Visual C++ 2015 Community (19.0.23026.1)5.3.1
- 8 Microsoft Visual C++ 2013 Express (12.0.30501.00)5.3.1
Mac OS 10.10.5 Apple LLVM 7.0.0 (Xcode 7.0)5.3.1
- - GNU C++ 5.2.0 (Macports)5.3.1
- - GNU C++ 4.9.3 (Macports)5.3.1

Note: This information concerns only basic classes of Cogitant (namespace cogitant), but neither the classes of the client/server architecture, nor the drawing and interfacing classes with Java.

The instructions for compiling described below refer to the basic classes of the library. If you wish to use extensions (client/server architecture, graph design and edition, CommonC++ interfacing, wxWidgets or Java), the compilation is done in much the same way, but specific options must be provided to the compiling mechanism. In order to know in detail these options, you can refer to the section Graphs drawing - compilation and to the section Client-server architecture - compilation.

Two methods are available for the compiling of Cogitant. Depending on the operating system, you must use one method or another. The first method is to use a script configure, a familiar approach to users of Unix-based systems (from now on simply called Unix). This method has the advantage of being basic, but the disadvantage of being available only for Unix, because it requires the presence of an interpreter of shell scripts (sh). The other method is to use Cmake (http://www.cmake.org) whose main advantage is to be available both for Unix and MS Windows, but this method requires the installation of Cmake before launching the compiling of Cogitant.

Installation under Unix (and GNU/Linux, and MacOS X)

Cogitant uses the classical mechanism for compiling under Unix (./configure, make, make install). If you are familiar with this mechanism, there is no need to read this section. Note that Cmake can also be used under Unix, refer to section Installing with Cmake for more information. Make sure you have a C++ compiler installed before going further. Under MacOS, install Xcode, (https://developer.apple.com/xcode/).

First, you must unpack the archive containing the source. To do so, proceed as follows:

tar zxvf cogitant-5.x.x.tar.gz

This will create a directory cogitant-5.x.x containing the source of the library, but also the header files, documentation and example programs. You have now to compile the source in order to build the library file, which can later be linked to your applications. Before that, you have to configure the compiling this way:

cd cogitant-5.x.x
./configure

The call to configure (which is a script file located in the cogitant directory) creates a number of files, enabling the construction of the library. You can pass a number of parameters to this script in order to setup the compiling. Most of these settings can help settling details of the compiling and it is often unnecessary to alter them unless you know what you are doing. Note that a parameter is often used, it is – prefix, which allows you to specify in which directory the result of the compilation will be installed. By default, it is the /usr/local directory (header files are installed in /usr/local/include, the library in /usr/local/lib, etc.), however if you do not have the rights (root) on this directory, you need to specify a different directory (./configure –prefix=/home/ users/me/usr for example). In this case, you must set the value of environment variables PATH and LD_LIBRARY_PATH in order to simply use the library. The purpose of this documentation is not to describe the use of Unix, we do not describe handlings to be done to achieve this result and consider in the future that the files of the platform are correctly installed in reachable directories in the various search directories (e.g. it is the default if you do not use the –prefix parameter). Refer to a "Unix guru" you know if you do not feel able to perform these operations: Cogitant is used like any other library, and any Unix guru worthy of the name knows how to create a tree usr specific to a user.

Once the configuration is done, it is possible to launch the compiling of the library in the following manner:

make

Compiling takes some time, varying obviously according to the capabilities of your hardware. If the compiling is done without incident, you can now install the library in the directories selected at the time of the configure call, for that, just type:

make install

And it's over, now you can compile your own programs that use the library, and for that, please refer to the section Programm compiling using Cogitant.

Installation under SunOS / Solaris

You need to use the GNU tools rather than Sun tools. The names of the GNU tools are usually prefixed by g under SunOS. For example, to uncompress the archive, use the GNU tar rather than the Sun tar (gtar zxvf cogitant-5.x.x.tar.gz). Similarly, to compile the source of the library use the GNU make (gmake followed by gmake install). Depending on the installation, it may be required to specify the make command to be used for the call of the Makefiles of the lower levels, for that, type gmake MAKE=gmake. If the compiling immediately ends with an error, you may have to regenerate some files. For that, type automake, autoconf, ./configure, make.

Installation with other compilers under Unix (Intel C++, another version of the GNU C++, LLVM Clang)

The script configures detects the default compiler and the compiling is done with this compiler, usually version 4.x of GNU C++. Nevertheless, it is possible to force the script configure to use a different compiler. To do this, simply set environment variables CC and CXX before running the script. These two variables must have as value respectively the name of the C compiler used, and the name of the C++ compiler. If needed, these names must be prefixed by a path if executables are not included in the PATH.

Note that if you have already launched the configure script, you should delete the file config.cache before launching the configure script again with the new values for CC and CXX.

Advanced configuration

The configure script can receive arguments that allow you to configure how Cogitant is compiled. ./configure –help returns the argument list, some of which being common to all configuration scripts generated by the infernal couple autoconf / automake, others being specific to Cogitant. Among the specific arguments, we'll cite a few.

Installing with Cmake

Cmake is the second compiling method of Cogitant, but unlike the use of configure, this method requires the installation of an additional application: Cmake. Nevertheless, the application is available packaged in any modern Unix systems. In order to check that cmake is properly installed, just type cmake –version in a shell. The version 2.6.3 (at least) of Cmake is required.

Here we describe the compiling of Cogitant with Cmake in a subdirectory of the directory cogitant-5.x.x called cmake. Obviously, this name is just an example.

tar zxvf cogitant-5.x.x.tar.gz
cd cogitant-5.x.x
mkdir cmake
cd cmake
ccmake ..

ccmake is a simplified interface for configuring the compiling. Once ccmake loaded, type c to display configuration options. The screen appearing then allows you to select Cogitant modules to be constructed (Java Interfacing, for example) and the compiling configuration (CMAKE_BUILD_TYPE can take the value Release for an optimized compiling and Debug for a compilation with debugging information). Press c (after having, if needed, modified certain values) to launch the configuration, then g to generate makefiles. Indeed, the ccmake command generates makefiles matching to the selected configuration, so it only remains to compile Cogitant with a basic:

make

Note that Cmake can also handle other compilers such as Intel C++, for this, you have to define the environment variables in the way given above before calling ccmake. Finally, note that the cmake command can be used in place of ccmake and allows you to set compiling arguments on the command line rather than in an interface, which can be useful for automating the Cogitant construction. Refer to the documentation of cmake (http://www.cmake.org/HTML/RunningCMake.html) for more information.

Installation under MS Windows, with Microsoft Visual C++ Express

This compiler is the recommended one on MS Windows because it is, unlike previous versions, a compiler almost respecting the norm. Nevertheless, solutions based on free software tools must not be forgotten using Cygwin and Mingw which are described below. The approach described here is valid for the Express version of the compiler, which has the advantage of being free, but the approach can be adapted easily to commercial versions of the compiler.

Installing VC++ Express and Cmake

The compiler is available for free from Microsoft's website at the following address: http://www.microsoft.com/france/visual-studio/essayez/express.aspx (Visual Studio Express for Windows Desktop)
Visit the website of Cmake http://www.cmake.org , download and install the MS Windows version.

Configuration

Before compiling the sources, you have to extract them from the archive, for this you have to use a tool able to handle tar.gz files like 7zip (free software available at http://www.7-zip.org/), or Total Commander (http://www.ghisler.com).

Load Cmake from the Start menu and inform it about the directory containing Cogitant's sources in the Where is the source code field (e.g. D:\cogitant-5.x.x). In the second field of Where to build the binaries, we'll specify either the same directory, or another directory which will contain the result of the compiling (e.g. D:\cogitant-5.x.x\cmake). Click on Configure, and ask for the creation of files for Visual Studio 10 (2010), Visual Studio 11 (2012), Visual Studio 12 (2013), VisualStudio 14 (2015). If required, modify the value of certain parameters, then click on Configure. Click then on Generate (or Ok depending on the Cmake version). Cmake deals with the creation of project files for VC++.

With the directories above-cited, Cmake has created a file cogitant.sln in the directory D:\cogitant-5.x.x\cmake. Run this file, which will open VC++ on this project, and start the compiling by pressing F7 (after having, if needed, chosen the compiling method Debug or Release). Beware, if you want to redistribute an application compiled with VC++, you must compile it with the Release mode because the runtime DLL of VC++ in debugging mode are not redistributable.

Installation under MS Windows, with Cygwin

The Cygwin suite (http://www.cygwin.com) is a set of tools enabling to easily compile Unix-made sources. The compiler included in this suite is GNU C++ 4.8. The compiling with Cygwin is done in exactly the same way as under Unix. After starting Cygwin (bash –login), execute the following commands:

./configure
make
make install

Installation under MS Windows, with Mingw

The Mingw toolkit (http://www.mingw.org) is a MS Windows version of the GNU compiler and related tools. Unlike Cygwin which provides an emulation layer for Unix (both system calls and command line utilities), Mingw only contains the compiler and tools needed to build MS Windows programs that can use the Win32 API, but that cannot use systems call specific to Unix. The main benefit of using Mingw compared with Cygwin lies in the absence of the "heavy artillery" established by Cygwin in order to make applications believe they run under Unix: thus, any software compiled with Cygwin is dynamically linked to the cygwin1.dll library which must be compulsorily supplied with your applications (the other constraint is that an application compiled with Cygwin must be GPL, but it is also the case of an application using Cogitant). On the contrary, Mingw produces a "pure" MS Windows executable, which does not require this dll. Nevertheless, it should be noted that the compiling of C++ source with Mingw produce an executable requiring the libstd++.dll library (supplied with Mingw, but which must be distributed with your applications in the case of an installation on a workstation where Mingw is not installed). Cogitant can be compiled with the configure script (Unix way) or CMake (recommended).

Compiling with CMake

See Configuration for generic instructions about the use of CMake with Cogitant. For Mingw, you obviously have to choose the "MinGW Makefiles" generator. Once makefiles are generated, open a command prompt window. Change the current directory to the directory where makefiles have been generated and run the Mingw make. If Mingw has been installed in C:\mingw, Cogitant has been installed in D:\cogitant-5.x.x and CMake-generated makefiles are in the subdirectory cmake of D:\cogitant-5.x.x, the following commands start the compiling.

D:
cd cogitant-5.x.x
cd cmake
C:\mingw\bin\mingw32-make

Compiling with the configure script (deprecated)

No tool is supplied with Mingw for building an application, while you need a shell application and other tools to compile Cogitant or other programs. That is why you have to install, in addition to the Mingw package, the MSys package (for minimal system). This package provides (among other things) a shell required for the execution of the configure script, and can be downloaded from the Mingw's main website.

Once the Mingw and MSys packages are installed, open a MSys session using the Start menu, and start the compiling with ./configure –disable-shared followed by a make.