Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/AdaCore/gnatcoll-core

GNAT Components Collection – Core packages
https://github.com/AdaCore/gnatcoll-core

Last synced: 14 days ago
JSON representation

GNAT Components Collection – Core packages

Awesome Lists containing this project

README 

        
# 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:



```sh

$ ./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:



```sh

$ ./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:



```sh

$ SOURCE_DIR/minimal/gnatcoll_minimal.gpr.py build

...

```



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



```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.