# 2. Building GNATColl

The build process is extremely flexible, allowing you to choose which modules to build, the features they should have, and various other properties. In the instructions detailed below, it is assumed that you have unpacked the GNATColl package in a temporary directory and that installdir is the directory in which you would like to install the selected components.

GNATColl requires the same version of GNAT it was released with, since it is sharing some sources with GNAT’s `libgnatutil` library. If you do not have such a compiler, please contact info@adacore.com

## 2.1. Configuring the build environment

The first step is to configure the build environment. This is done by running the configure command in the root directory of the GNATColl tree.

On Windows, this requires a properly setup Cygwin environment, to provide Unix-like tools.

Some GNATColl components need access to a subset of the GNAT source files. An example is the GNATCOLL.Projects module, which reuses the same parser as the GNAT tools.

GNATColl will locate the needed source files in one of the following ways:

- If you have a copy of the GNAT sources, create a link called `gnat_src` that points to the directory containing those sources. This link should be created in the root GNATColl directory.
- Otherwise, recent versions of GNAT are distributed with a `libgpr` library that contains the project parser. GNATCOLL will automatically make use of it. You must use the same version of GNAT that GNATColl was released with, otherwise the sources might not be compatible. If you have an older version of GNAT, you could also chose to install libgpr independently.

If neither of the above is satisfied, GNATColl will not include support for GNATCOLL.Projects. You can also explicitly disable project support by configuring with –disable-project.

The configure command accepts a variety of arguments; the following are likely to be the most useful:

–prefix=`installdir`
  This specifies the directory in which GNATColl should be installed.
–enable-shared and –disable-shared

  If neither of these switches is specified, GNATColl will try to build both static and shared libraries (if the latter are supported on your system). The compilation needs to be done twice, since the compilation options might not be the same in both cases.

  If you intend to always use static libraries, you can specify –disable-shared.

  When you link GNATColl with your own application, the default is to link with the static libraries. You can change this default, which becomes shared libraries if you explicitly specify –enable-shared. However, even if the default is static libraries, you can still override this (see below the LIBRARY_TYPE variable).

–with-python=`directory` and –without-python

  This specifies where GNATColl should find python. For example, if the python executable is in `/usr/bin`, the directory to specify is `/usr`. In most cases, however, configure will be able to detect this automatically, so this option is only useful when python is installed some special directory. If you specify the second option, support for python will not be built in.

  The switch –with-python-exec can also be used to specify an alternative python executable. If you pass the value ‘python3’, it will force GNATCOLL to build with support for python3, not python2.

–enable-shared-python
  This specifies the location of the python library as directory/lib, which will in general be a shared library. By default, configure will search in a different directory of the python installation, and is more likely to find the static library instead (which makes distributing your application easier). However, whether shared or static libraries are used depends on how python was installed on your system.
–disable-gtk
  If this switch is specified, then no package depending on the gtk+ graphical toolkit will be built.
–disable-pygtk
  If this switch is specified, then support for pygtk (The Python language) will not be build. The support for this python module will also be automatically disabled if python was not found or if you configured with –without-python.
–disable-syslog
  If this switch is specified, then support for syslog (Logging to syslog) will not be build. This support allows sending the traces from all or part of your application to the system logger, rather than to files or stdout.
–with-postgresql=<dir> and –without-postgresql

  GNATColl embeds a set of packages to query a database engine. The configure command attempts to find which systems are installed on your system, and then builds the needed support. But you can also explicitly disable such support.

  If the directory in which PostgreSQL is installed contains spaces, you should use a syntax like:

      ./configure --with-postgres="/Program Files/PostgreSQL/8.4"

  Generally speaking, we do not recommend using paths with spaces, since such a setup often introduces complications.

  It is possible to link with a static library for postgres, by specifying the full path to libpq.a, as in:

       ./configure --with-postgres="/usr/local/lib/libpq.a"

      However, that library depends on shared libraries ssl and crypto, so your
      application is still not fully linked statically.

–with-sqlite=<dir> and –without-sqlite

  GNATCOLL embeds a set of packages to access sqlite database. This requires a fairly recent version of sqlite. These switches can be used to point to the sqlite install on your system. By default, GNATCOLL will recompile its own embedded version of sqlite and link statically with it, which avoids issues with shared libraries and makes sure the version is compatible with GNATCOLL’s needs.

  configure will look for the sqlite libraries in `dir/lib/`, `dir/lib64` or `dir`, in that order, and using the first directory that exists.

–enable-gpl

  GNATCOLL provides interfaces to libraries that are licensed under the Full GNU Public License. This means that, should you choose to distribute your application to anyone, it must be free software and have a GPL-compatible license.

  To avoid ambiguities, these interfaces are disabled by default, unless you provide the –enable-gpl switch to configure.

  This currently only impacts GNATCOLL.Readline.

Special support exists in GNATColl for the gtk+ graphical toolkit. The configure command will attempt to find the installation directory for this toolkit by using the pkg-config command, which must therefore be available through your PATH environment variable. It also needs to find the `gtkada.gpr` project file either because it is part of the implicit search path for project files, or because you have put the corresponding directory in the environment variable GPR_PROJECT_PATH. If either of these two requirements fail, the modules of GNATColl that depend on GtkAda will not be built:

    ./configure --prefix=/usr/local/gnatcoll --without-python

If all goes well (i.e. all required dependencies are found on the system), configure will generate a number of files, including `Makefile`, `Makefile.conf` and `gnatcoll_shared.gpr`.

## 2.2. Building GNATColl

If configure has run successfully, it generates a Makefile to allow you to build the rest of GNATColl. This is done by simply typing the following command:

    make

Depending on the switches passed to configure, this will either build both static and shared libraries, or static only (see the –disable-shared configure switch).

Optionally, you can also build the examples and/or the automatic test suite, with the following commands:

    make examples
    make test

The latter will do a local installation of gnatcoll in a subdirectory called `local_install`, and use this to run the tests. This checks whether the installation of gnatcoll was successful.

## 2.3. Installing GNATColl

Installing the library is done with the following command:

    make install

Note that this command does not try to recompile GNATColl, so you must build it first. This command will install both the shared and the static libraries if both were built.

As mentioned in the description of the configure switches, your application will by default be linked with the static library, unless you specified the –enable-shared switch.

However, you can always choose later which kind of library to use for GNATColl by setting the environment variable LIBRARY_TYPE to either “relocatable” or “static”.

Your application can now use the GNATColl code through a project file, by adding a `with` clause to `gnatcoll.gpr`, `gnatcoll_gtk.gpr` or `gnatcoll_python.gpr`. The second one will also force your application to be linked with the gtk+ libraries, but provides additional capabilities as documented in each of the modules.

If you wish to install in a different location than was specified at configure time, you can override the “prefix” variable from the command line, for instance:

    make prefix=/alternate/directory install

This does not require any recompilation.