The GNAT Components Collection (GNATcoll) - Core packages

This is the core module of the GNAT Components Collection. Please refer to the documentation in the docs/ directory.

Structure

The repository contains three projects:

• minimal/gnatcoll_minimal.gpr: packages that may work on more restrictive cross environments.
• core/gnatcoll_core.gpr: packages that can be used in POSIX or Win32 environments.
• projects/gnatcoll_projects.gpr: high level binding to libgpr project

For backward compatibility a project called gnatcoll.gpr is also provided

Dependencies

GNATCOLL requires:

• A recent GNAT compiler
• Gprbuild tools
• (optional) LIBGPR library (only if using gnatcoll_project.gpr)
• (optional) Python (>3.8) to easily configure, build, install each projects.
• (optional) GNU Make to use the legacy makefile that builds the three projects.

Building and Installing

Each project has a helper Python script to handle automatic configuration and launch of gpr tools. The script is located next to each project and called PROJECT_NAME.gpr.py.

Building

The simplest way to build a given project is to use the Python helper script.

For example to build gnatcoll_core.gpr project:

$ ./gnatcoll_core.gpr.py build

For each project the script provides the following commands:

• build: to build and configure the project
• install': to install the built project (gprinstall step)
• clean': to clean all object files (gprclean step)
• uninstall': to uninstall the project (gprinstall --uninstall step)

Build Command

Use --help switch to get the full help on a command. For the build command the results is:

$ ./gnatcoll_core.gpr.py build --help
usage: gnatcoll_core.gpr.py build [-h] [--gpr-opts ...]
                                  [--add-gpr-path ADD_GPR_PATH] [--jobs JOBS]
                                  [--target TARGET] [--prefix PREFIX]
                                  [--integrated] [--install] [--gnatcov]
                                  [--configure-only] [--disable-constant-updates]
                                  [--build {DEBUG,PROD}]
                                  [--enable-shared {yes,no}]

options:
  -h, --help            show this help message and exit
  --gpr-opts ...        pass remaining arguments to gprbuild
  --add-gpr-path ADD_GPR_PATH
                        prepend a path to look for GPR files
  --jobs JOBS, -j JOBS  gprbuild parallelism
  --target TARGET       target
  --prefix PREFIX       installation prefix
  --integrated          installation in platform specific subdir
  --install             proceed with install automatically after the build
  --gnatcov             build project with gnatcov instrumentation
  --configure-only      only perform configuration (i.e: update of project
                        constants and creation of json file). Can be used to
                        integrate with Alire
  --disable-constant-updates
                        Do not update constants in GPR file and use only
                        -XVAR=VALUE to pass configuration to gpr tools

project specific options:
  --build {DEBUG,PROD}
  --enable-shared {yes,no}

The first set of options is generic, and the second set under project specific options is usually connected to some scenario variables in the project.

On call to the build command a JSON file is generated containing all the complete configuration of the project. For example for gnatcoll_minimal.gpr, if you call from a directory called OBJ_DIR the following command:

$ SOURCE_DIR/minimal/gnatcoll_minimal.gpr.py build
...

This will generate in OBJ_DIR the file called gnatcoll_minimal.json:

{
  "project_file": "SOURCE_DIR/minimal/gnatcoll_minimal.gpr",
  "object_dir": "OBJ_DIR",
  "target": null,
  "integrated": false,
  "variables": {
    "GNATCOLL_BUILD_MODE": "PROD",
    "GNATCOLL_VERSION": "25.0",
    "GNATCOLL_OS": "unix"
  },
  "jobs": "0",
  "variants_var": "LIBRARY_TYPE",
  "variants_values": [
    "static",
    "relocatable",
    "static-pic"
  ],
  "gnatcov": false,
  "prefix": "COMPILER_PREFIX",
  "gpr_paths": []
}

In addition, to the generated JSON file a project file might be updated to update the default values for the managed scenario variables. In the context of gnatcoll_minimal.gpr the project is located in config/gnatcoll_minimal_constants.gpr and contains the following:

abstract project GNATCOLL_Minimal_Constants is
    GNATCOLL_VERSION_DEFAULT     := "25.0";
    GNATCOLL_BUILD_MODE_DEFAULT  := "PROD";
    GNATCOLL_OS_DEFAULT          := "unix";
end GNATCOLL_Minimal_Constants;

This update can be skipped by passing --disable-constant-updates. In that case the Python script will pass only -XVAR=VALUE options to the GPR tools to pass the selected configuration.

Having a project with the updated defaults ease work with:

• Alire: You can use build --configure-only command to as a pre-build step in the Alire configuration to generate the right values for the scenario variables
• IDE: When opening the project the right value is automatically selected for all the scenario variables

Bug reports

Please send questions and bug reports to [email protected] following the same procedures used to submit reports with the GNAT toolset itself.