Package API

PID_Package

PID_Package(AUTHOR ... YEAR ... LICENSE ... DESCRIPTION ... [OPTIONS])
declare_PID_Package(AUTHOR ... YEAR ... LICENSE ... DESCRIPTION ... [OPTIONS])

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

Required parameters

AUTHOR <name>:The name of the author in charge of maintaining the package.
YEAR <dates>:Reflects the lifetime of the package, 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 package. This must match one of the existing license file in the licenses directory of the workspace.
DESCRIPTION <description>:
 A short description of the package usage and utility.

Optional parameters

INSTITUTION <institutions>:
 Define the institution(s) to which the reference author belongs.
MAIL|EMAIL <e-mail>:
 E-mail of the reference author.
ADDRESS <url>:url of the package’s official repository. Must be set once the package is published.
PUBLIC_ADDRESS <url>:
 provide a public counterpart to the repository ADDRESS
README <path relative to share folder>:
 Used to define a user-defined README file for the package.
CODE_STYLE <code style>:
 Select the given code style for the project. If clang-format is available, the format command will be provided to format the source files.
VERSION (major minor [patch] | major.minor.patch):
 current version of the project either as a list of digits or as a version number with dotted expression.

Constraints

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

Effects

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

Example

PID_Package(
                  AUTHOR Robin Passama
                  INSTITUTION LIRMM
                  YEAR 2013-2018
                  LICENSE CeCILL
                  ADDRESS git@gite.lirmm.fr:passama/a-given-package.git
                  DESCRIPTION "an example PID package"
)

set_PID_Package_Version

set_PID_Package_Version(MAJOR MINOR [PATCH])
set_PID_Package_Version(version_string)

Set the current version number of the package.

Required parameters

MAJOR:A positive number indicating the major version number.
MINOR:A positive number indicating the minor version number.
Version_string:alternatively you can use a single version string with the format “MAJOR.MINOR[.PATCH]”

Optional parameters

PATCH:A positive number indicating the patch version number. If not defined, it will default to 0.

Constraints

  • This function must be called in the root CMakeLists.txt file of the package, after PID_Package but before build_PID_Package.
  • It must be called : never if the VERSION argument of PID_Package has been used ; exactly once otherwise.

Effects

Setting the current version number will affect the binar installation folder and configuration files.

Example

set_PID_Package_Version(1 2)

PID_Author

PID_Author(AUTHOR ... [INSTITUTION ...])
add_PID_Package_Author(AUTHOR ... [INSTITUTION ...])

Add an author to the list of authors.

Required parameters

AUTHOR <name>:Name of the additional author.

Optional parameters

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

Constraints

Effects

Add an author to the list of authors.

Example

PID_Author(AUTHOR Benjamin Navarro INSTITUTION LIRMM)

PID_Category

PID_Category(CATEGORY)
add_PID_Package_Category(CATEGORY)

Declare that the current package belongs to a given category.

Required parameters

CATEGORY:A string describing the category to which the package belongs. Sub-categories are divided by /.

Constraints

Effects

Register the package has being member of the given (sub)category. This information will be added to the Reference file when it is generated.

Example

PID_Category(example/packaging)

PID_Publishing

PID_Publishing(AUTHOR ... [INSTITUTION ...])
declare_PID_Publishing(AUTHOR ... [INSTITUTION ...])

Declare a site where the package is published, i.e. an online website where documentation and binaries of the package ar stored and accessible. There are two alternative for this function: defining a lone static site or defining the publication of the package in a framework.

Required parameters

One of the two following options must be selected.

FRAMEWORK <name>:
 The package belongs to the name framework. It will contribute to that site.
GIT <url>:A stand-alone package. <url> is the git repository for the static site of this package.

When the GIT option is used, the following argument is also required:

PAGE <url>:<url> is the online url of the static site.

When the GIT option is used, the following argument is also required:

PROJECT <url>:Where to find the project page. This can also be used for same prupose with FRAMEWORK but when not used the documentation for the package is not generated (only used to reference the project as part of the framework).

Optional parameters

DESCRIPTION <description>:
 A long description of the package utility.
TUTORIAL <file>:
 <file> should be a markdown file relative to the share/site folder of the package. This will be used to generate a tutorial webpage.
ADVANCED <file>:
 <file> should be a markdown file relative to the share/site folder of the package. This will be used to generate an advanced description page.
PUBLISH_BINARIES:
 If this is present, the package will automatically publish new binaries to the publication site.
PUBLISH_DEVELOPMENT_INFO:
 If this is present, the package website will contain information for developpers such as coverage reports and static checks.
ALLOWED_PLATFORMS <list of platforms>:
 list of platforms used for CI, only the specified platforms will be managed in the CI process. WARNING: Due to gitlab limitation (only one pipeline can be defined) only ONE platform is allowed at the moment OR all pipelines must build to produce the output.
CATEGORIES <list of string>:
 list of category strings, used to specify to which categories the package contributes in a framework with same syntax as with PID_Category function. Used together with FRAMEWORK keyword.

When the GIT option is used, the following argument is also accepted:

LOGO <path>:<path> is an image file that will be used as a logo. The file path is relative to the share/site folder of the package.

Constraints

Effects

The main effect is to generate or update a static site for the project. This static site locally resides in a dedicated git repository. If the project belongs to no framework then it has its lone static site that can be found in sites/packages/<package name>. If it belongs to a framework, the framework repository can be found in sites/frameworks/<framework name>. In this later case, the package only contributes to its own related content not the overall content of the framework.

In both case, depending on how the package is built, the package will generate different kind of documentation (API documentatio, static check reports, coverage reports, etc.). Depending on options it can also deploy binaries or developper info for the current version and target platform into the static site repository (framework or lone static site).

Example

Declaring the publication of the pid-rpath package as a stand-alone package:

declare_PID_Publishing(PROJECT https://gite.lirmm.fr/pid/pid-rpath
			GIT git@gite.lirmm.fr:pid/pid-rpath-pages.git
			PAGE http://pid.lirmm.net/pid-rpath
			DESCRIPTION pid-rpath is a package providing a little API to ease the management of runtime resources within a PID workspace. Runtime resources may be either configuration files, executables or module libraries. Its usage is completely bound to the use of PID system.
			ADVANCED specific_usage.md
			LOGO	img/rouage_PID.jpg
			PUBLISH_BINARIES
     ALLOWED_PLATFORMS x86_64_linux_stdc++11__ub20_gcc9__)

Declaring the publication of the pid-rpath package into the pid framework:

PID_Publishing(
   PROJECT https://gite.lirmm.fr/pid/pid-rpath
   FRAMEWORK pid
   DESCRIPTION pid-rpath is a package providing a little API to ease the management of runtime resources within a PID workspace. Runtime resources may be either configuration files, executables or module libraries. Its usage is completely bound to the use of PID system.
   ADVANCED specific_usage.md
   PUBLISH_BINARIES
   ALLOWED_PLATFORMS x86_64_linux_stdc++11__ub20_gcc9__)

PID_Documentation

PID_Documentation(COMPONENT ... FILE ...)
declare_PID_Component_Documentation(COMPONENT ... FILE ...)

Add specific documentation for a component

Required parameters

COMPONENT <name>:
 Name of the component for which a markdown page is provided.
FILE <path>:Path to the markdown page for the specified component. <path> is relative to the share/site folder of the package.

Constraints

Effects

This function registers a markdown page with documentation about the component. This page can be used to generate a specific web page for the component than will be put in the static site defined by the package deployment, see PID_Publishing.

Example

PID_Documentation(COMPONENT my-lib FILE mylib_usage.md)

check_PID_Environment

check_PID_Environment(...)

Check if the current build profile conforms to the given environments requirements. If constraints are violated then the configuration of the package fails. Otherwise the project will be configured and built accordingly.

Optional parameters

OPTIONAL:if used then the requirement on build environment is optional.
LANGUAGE …:constraint check expressions defining which language must/can be used (testing only C and C++ is not necessary).
TOOLSET …:constraint check expressions defining which toolset must/can be used for target language.
CONFIGURE …:set of languages that will be configured by the usage of a toolset, in addition to the one defined by the LANGUAGE keyword. TOOLSET keyword is not mandatory as the toolset may be automatically deduced from LANGUAGE expression.
TOOL …:Set of constraint check expressions defining which extra tools must/can be used.

Constraints

Effects

Verify that the current profile in use provides an environment the tool or langauge to use

Example

Checking that the current profile support a f2c generator.

check_PID_Environment(TOOL f2c)

check_PID_Environment(LANGUAGE CXX[std=17])#check that a compiler with full c++17 support is provided

check_PID_Environment(LANGUAGE CXX TOOLSET clang_toolchain[version=9.0])#check that a clang compiler with version >= 9.0 is available

check_PID_Environment(LANGUAGE CXX CONFIGURE C TOOLSET clang_toolchain[version=9.0])#same as previously but the clang_toolchain is also used for C language

check_PID_Environment(LANGUAGE CXX[std=17] CONFIGURE C ASM)#check that compiler/stdlib fully supports C++17. If not AND if a solution can be found then the toolset used will also be used for C and ASM languages

check_PID_Platform

check_PID_Platform(CONFIGURATION ... [OPTIONS])

Check if the current target platform conforms to the given platform configuration. If constraints are violated then the configuration of the package fail. Otherwise the project will be configured and built accordingly. The configuration will be checked only if the current platform matches some constraints. If there is no constraint then the configuration is checked whatever the current target platform is.

Optional parameters

CONFIGURATION|REQUIRED <list of configurations>:
 list of platform configruation expressions that define the required configurations on target platform. Call will fail with an error if a configuration is not satisfied. Use of CONFIGURATION keyword is deprecated.
OPTIONAL <configurations>:
 list of platform configruation expressions that define the required configurations on target platform. Call will silent errors if a configuration is not satisfied and produce the variable <confi name>_AVAILABLE accordingly.

These parameters can be used to refine the configuration check.

TYPE <list of arch>:
 Constraint on the processor type.
OS <list of os name>:
 Constraint on the operating system. For instance the list “linux freebsd” can be used.
ARCH <32|64>:Constraint on the processor architecture.
ABI <list of standard libraries abi>:
 Constraint on the ABI given by the standard c++ library in use.

Constraints

Effects

First it checks if the current target platform of the workspace satisfies the specified constraints (TYPE, OS, ARCH and ABI). If all constraints are not respected then nothing is checked and the configuration of the package continues. Otherwise, the package configuration must be checked before continuing the configuration. Each configuration required is then checked individually. This can lead to the automatic install of some configuration, if this is possible (i.e. if there is a known way to install this configuration), which is typically the case for system software dependencies like libraries when:

  1. No cross compilation takes place
  2. The host system distribution is managed by the configuration (most of time debian like distributions are managed for installable configurations).

If the target plaform conforms to all required configurations, then the configuration continue. Otherwise the configuratin fails.

Example

Checking that if the target platform is a linux with 32 bits architecture, then it must provide posix and x11 configruation.

check_PID_Platform(OS linux ARCH 32 CONFIGURATION posix x11)

Checking that any target platform provides an openssl configuration.

check_PID_Platform(REQUIRED openssl)

get_PID_Platform_Info

get_PID_Platform_Info([OPTIONS])

Get information about the target platform. This can be used to configure the build accordingly.

Optional parameters

All arguments are optional but at least one must be provided. All properties are retrieved for the target platform.

NAME <VAR>:Output the name of the target platform in VAR
TYPE <VAR>:Ouptut the processor type in VAR
OS <VAR>:Output the OS name in VAR
ARCH <VAR>:Output the architecture in VAR
ABI <VAR>:Output the ABI in VAR
DISTRIBUTION <VAR>:
 Output the distribution in VAR
DISTRIB_VERSION <VAR>:
 Output the distribution version in VAR
PYTHON <VAR>:Output the Python version in VAR
PROC_OPTIM <VAR>:
 Output available processor optimizations in VAR

Effects

After the call, the variables defined by the user will be set to the corresponding value. Then it can be used to control the configuration of the package.

Example

add_PID_Package_Author(AUTHOR Benjamin Navarro INSTITUTION LIRMM)

build_PID_Package

build_PID_Package()

Automatically configure a PID package according to previous information.

Constraints

  • This function must be called last in the root CMakeLists.txt file of the package.

Effects

This function generates configuration files, manage the generation of the global native build process and include the CMakeLists.txt files from the following folders (in that order): src, apps, test, share.

Example

build_PID_Package()

PID_Component

PID_Component(<type> NAME ... DIRECTORY .. [OPTIONS])
declare_PID_Component(<type> NAME ... DIRECTORY .. [OPTIONS])

Declare a new component in the current package.

Required parameters

<type>:this is the type of the library. It can be ommited, in this case it is deduced automatically with default values (SHARED, MODULE or HEADER for libraries, APP for applications, TEST for tests) - STATIC_LIB|STATIC: static library - SHARED_LIB|SHARED: shared library - MODULE_LIB|MODULE: shared library without header - HEADER_LIB|HEADER: header-only library - APPLICATION|APP: standard application - EXAMPLE_APPLICATION|EXAMPLE: example code - TEST_APPLICATION|TEST: unit test
NAME <name>:Unique identifier of the component. name cannot contain whitespaces. The NAME keyword can be omitted if the name of the dependency is the first argument.

Optional parameters

DIRECTORY <dir>:
 Sub-folder where to find the component sources. This is relative to the current CMakeLists.txt folder. If ommitted then the folder name is considered the same as the component name.
DESCRIPTION <text>:
 Provides a description of the component. This will be used in generated documentation.
USAGE <list of headers to include>:
 This should be used to list useful includes to put in client code. This is used for documentation purpose.
DOCUMENTATION:specifies a file (markdown) used to generate an online documentaion for the component.
C_STANDARD <90|99|11>:
 C language standard used to build the component. Defaults to 90 (i.e. ANSI-C)
C_MAX_STANDARD <90|99|11>:
 Maximum C language standard that can be used when using the component.
CXX_STANDARD <98|11|14|17|20>:
 C++ language standard used to build the component. Defaults to 98.
CXX_MAX_STANDARD <98|11|14|17|20>:
 Maximum C++ language standard that can be used when using the component.
WARNING_LEVEL <DEFAULT|MORE|ALL>:
 Level of warning required when building the code, DEFAULT is the compiler’s defaut warning level, MORE adds the most common ones and ALL maximizes the number of warnings.
RUNTIME_RESOURCES <files>:
 <files> is a list of files and folders relative to the share/resources folder. These files will be installed automatically and should be accessed in a PID component using the pid-rpath package.
INTERNAL:This flag is used to introduce compilation options that are only used by this component.
EXPORTED:This flag is used to export compilation options. Meaning, components that later refer to this component will be using these options.
SPECIAL_HEADERS:
 Specify specific files to export from the include folder of the component. Used for instance to export file without explicit header extension.
AUXILIARY_SOURCES:
 Specify auxiliary source folder or files to use when building the component. Used for instance to share private code between component of the project. May contain a list of path relative to project root dir.
DEPEND …:Specify a list of components that the current component depends on. These components are not exported.
EXPORT …:Specify a list of components that the current component depends on and exports.
LOGGABLE:specifies that the component generate logs using the pid-log system.
ALIAS …:specifies the alias names of the component.
MANAGE_SYMBOLS:Tell the system that the code will manage symbol export by specifying the path (relative to DIRECTORY) where the generated header defining macro for exporting symbols will be put. All symbols of the library will be hidden instead of default behavior where all symbols are exported.
INTERNAL_ONLY:specifies that the library is defined for internal use only, will not be installed by the package.
FOR_EXAMPLES:specifies that library must be internal only and is used for example purpose
FOR_TESTS:specifies that library must be internal only and is used for testing purpose
LOGGABLE:specifies generate logs that can be discriminated from other component logs (using pid-log system)

The following options are supported by the INTERNAL and EXPORTED commands:

DEFINITIONS <defs>:
 Preprocessor definitions. May be exported if these definitions are used in public headers of a library.
LINKS <links>:Linker flags. Should be reserved to specific linker option to use when linking a library or executable. May be exported if this option changes the ABI.
COMPILER_OPTIONS <options>:
 Compiler-specific options. May be exported if this option changes the ABI.

Furthermore, the INTERNAL option also support the following commands: :INCLUDE_DIRS <dirs>: Additional include directories.

Constraints

  • <type> acceptability depends on the current folder.

Effects

Defines a new component in the package. Will create related targets to build the component and install it (if applicable).

Example

 PID_Component(STATIC_LIB NAME my-static-lib DIRECTORY binary_lib
                       INTERNAL DEFINITIONS EXPORT_SYMBOLS
                       EXPORT DEFINITIONS IMPORT_SYMBOLS
)

PID_Predeclare_Application

PID_Predeclare_Application(name)

Predeclare an application. To be used in CMakeLists.txt of src folder to allow a library to depend on an internal application (that will be defined later)

Required parameters

<name>:Name of the application. This later must be defined in the CMakeLists.txt of the app folder.

PID_Dependency

PID_Dependency([PACKAGE] ... [EXTERNAL|NATIVE] [OPTIONS])
declare_PID_Package_Dependency([PACKAGE] ... [EXTERNAL|NATIVE] [OPTIONS])

Declare a dependency between the current package and another package.

Required parameters

[PACKAGE] <name>:
 Name of the package the current package depends upon. The PACKAGE keyword can be omitted if the name of the dependency is the first argument.

Optional parameters

EXTERNAL:Use this keyword when you want to specify name as an external package. In most cases this keyword can be omitted as PID can automatically detect the type of packages.
NATIVE:Use this keyword when you want to specify name as a native package. In most cases this keyword can be omitted as PID can automatically detect the type of packages.
OPTIONAL:Make the dependency optional.
[EXACT|FROM|TO] VERSION <version>:
 Specifies the requested package version. EXACT means this exact version is required (patch revision may be ignored for native packages), otherwise this is treated as a minimum version requirement. Multiple exact versions may be specified. In that case, the first one is the default version. Another option is to define ranges of versions with FROM VERSION … TO VERSION .. expressions.
COMPONENTS <components>:
 Specify which components of the given package are required.

Constraints

Effects

This function will register the target package as a dependency of the current package. The information will be added to the Use file.

Example

Simple example:

PID_Dependency (
          PACKAGE another-package
          NATIVE VERSION 1.0
          COMPONENTS lib-other-sh
)

Specifying multiple acceptable versions:

declare_PID_Package_Dependency (PACKAGE boost EXTERNAL
                                EXACT VERSION 1.55.0
                                EXACT VERSION 1.63.0
                                EXACT VERSION 1.64.0
)

Same but with reduced signature:

PID_Dependency (boost EXACT VERSION 1.55.0
                      EXACT VERSION 1.63.0
                      EXACT VERSION 1.64.0
)

used_PID_Dependency

used_PID_Dependency([PACKAGE] ... [USED var] [VERSION var])
used_PID_Package_Dependency([PACKAGE] ... [USED var] [VERSION var])
Get information about a dependency so that it can help the user configure the build.

Required parameters

[PACKAGE] <name>:
 Name of the depoendency. The PACKAGE ketword may be omitted.

Optional parameters

USED var:var is the output variable that is TRUE if dependency is used, FALSE otherwise. This is used to test if an optional dependency is in use.
VERSION var:var is the output variable that contains the version of the dependency that is used for current build.

Constraints

  • Must be called after all declaration of package dependencies.

Effects

This function has no side effect but simply returns information about dependency.

Example

used_PID_Dependency(PACKAGE boost VERSION version_str)
#configure components according to version_str...

PID_Component_Dependency

PID_Component_Dependency([COMPONENT] ... [EXPORT|DEPEND] [NATIVE|EXTERNAL] ... [PACKAGE|FRAMEWORK ...] [definitions...])
PID_Component_Dependency([COMPONENT] ... [EXPORT] [EXTERNAL ...] [OPTIONS])
PID_Component_Dependency([COMPONENT] ... [EXPORT|DEPEND] CONFIGURATION ... [definitions...])
declare_PID_Component_Dependency([COMPONENT] ... [EXPORT|DEPEND] [NATIVE|EXTERNAL] ... [PACKAGE ...] [defintions...])
declare_PID_Component_Dependency([COMPONENT] ... [EXPORT] [EXTERNAL ...] [OPTIONS])

Declare a dependency for a component of the current package. First signature is used to defince a dependency to an explicity component either native or external. Compared to the DEPEND option of PID_Component this function may define additional configuration for a given component dependency (typically setting definitions). Second signature is used to define a dependency between the component and either the content of an external package or to the operating system. Third signature is used to define a dependency between the component and all components defined by a configuration. This is a shortcut of second signature to bind a component with system dependencies that are described as configurations. As often as possible first or third signature must be preferred to second one. This later here is mainly to ensure legacy compatibility.

Common parameters

[COMPONENT] <name>:
 Name of the component. The COMPONENT ketword may be omitted.
EXPORT:If this flag is present, the dependency is exported. It means that symbols of this dependency appears in component public headers.
INTERNAL_DEFINITIONS <defs>:
 Definitions used internally in name when the dependency is used.
IMPORTED_DEFINITIONS <defs>:
 Definitions contained in the interface of the dependency that are set when the component uses this dependency.
EXPORTED_DEFINITIONS <defs>:
 Definitions that are exported by name when that dependency is used.

First signature

[NATIVE] <component>:
 component is the native component that name depends upon. The keyword NATIVE is optional but may be useful to specify exactly the nature of the required component, for instance is there are naming conflicts between component of different packages. Cannot be used together with NATIVE keyword.
[EXTERNAL] <component>:
 component is the external component that name depends upon. The keyword EXTERNAL is optional but may be useful to specify exactly the nature of the required component, for instance is there are naming conflicts between component of different packages. Cannot be used together with NATIVE keyword.
[EXPORT]:If this flag is present, the dependency is exported. It means that symbols of this dependency appears in component public headers. Cannot be used together with DEPEND keyword.
[DEPEND]:If this flag is present, the dependency is NOT exported. It means that symbols of this dependency do not appear in component public headers. Cannot be used together with EXPORT keyword. If none of EXPORT or DEPEND keyword are used, you must either use NATIVE or EXTERNAL keyword to specify the dependency.
[PACKAGE <package>]:
 package is the native package that contains the component. If PACKAGE is not used, it means either component is part of the current package or it can be found in current package dependencies.
[FRAMEWORK <framework>]:
 framework is the name of the framework containing the package that itself contains the component. Usable instead of PACKAGE.
[CONFIGURATION <framework>]:
 framework is the name of the framework containing the package that itself contains the component. Usable instead of PACKAGE.

Second signature

[EXTERNAL <package>]:
 

Name of the external package that component depends upon.
INCLUDE_DIRS <dirs>:
 

Specify include directories for this dependency. For external packages, these paths must be relative to the package root dir (using <package>).
LIBRARY_DIRS <path>:
 

Specify library search directories for this dependency. For external packages, these paths must be relative to the package root dir (using <package>).
RUNTIME_RESOURCES <paths>:
 

Specify where to find runtime resources. For external package, these paths must be relative to the package root dir (using <package>).
COMPILER_OPTIONS:
 

Compiler options that are not definitions.
LINKS STATIC|SHARED <links>:
 
  • STATIC <links>: static libraries. For system libraries, system referencing must be used (e.g. -lm for libm.a). For external packages, complete path (relative to the package root dir) must be used.
  • SHARED <links>: shared libraries. For system libraries, system referencing must be used (e.g. -lm for libm.a). For external packages, complete path (relative to the package root dir) must be used.

Third signature

[EXPORT]:If this flag is present, the dependency is exported. It means that symbols of this dependency appears in component public headers. Cannot be used together with DEPEND keyword.
[DEPEND]:If this flag is present, the dependency is NOT exported. It means that symbols of this dependency do not appear in component public headers. Cannot be used together with EXPORT keyword. If none of EXPORT or DEPEND keyword are used, you must either use NATIVE or EXTERNAL keyword to specify the dependency.
[CONFIGURATION <configuration>]:
 configuration is the name of the configuration defining the system dependency.

Constraints

  • Must be called after the component has been declared using PID_Component.

Effects

This function is used to defined a dependency between a component in the current package and another component. This will configure the build process accordingly.

Example

#declare a dependency to the content of an external package (do not use component description - NOT RECOMMENDED)
PID_Component_Dependency(COMPONENT my-static-lib
                                 EXTERNAL boost INCLUDE_DIRS <boost>/include
)

#declare a dependency to an external component that is NOT exported
PID_Component_Dependency(my-static-lib
                                 DEPEND EXTERNAL boost-headers PACKAGE boost
)

#declare a dependency to a system configuration that is NOT exported
PID_Component_Dependency(my-static-lib
                                 DEPEND CONFIGURATION posix
)

#declare a dependency to a native package of same project that is exported
PID_Component_Dependency(COMPONENT my-static-lib
                                 EXPORT NATIVE my-given-lib-bis
)

# suppose that package pid-rpath has been defined as a package dependency
declare_PID_Component_Dependency(my-static-lib
                                 DEPEND NATIVE rpathlib PACKAGE pid-rpath
)

# suppose that package pid-rpath has been defined as a package dependency
PID_Component_Dependency(my-static-lib DEPEND rpathlib)

# suppose that package pid-rpath has been defined as a package dependency
PID_Component_Dependency(my-other-lib EXPORT rpathlib)
#it is exported since includes of rpathlib are in public includes of my-other-lib

run_PID_Test

run_PID_Test(NAME ... [OPTIONS])

Run a test using an application.

The application can be: - an executable (e.g. valgrind) - a PID component (standard, example or test application) - a Python script

Common parameters

NAME <name>:Unique identifier for the test
ARGUMENTS <args>:
 (optional) Arguments passed to the executable, component or script

Executable parameters

EXE <name>:Name of the executable to run.

Component parameters

COMPONENT <name>:
 Name of the component to run.
PACKAGE <name>:Package to which the component belongs (defaults to the current package).

Python script

PYTHON:Flag the test as a Python test.

In that case, the first argument of ARGUMENTS is interpreted as a Python script, located in the test or share/script folder of the package.

Constraints

  • The component variant of this function must be called after the component has been declared.

Effects

Adds a test to the make test target. When the test is run it will generate a PASSED or ERROR message according to the result.

Example

run_PID_Test (NAME correctness_of_my-shared-lib_step1 COMPONENT my-test ARGUMENTS "first" "124" "12")
run_PID_Test (NAME correctness_of_my-shared-lib_step2 COMPONENT my-test ARGUMENTS "second" "12" "46")
run_PID_Test (NAME correctness_of_my-shared-lib_step3 COMPONENT my-test ARGUMENTS "first" "0" "87")

Advanced functions

external_PID_Package_Path

external_PID_Package_Path(NAME ... PATH ...)

Get the path to a target external package that is supposed to exist in the local workspace.

Required parameters

NAME <name>:Name of the target external package.
PATH <var>:<var> will contain the package root folder.

Constraints

  • This function must be called after a dependency to name has been declared using PID_Dependency.

Effects

No effect on the project.

Example

external_PID_Package_Path(NAME boost PATH BOOST_ROOT_PATH)
message(INFO "Boost root path is: ${BOOST_ROOT_PATH}")