Environments are used to configure the build environment, for instance to change the C/C++ compiler in use.

Selecting an environment

To know available environments use the info command of PID:

cd <pid-workspace>/pid
make info environment=all

Output should look something like:

[PID] Available environments:
- clang_toolchain
- gcc_toolchain
- gfortran_toolchain
- msvc_toolchain
- nvcc_toolchain
- python_interpreter

To get more detailed information about a given environment also use the info command. For instance we want to get information about the gcc_toolchain environment:

cd <pid-workspace>/pid
make info environment=gcc_toolchain

Output should look something like:

ENVIRONMENT: gcc_toolchain
DESCRIPTION: using GNU gcc toolchain to build C/C++ code of projects
LICENSE: CeCILL-C
DATES: 2019
REPOSITORY: git@gite.lirmm.fr:pid/environments/gcc_toolchain.git
CONTACT: Robin Passama (passama@lirmm.fr) - CNRS/LIRMM
AUTHORS:
	Robin Passama - CNRS/LIRMM
Built target info

So gcc_toolchain is used to configure the C/C++ build tools in use. We want to use it to configure our workspace.

Let’s suppose we want to use the gcc_toolchain, we deploy the corresponding environment in workspace:

cd <pid-workspace>/pid
make deploy environment=gcc_toolchain

Now we can use the gcc_toolchain environment to configure workspace build settings.

Changing the current environment in workspace

Let’s suppose we work on a linux workstation with the clang toolchain as default build tools and we want to switch to a gcc toolchain. This operation is managed by changing the current environment in use at workspace level:

cd <pid-workspace>/pid
make configure environment=gcc_toolchain

If gcc is already the default toolchain in your OS then the host configuration will be somehow reset to the default configuration.

Otherwise, depending on your OS and distribution it will try to install and/or configure adequate build tools. Then, anytime you build a package, it will use the gcc toolchain ! Notice that it will not change the current platform and so binaries generated by gcc are compatible with those generated by the clang.

To go back to the host default configuration simply do:

cd <pid-workspace>/pid
make configure environment=host

host is a reserved word that simply tells to reset workspace current configuration.

Parameterize the environment

Environments like gcc_toolchain also use paremeters to be able to define the exact build tools and versions to use. They may for instance adapt the build tools used for a given target platform, so there is a set of default arguments to the configure command used to (partly) specify the target platform:

  • platform: this is the full specification of a target platform. For instance:
make configure environment=gcc_toolchain platform=x86_64_linux_abi11
  • proc_type: specifies a constraint on the processor type (e.g. x86, arm).
  • proc_arch: specifies a constraint on the processor data bus size (e.g. 32, 64).
  • os: specifies a constraint on the operating system (e.g. linux, macosx).
  • abi: specify a constraint on C++ abi in use (98 or 11).
  • distribution: specify a constraint on OS distribution (e.g. ubuntu).
  • distrib_version: specify a constraint on version of OS distribution (e.g. ubuntu). Used together with distribution.

Depending on the constraints passed as arguments the gcc_toolchain environment will try to find a solution.

For instance when working on a x86_64 host platform changing the abi is performed this way:

make configure environment=gcc_toolchain abi=98

It should produce a result like :

[PID] INFO : Target platform in use is x86_64_linux_abi98:
 + processor family= x86
 + binary architecture= 64
 + operating system=linux (ubuntu 16.04)
 + compiler ABI= CXX

The current platform has changed (now it is x86_64_linux_abi98) and everytime a package is built it is installed in the corresponding isolated install tree for this platform. Be warned that such a change can have undesired side effect due for instance to OS libraries being not built with dual ABI support.

On a 64 bits platform, changing the processor binary architecture to 32 bits is performed this way:

make configure environment=gcc_toolchain arch=32

It should produce a result like :

[PID] INFO : Target platform in use is x86_32_linux_abi11:
 + processor family= x86
 + binary architecture= 32
 + operating system=linux (ubuntu 16.04)
 + compiler ABI= CXX11

For now changing those environment does not lead to a cross compilation.

Cross compiling

Environments can be used to define a cross-compilation process by simply targeting another platform: it takes place if you change processor type or operating system. For instance if we want to target a bare metal 32 bits arm system:

cd <pid-workspace>/pid
make configure environment=gcc_toolchain platform=arm_32_abi98

Here notice that the full platform specification arm_32_abi98 does not define an OS, which is normal in this situation because bare metal systems have no OS installed.

Of course it requires that the environment defines the build tools required to target the given platform. For instance gcc_toolchain environment defines how to install adequate version of gcc on ubuntu. Anytime we need to manage new host distributions the gcc_toolchain has to be updated adequately.

When crosscompiling to OS equipped systems we may define additional information. To do this there are specific arguments to the configure command:

  • sysroot: allow user to define a custom sysroot folder for its target platform. Environment should always define a default sysroot id mandatory but user may want to define a new one.
  • staging: allow user to define a custom sysroot staging folder for its target platform. It is only usefull if you used sysroot argument to a path that is read only.

So let’s imagine we want to build for a raspberry pi, we can do:

make configure environment=gcc_toolchain platform=arm_32_linux_abi98 distribution=raspbian

It configures the workspace with the gcc toolchain able to build for a raspberry pi target platform. gcc_toolchain provides a default sysroot but user may want to change it by doing:

make configure environment=gcc_toolchain platform=arm_32_linux_abi98 distribution=raspbian sysroot=/home/login/targets/raspi

Using specific constraints

Each environment may define its own set of constraints. Those constraints may or must be set before using the environment. Typical user defined constraints for environments defining toolchains are: - version: to define a given version of the toolset. - exact: to fore use of the exact version.

Contrarily to predefined parameters, environment constraints must be set with environment variables, for instance:

version=7.1 make configure environment=gcc_toolchain

This command configure workspace with version 7.1 or more of the gcc_toolchain, if this version is available for (or installable on) host OS. Version is an important constraint for environment defining toolchains, for instance because it allows to use compiler supporting specific C++ language features.

To know what are the available constraints for a given environment:

  • the environment must be deployed in workspace, if not do:
cd <pid-workspace>/pid
make deploy environment=gcc_toolchain
  • use the info command:
make info environment=gcc_toolchain

Output should look like:

ENVIRONMENT: gcc_toolchain
DESCRIPTION: using GNU gcc toolchain to build C/C++ code of projects
LICENSE: CeCILL-C
DATES: 2019
REPOSITORY: git@gite.lirmm.fr:pid/environments/gcc_toolchain.git
CONTACT: Robin Passama (passama@lirmm.fr) - CNRS/LIRMM
AUTHORS:
	Robin Passama - CNRS/LIRMM
CONSTRAINTS:
 - version
 - exact

We can see that last section CONSTRAINTS lists available parameters: version and exact.