Environment API

PID_Environment

PID_Environment(AUTHOR ... YEAR ... LICENSE ... DESCRIPTION ... [OPTIONS])
declare_PID_Environment(AUTHOR ... YEAR ... LICENSE ... DESCRIPTION ... [OPTIONS])

Declare the current CMake project as a PID environment with specific meta-information passed as parameters.

Required parameters

AUTHOR <name>:The name of the author in charge of maintaining the environment.
YEAR <dates>:Reflects the lifetime of the environment, e.g. YYYY-ZZZZ where YYYY is the creation year and ZZZZ the latest modification date.
LICENSE <license name>:
 The name of the license applying to the environment. This must match one of the existing license file in the licenses directory of the workspace.
DESCRIPTION <description>:
 A short description of the environment usage and utility.
ADDRESS <url>:url of the environment’s official repository.
PUBLIC_ADDRESS <url>:
 provide a public counterpart to the repository ADDRESS

Optional parameters

INSTITUTION <institutions>:
 Define the institution(s) to which the reference author belongs.
MAIL <e-mail>:E-mail of the reference author.

Constraints

  • This function must be called in the root CMakeLists.txt file of the environment before any other call to the PID API.
  • It must be called exactly once.

Effects

Initialization of the environment internal state. After this call the package’s content can be defined.

Example

PID_Environment(
                  AUTHOR Robin Passama
                  INSTITUTION LIRMM
                  YEAR 2013-2018
                  LICENSE CeCILL
                  ADDRESS git@gite.lirmm.fr:pid/clang_toolchain.git
                  DESCRIPTION "using clang toolchain in PID"
)

PID_Environment_Author

PID_Environment_Author(AUHTOR ...[INSTITUTION ...])
add_PID_Environment_Author(AUHTOR ...[INSTITUTION ...])
Add an author to the list of authors of the environment.

Required parameters

AUTHOR <name>:The name of the author.

Optional parameters

INSTITUTION <institutions>:
 Define the institution(s) to which the author belongs to.

Constraints

  • This function must be called in the root CMakeLists.txt file of the package, after PID_Environment and before build_PID_Environment.

Effects

Add another author to the list of authors of the environment.

Example

PID_Environment_Author(AUTHOR Another Writter INSTITUTION LIRMM)

PID_Environment_Platform

PID_Environment_Platform([OPTIONS])
declare_PID_Environment_Platform([OPTIONS])

Defines for building the current environment on the given host platform that satisfies all requirements.

Optional parameters

PLATFORM <platform>:
 defines a complete specification of the target platform (e.g. x86_64_linux_abi11).
TYPE <proc>:the type of architecture for processor of the platform (e.g. x86).
ARCH <bits>:the size of processor architecture registry, 16, 32 or 64.
OS <kernel>:the OS kernel of the platform (e.g. linux).
ABI <abi>:the default c++ ABI used by the platform, 98 or 11.
DISTRIBUTION <distrib name>:
 the name of the distribution of the target platform.
DISTRIB_VERSION <version>:
 the version of the distribution of the target platform.
CONFIGURATION …:
 list of target platform configuration that the host must match
CHECK …:the path to the script file defining how to check if current host already defines aequate build variables.

Constraints

  • This function must be called in the root CMakeLists.txt file of the environment after call to PID_Environment and before call to build_PID_Environment.

Example

PID_Environment_Platform(
   PLATFORM x86_64_linux_abi11
   DISTRIBUTION ubuntu
   DISTRIB_VERSION 18.04
)

PID_Environment_Constraints

PID_Environment_Constraints(OPTIONAL ... REQUIRED ...)
declare_PID_Environment_Constraints(OPTIONAL ... REQUIRED ...)

Declare a set of optional and/or required constraints for the configuration. These constraints are used to provide parameters to environment scripts.

Optional parameters

REQUIRED …:the list of constraints whose value must be set before calling it.
OPTIONAL …:the list of constraints whose value can be set or not before calling it.

Constraints

  • This function must be called in the root CMakeLists.txt file of the environment after call to PID_Environment and before call to build_PID_Environment.

Effects

Defines parameters to the configuration process.

Example

PID_Environment_Constraints(
                  REQUIRED version
)

PID_Environment_Solution

PID_Environment_Solution([CONFIGURE ...] [DEPENDENCIES ...] [FILTERS])
declare_PID_Environment_Solution(CONFIGURE ... [DEPENDENCIES ...][FILTERS])

Define a solution to configure the environment for the current host platform.

Optional parameters

CONFIGURE …:the path to the script file defining how to configure the build tools used by the environment.
DEPENDENCIES …:The list of environment that current environment project depends on. Each environment expression can (or must in case of required constraints) embbed constraint value definition.
DISTRIBUTION …:This is a filter for applying the solution. The solution will apply only if host is of same distribution.
DISTRIB_VERSION …:
 This is a filter for applying the solution. The solution will apply only if host is of same version of distribution (you must also use DISTRIBUTION filter).
PLATFORM …:This is a filter for applying the solution. The solution will apply only if host exactly matches the given platform. To be more selective use a combination of ARCH, TYPE, OS, ABI keywords
ARCH …:This is a filter for applying the solution. The solution will apply only if host has given processor architecture type (e.g. x86).
TYPE …:This is a filter for applying the solution. The solution will apply only if host has given processor architecture register size (e.g. 32).
OS …:This is a filter for applying the solution. The solution will apply only if host runs the given kernel.
ABI …:This is a filter for applying the solution. The solution will apply only if host default C++ ABI is 98 or 11.

Constraints

  • This function must be called in the root CMakeLists.txt file of the environment after call to PID_Environment and before call to build_PID_Environment.

Effects

Defines parameters to the configuration process.

Example

PID_Environment_Solution(OS linux DISTRIBUTION ubuntu CHECK ubuntu/check.cmake)

build_PID_Environment

build_PID_Environment()
Configure PID environment according to previous information.

Constraints

  • This function must be the last one called in the root CMakeList.txt file of the environment.

Effects

This function launch the configuration of the environment build process.

Example

build_PID_Environment()

Script functions

configure_Environment_Tool

configure_Environment_Tool(LANGUAGE ... [COMPILER...] [AR...] [RANLIB...] [FLAGS...])
configure_Environment_Tool(SYSTEM [GENERATOR...] [LINKER ...] [[EXE|MODULE|STATIC|SHARED] FLAGS...])

Configure the tools used for the current environment. Support different signatures.

Required parameters

LANGUAGE lang:the language that is being configured (C, CXX, ASM, Fortran, CUDA).
SYSTEM:tells that system wide (as opposed to language wide) variables are configured.

Optional parameters

COMPILER …:the path to the compiler in use.
AR …:the path to the archive tool in use.
RANLIB …:.
FLAGS …:set of compiler flags (if used with LANGUAGE) or linker flags (if used with SYSTEM) to use.
LINKER …:the path to the linker in use.
GENERATOR …:the name of the generator in use.
EXE|MODULE|STATIC|SHARED:
 filters for selecting adequate type of binaries for which to apply link flags.

Constraints

  • This function must be called in script files of the environment.

Effects

Set the variables used to configure the build environment.

Example

configure_Environment_Tool(LANGUAGE ASM COMPILER ${CMAKE_ASM_COMPILER})

configure_Environment_Tool(SYSTEM LINKER ${CMAKE_LINKER} FLAGS -m32 )

return_Environment_Check

return_Environment_Check(value)
Sets the check process result.

Required parameters

Value:return value of the scrit : TRUE if check OK and FALSE otherwise.

Constraints

  • This function must be called in script files of the environment.

Example

return_Environment_Check()

return_Environment_Configured

return_Environment_Configured(value)
Sets the environment configuration process result.

Required parameters

Value:return value of the scrit : TRUE if configuration is OK and FALSE otherwise.

Constraints

  • This function must be called in script files of the environment.

Example

return_Environment_Configured()

get_Environment_Target_Platform

get_Environment_Target_Platform()

Get information about target platform. The function returns constraints that apply to the target platform.

Optional parameters

DISTRIBUTION <var>:
 the ouput variable containing the name of the distribution.
DISTRIB_VERSION <var>:
 the ouput variable containing the version of the distribution.
TYPE <var>:the ouput variable containing the type of processor (x86, arm).
ARCH <var>:the ouput variable containing the architecture for TYPE (16, 32 or 64).
OS <var>:the ouput variable containing the operating system name (linux, macos).
ABI <var>:the ouput variable containing the C++ ABI used (98 or 11).
CONFIGURATION <var>:
 the ouput variable containing the list of configurations of the platform.

Constraints

  • This function must be called in script files of the environment.

Example

get_Environment_Target_Platform(DISTRIBUTION distrib TYPE proc ARCH bits OS os)

get_Environment_Host_Platform

get_Environment_Host_Platform([OPTION var]...)

Get information about host platform. The function returns the current parameters of the host platform.

Optional parameters

DISTRIBUTION <var>:
 the ouput variable containing the name of the distribution.
DISTRIB_VERSION <var>:
 the ouput variable containing the version of the distribution.
TYPE <var>:the ouput variable containing the type of processor (x86, arm).
ARCH <var>:the ouput variable containing the processor architecture for TYPE (16, 32 or 64).
OS <var>:the ouput variable containing the operating system name (linux, macos).
ABI <var>:the ouput variable containing the C++ ABI used (98 or 11).

Constraints

  • This function must be called in script files of the environment.

Example

get_Environment_Host_Platform(DISTRIBUTION distrib TYPE proc ARCH bits OS os)

get_Environment_Target_ABI_Flags

get_Environment_Target_ABI_Flags(FLAGS target_abi)
Get C++ compiler flags to use the given ABI.

Required parameters

Target_abi:the desired ABI to be used
FLAGS:the output variable that contains compile flags for using target abi

Example

get_Environment_Target_ABI_Flags(FLAGS "CXX11")

evaluate_Host_Platform

evaluate_Host_Platform()
Evaluate again the host platform configuration. To be used after an update of the host (for instance after using apt-get install).

Required parameters

RESULT <var>:the output variable that is TRUE if host now matches

Effects

Recompure all internal cache variables describing the host.

Example

evaluate_Host_Platform()