Wrapper API

PID_Wrapper

PID_Wrapper(AUTHOR ... YEAR ... LICENSE ... DESCRIPTION ... [OPTIONS])
declare_PID_Wrapper(AUTHOR ... YEAR ... LICENSE ... DESCRIPTION ... [OPTIONS])
Declare the current CMake project as a PID wrapper for a given external package with specific meta-information passed as parameter.

Required parameters

AUTHOR <name>:Defines the name of the reference author.
YEAR <dates>:Reflects the lifetime of the wrapper, 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 wrapper. This must match one of the existing license file in the licenses directory of the workspace. This license applies to the wrapper and not to the original project.
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>:The url of the wrapper’s official repository. Must be set once the package is published.
PUBLIC_ADDRESS <url>:
 Can be used to 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.
CONTRIBUTION_SPACE <name>:
 name of the contribution space to use.

Constraints

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

Effects

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

Example

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

PID_Original_Project

PID_Original_Project(AUTHORS ... LICENSES ... URL ...)
define_PID_Wrapper_Original_Project_Info(AUTHORS ... LICENSES ... URL ...)
Set the meta information about original project being wrapped by current project.

Required parameters

AUTHORS <string>:
 Defines who are the authors of the original project.
LICENSES <string>:
 The licenses that applies to the original project content.
URL <url>:this is the index URL of the original project.

Constraints

  • This function must be called in the root CMakeLists.txt file of the wrapper, after declare_PID_Wrapper.
  • It must be called exactly once.

Effects

Sets the meta-information about original project.

Example

PID_Original_Project(
   AUTHORS "Boost.org contributors"
   LICENSES "Boost license"
   URL http://www.boost.org)

PID_Wrapper_Author

PID_Wrapper_Author(AUTHOR ... [INSTITUTION ...])
add_PID_Wrapper_Author(AUTHOR ... [INSTITUTION ...])
Add an author to the list of authors of the wrapper.

Required parameters

[AUTHOR] <string>:
 Name of the author. The keyword AUTHOR can be avoided if the name is given as first argument.

Optional parameters

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

Constraints

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

Effects

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

Example

PID_Wrapper_Author(AUTHOR Another Writter INSTITUTION LIRMM)

PID_Wrapper_Category

PID_Wrapper_Category(...)
add_PID_Wrapper_Category(...)
Declare that the current wrapper generates external packages that belong to a given category.

Required parameters

<string>:Name of the category

Constraints

  • This function must be called in the root CMakeLists.txt file of the wrapper, after declare_PID_Wrapper and before build_PID_Wrapper.

Effects

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

Example

PID_Wrapper_Category(example/packaging)

PID_Wrapper_Option

PID_Wrapper_Option(OPTION ... TYPE ... DEFAULT ... [DESCRIPTION ...])
define_PID_Wrapper_User_Option(OPTION ... TYPE ... DEFAULT ... [DESCRIPTION ...])
Define an option to configure the build of the wrapped project.

Required parameters

[OPTION] <name>:
 string defining the name of the user option. This name can then be used in deployment scripts. The option keyword can be omitted is name is given as first argument.
TYPE <type of the cmake option>:
 type of the option, to be chosen between: FILEPATH (File chooser dialog), PATH (Directory chooser dialog), STRING (Arbitrary string), BOOL.
DEFAULT …:Default value for the option.

Optional parameters

DESCRIPTION <string>:
 a string describing what this option is acting on.

Constraints

  • This function must be called in the root CMakeLists.txt file of the wrapper, after declare_PID_Wrapper and before build_PID_Wrapper.

Effects

Register a new user option into the wrapper. This user option will be used only in deployment scripts.

Example

PID_Wrapper_Option(OPTION BUILD_WITH_CUDA_SUPPORT
  TYPE BOOL DEFAULT OFF
  DESCRIPTION "set to ON to enable CUDA support during build")

PID_Wrapper_Publishing

PID_Wrapper_Publishing(PROJECT ... GIT|FRAMEWORK ... [OPTIONS])
declare_PID_Wrapper_Publishing(PROJECT ... GIT|FRAMEWORK ... [OPTIONS])
Declare that the current wrapper generates external packages that belong to a given category.

Required parameters

PROJECT <url>:This argument tells where to fing the official repository project page of the wrapper. This is used to reference the wrapper project into the static site.

Optional parameters

ALLOWED_PLATFORMS <list of platforms>:
 This argument limits the set of platforms used for CI, only platforms specified 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.
DESCRIPTION <string>:
 This is a long(er) description of the wrapper that will be used for its documentation in static site.
PUBLISH_BINARIES:
 If this argument is used then the wrapper will automatically publish new binary versions to the publication site.
FRAMEWORK <name of the framework>:
 If this argument is set, then it means that the wrapper belongs to a framework. It will so contribute to the framework site. You must use either this argument or GIT one.
GIT <repository address>:
 This is the address of the lone static site repository for the wrapper. It is used to automatically clone/update the static site of the wrapper. With this option the wrapper will not contribute to a framework but will have its own isolated deployment. You must use either this argument or FRAMEWORK one.
PAGE <url>:This is the online URL of the static site index page. Must be used if you use the GIT argument.
CATEGORIES <list>:
 list of categories the package belongs to into the framework

Constraints

  • This function must be called in the root CMakeLists.txt of the package, after declare_PID_Wrapper and before build_PID_Wrapper.
  • This function must be called it has to be called after any other following functions: add_PID_Wrapper_Author, add_PID_Wrapper_Category and define_PID_Wrapper_Original_Project_Info.

Effects

  • 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 <pid-workspace>/sites/packages/<wrapper name>. If it belongs to a framework, the framework repository can be found in <pid-workspace>/sites/frameworks/<framework name>. In this later case, the wrapper only contributes to its own related content not the overall content of the framework.
  • Depending on options it can also deploy binaries for target platform into the static site repository (framework or lone static site).

Example

PID_Wrapper_Publishing(
  PROJECT https://gite.lirmm.fr/pid/boost
  FRAMEWORK pid
  DESCRIPTION boost is a PID wrapper for external project called Boost. Boost provides many libraries and templates to ease development in C++.
  PUBLISH_BINARIES
  ALLOWED_PLATFORMS x86_64_linux_stdc++11__ub20_gcc9__)

build_PID_Wrapper

build_PID_Wrapper()
Configure the PID wrapper according to overall information.

Constraints

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

Effects

This function generates configuration files, manage the generation of the global build process and call CMakeLists.txt files of version folders contained in subfolder src.

Example

build_PID_Wrapper()

PID_Wrapper_Version

PID_Wrapper_Version(VERSION ... DEPLOY ... [OPTIONS])
add_PID_Wrapper_Known_Version(VERSION ... DEPLOY ... [OPTIONS])
Declare a new version of the original project wrapped into PID system.

Required parameters

[VERSION] <version string>:
 tells which version of the external package is being wrapped. The version number must exactly match the name of the folder containing the CMakeLists.txt that does this call. The keyword version may be omitted is version is the first argument.
DEPLOY <path to deploy script>:
 This is the path, relative to the current folder, to the deploy script used to build and install the external package version. Script must be a cmake module file.

Optional parameters

POSTINSTALL <path to install script>:
 This is the path, relative to the current folder, to the install script that will be run after external package version has been installed into the workspace, to perform additionnal configuration steps. Script is a cmake module file.
PREUSE <path to use script>:
 This is the path, relative to the current folder, to the install script that will be run anytime a package uses this version.
COMPATIBILITY <version number>:
 define which previous version is compatible with this current version, if any. Compatible simply means that this current version can be used instead of the previous one without any restriction.
SONAME <version number>:
 (useful on UNIX only) Specify which soname will be given by default to all shared libraries defined by the wrapper.
CMAKE_FOLDER <path to folder>:
 (useful on CMake projects only) Specify the path, relative to the package install root, where to fond CMake configuration files.
PKGCONFIG_FOLDER <path to folder>:
 (useful for projects supporting pkg-config only) Specify the path, relative to the package install root, where to find pkg-config configuration files.

Constraints

  • This function must be the first one called in the CMakeList.txt file of a version folder.

Effects

Configure information about a specific version of the external package.

Example

PID_Wrapper_Version(VERSION 1.55.0 DEPLOY deploy.cmake
    SONAME 1.55.0 #define the extension name to use for shared objects
)

PID_Wrapper_Environment

PID_Wrapper_Environment(...)
declare_PID_Wrapper_Environment(... )
Declare a configuration constraint on the build environment for the current version of the external project being described.

Required parameters

OPTIONAL:if used then the requirement on build environment is optional.
LANGUAGE …:Set of constraint check expressions defining which languages must/can be used (testing only C and C++ is not necessary).
TOOLSET …:Set of constraint check expressions defining which toolset must/can be used for target language. If many languages are specified then there must have as many toolsets defined, in same order.
TOOL …:Set of constraint check expressions defining which tools (compiler, interpreter, generators, etc.) must/can be used.

Optional parameters

PLATFORM <platform name>:
 Use to apply the configuration constraints only to the target platform.

Constraints

  • This function must be called in the CMakeList.txt file of a version folder after add_PID_Wrapper_Known_Version.

Effects

  • Configure the check of a set of platform configurations that will be perfomed when the given wrapper version is built.

Example

PID_Wrapper_Environment(LANGUAGE CUDA)

PID_Wrapper_Configuration

PID_Wrapper_Configuration(REQUIRED|OPTIONAL ... [PLATFORM ...])
declare_PID_Wrapper_Platform_Configuration(CONFIGURATION ... [PLATFORM ...])
Declare a platform configuration constraint for the current version of the external project being described.

Required parameters

REQUIRED|CONFIGURATION <list of configurations>:
 list of configuration expression defining the required target platform configurations.
OPTIONAL <list of configurations>:
 list of configuration expression defining the required target platform configurations.

Optional parameters

PLATFORM <list of platform or OS name>:
 Used to apply the configuration constraints only to the target platform (e.g. x86_64_linux_stdc++11) or operating system (e.g. linux).

Constraints

  • This function must be called in the CMakeList.txt file of a version folder after add_PID_Wrapper_Known_Version.

Effects

  • Configure the check of a set of platform configurations that will be perfomed when the given wrapper version is built.

Example

PID_Wrapper_Configuration(REQUIRED posix)

PID_Wrapper_Dependency

PID_Wrapper_Dependency([PACKAGE] ... [[EXACT] VERSION ...]...)
declare_PID_Wrapper_External_Dependency([PACKAGE] ... [[EXACT] VERSION ...]...)

Declare a dependency between the currently described version of the external package and another external package.

Required parameters

[PACKAGE] <string>:
 defines the unique identifier of the required package. The keyword PACKAGE may be omitted if name is the first argument.

Optional parameters

VERSION <version string>:
 dotted notation of a version, representing which version of the external package is required. May be use many times.
EXACT:use to specify if the following version must be exac. May be used for earch VERSION specification.
COMPONENTS <list of components>:
 Used to specify which components of the required external package will be used by local components. If not specified there will be no check for the presence of specific components in the required package.

Constraints

  • This function must be called in the CMakeList.txt file of a version folder after add_PID_Wrapper_Known_Version.

Effects

  • Register the target package as a dependency of the current package.

Example

PID_Wrapper_Dependency (PACKAGE boost EXACT VERSION 1.55.0 EXACT VERSION 1.63.0 EXACT VERSION 1.64.0)

PID_Wrapper_Component

PID_Wrapper_Component([COMPONENT] ... [OPTIONS])
declare_PID_Wrapper_Component([COMPONENT] ... [OPTIONS])

Declare a new component for the current version of the external package.

Required parameters

[COMPONENT] <string w/o withespaces>:
 defines the unique identifier of the component. The COMPONENT keyword may be omnitted if name if the first argument.

Optional parameters

C_STANDARD <number of standard>:
 version of the C language standard to be used to build this component. The values may be 90, 99 or 11.
C_MAX_STANDARD <number of standard>:
 max version of the C language standard allowed when using this component.
CXX_STANDARD <number of standard>:
 version of the C++ language standard to be used to build this component. The values may be 98, 11, 14 or 17. If not specified the version 98 is used.
CXX_MAX_STANDARD <number of standard>:
 max version of the C++ language standard to be used to build this component. If not specified the version 98 is used.
SONAME <version number>:
 allows to set the SONAME to use for that specific library instead of the default one.
DEFINITIONS <defs>:
 preprocessor definitions used in the component’s interface.
INCLUDES <folders>:
 include folders to pass to any component using the current component. Path are interpreted relative to the installed external package version root folder.
SHARED_LINKS <links>:
 shared link flags. Path are interpreted relative to the installed external package version root folder.
DEBUG_SUFFIX suffix:
 Suffix to add to libraries binaries names when built in Debug mode.
FORCED_SHARED_LINKS <links>:
 shared links whose binary is forced to be linked into dependent binaries (see -Wl,no-as-needed)
STATIC_LINKS <links>:
 static link flags. Path are interpreted relative to the installed external package version root folder.
OPTIONS <compile options>:
 compiler options to be used whenever a third party code use this component. This should be used only for options bound to compiler usage, not definitions or include directories.
RUNTIME_RESOURCES <list of path>:
 list of path relative to the installed external package version root folder.
EXPORT …:list of components that are exported by the declared component. Each element has the pattern [<package name>/]<component_name>.
DEPEND …:list of components that the declared component depends on. Each element has the pattern [<package name>/]<component_name>.
ALIAS …:list of alias for naming the component.
PYTHON …:list of files and/or folder that define a python package. Used to define python bindings.

Constraints

  • Must be called in the CMakeList.txt file of a version folder after add_PID_Wrapper_Known_Version and before any call to declare_PID_Wrapper_Component_Dependency applied to the same declared component.

Effects

  • Define a component for the current external package version, which is mainly usefull to register all compilation options relative to a component.

Example

PID_Wrapper_Component(COMPONENT libyaml INCLUDES include SHARED_LINKS ${posix_LINK_OPTIONS} lib/libyaml-cpp)

PID_Wrapper_Component_Dependency

PID_Wrapper_Component_Dependency([COMPONENT] ... [OPTIONS])
declare_PID_Wrapper_Component_Dependency([COMPONENT] ... [OPTIONS])

Declare a dependency for a component defined in the current version of the current external package.

Required parameters

[COMPONENT] <string w/o withespaces>:
 defines the unique identifier of the component for which a dependency is described. The keyword COMPONENT may be omitted if name is given as first argument.

Optional parameters

EXPORT:Tells whether the component exports the required dependency. Exporting means that the reference to the dependency is contained in its interface (header files). This can be only the case for libraries, not for applications.
DEPEND:Tells whether the component depends on but do not export the required dependency. Exporting means that the reference to the dependency is contained in its interface (header files).
[EXTERNAL] <dependency>:
 This is the name of the component whose component <name> depends on. EXTERNAL keyword may be omitted if EXPORT or DEPEND keyword are used.
PACKAGE <name>:This is the name of the external package the dependency belongs to. This package must have been defined has a package dependency before this call. If this argument is not used, the dependency belongs to the current package (i.e. internal dependency).
DEFINITIONS <definitions>:
 List of definitions exported by the component. These definitions are supposed to be managed in the dependency’s heaedr files, but are set by current component.
INCLUDES <list of path>:
 List of path to system include folders.
LIBRARY_DIRS <list of path>:
 List of path to system libraries folders.
SHARED_LINKS <list of link>:
 List of shared system links.
STATIC_LINKS <list of link>:
 List of static system links.
OPTIONS <list of options>:
 List of compiler options to use when using a system library.
RUNTIME_RESOURCES <list of path>:
 List of path to system runtime resource such as program for instance.
C_STANDARD <std number>:
 the C standard used by the dependency.
CXX_STANDARD <std number>:
 the C++ standard used by the dependency.

Constraints

  • Must be called in the CMakeList.txt file of a version folder after add_PID_Wrapper_Known_Version and after any call to declare_PID_Wrapper_Component applied to the same declared component.

Effects

  • Define and configure a dependency between a component in the current external package version and another component.

Example

PID_Wrapper_Component_Dependency(COMPONENT libyaml EXPORT EXTERNAL boost-headers PACKAGE boost)

PID_Wrapper_System_Configuration

PID_Wrapper_System_Configuration(EVAL ... VARIABLES ... VALUES ... [OPTIONS])
declare_PID_Wrapper_System_Configuration(EVAL ... VARIABLES ... VALUES ... [OPTIONS])
To be used in check files of configuration. Used to declare the list of output variables generated by a configuration and how to set them from variables generated by the find file.

Required parameters

<name>:the name of the configuration.
EVAL <path to eval file>:
 path to the system configuration evaluation CMake script, relative to system folder.
VARIABLES <list of variables>:
 the list of variables that are returned by the configuration.
VALUES <list of variables>:
 the list of variables used to set the value of returned variables. This lis is ordered the same way as VARIABLES, so that each variable in VALUES matches a variable with same index in VARIABLES.

Optional parameters

FIND_PACKAGES <list of find modules>:
 list of find modules directly provided by the wrapper.
INSTALL <path to install file>:
 path to the CMake script used to install the system configuration, relative to system folder
LANGUAGES <list of languages>:
 list of special languages (CUDA, Python, Fortran) required by the system configuration.
USE <path to use file>:
 path to the CMake script that provide CMake functions/macro definition that will be usable anytime by packages when the system configuration is checked.
LANGUAGES <list of languages>:
 list of special languages (CUDA, Python, Fortran) required by the system configuration.
ADDITIONAL_CONTENT <list of path>:
 list of path to files and folders used by the evaluation script.
APT|PACMAN|YUM|BREW|PORT|CHOCO <list of packages>:
 automatic install procedure defining which packages must be installed depending of the corresponding packaging system of the host.

Constraints

  • This function can be called in the check file provided by a configuration.

Effects

Memorize variables used for the given configuration.

Example

# the configuration boost returns differents variables such as: boost_VERSION, boost_RPATH, etc...
# These variable are set according to the value of respectively: BOOST_VERSION, Boost_LIBRARY_DIRS, etc.
declare_PID_Wrapper_System_Configuration(
   EVAL eval_boost.cmake
   VARIABLES VERSION       LIBRARY_DIRS        INCLUDE_DIRS        RPATH
   VALUES    BOOST_VERSION Boost_LIBRARY_DIRS  Boost_INCLUDE_DIRS  Boost_LIBRARY_DIRS
)
PID_Wrapper_System_Configuration_Variables(
   EVAL eval_boost.cmake
   VARIABLES VERSION       LIBRARY_DIRS        INCLUDE_DIRS        RPATH
   VALUES    BOOST_VERSION Boost_LIBRARY_DIRS  Boost_INCLUDE_DIRS  Boost_LIBRARY_DIRS
)

PID_Wrapper_System_Configuration_Constraints

PID_Wrapper_System_Configuration_Constraints([OPTIONS...])
declare_PID_Wrapper_System_Configuration_Constraints([OPTIONS...])
To be used in check files of configuration. Used to declare the list of constraints managed by the configuration.

Optional parameters

REQUIRED <list of variables>:
 The list of required constraints. Required means that the constraints must be specified at configuration check time. All required constraints always appear in final binaries description.
OPTIONAL <list of variables>:
 The list of optional constraints. Optional means that the constraints value can be ignored when considering binaries AND no paremeter can be given for those constraints at configuration check time.
IN_BINARY <list of variables>:
 The list of optional constraints at source compilation time but that are required at binary usage time.
VALUE <list of variables>:
 The list variables used to set the value of the corresponding list of variables IN_BINARY. Used to initialize the value of constraints used only at binary usage time.

Constraints

  • This function can be called in the check file provided by a configuration.

Effects

Memorize constraints that can be used for the given configuration.

Example

declare_PID_Wrapper_System_Configuration_Constraints(ros REQUIRED distribution IN_BINARY packages VALUE ROS_PACKAGES)

PID_Wrapper_System_Configuration_Constraints(ros REQUIRED distribution IN_BINARY packages VALUE ROS_PACKAGES)

PID_Wrapper_System_Configuration_Dependencies

PID_Wrapper_System_Configuration_Dependencies(DEPEND ...)
declare_PID_Wrapper_System_Configuration_Dependencies(DEPEND ...)
To be used in check files of configuration. Used to declare the list of configuration that the given configuration depends on.

Required parameters

DEPEND <list of configuration checks>:
 The list of expressions representing the different systems configurations used by given configuration.

Constraints

  • This function can be called in the check file provided by a configuration.

Effects

Memorize dependencies used by the given configuration.

Example

declare_PID_Wrapper_System_Configuration_Dependencies(ros DEPEND boost)

PID_Wrapper_System_Configuration_Dependencies(ros DEPEND boost)

Script functions

get_External_Dependencies_Info

get_External_Dependencies_Info([OPTIONS])

Allow to get info defined in description of the currenlty built version.

Optional parameters

PACKAGE <ext_package>:
 Target external package that is a dependency of the currently built package, for which we want specific information. Used as a filter to get information only for a given dependency.
COMPONENT:Filter to get only information relative to a component. Mustbe used together with PACKAGE to get only info relative to a component dependency.
LOCAL:Filter to get only local information. Must be used together with PACKAGE and optionally with COMPONENT.
ROOT <variable>:
 The variable passed as argument will be filled with the path to the dependency external package version. Must be used together with PACKAGE.
CMAKE <variable>:
 The variable passed as argument will be filled with the path to the folder containing CMake config files. Only usable with PACKAGE.
PKGCONFIG <variable>:
 The variable passed as argument will be filled with the path to the folder containing pkgconfig config files. Only usable with PACKAGE.
OPTIONS <variable>:
 The variable passed as argument will be filled with compiler options for the external package version being built.
INCLUDES <variable>:
 The variable passed as argument will be filled with include folders for the external package version being built.
DEFINITIONS <variable>:
 The variable passed as argument will be filled with all definitions for the external package version being built.
LINKS <variable>:
 The variable passed as argument will be filled with all path to librairies and linker options for the external package version being built.
LIBRARY_DIRS <variable>:
 The variable passed as argument will be filled with all path to folders containing libraries.
C_STANDARD <variable>:
 The variable passed as argument will be filled with the C language standard to use for the external package version, if any specified.
CXX_STANDARD <variable>:
 The variable passed as argument will be filled with the CXX language standard to use for the external package version, if any specified.
RESOURCES <variable>:
 The variable passed as argument will be filled with the runtime resources provided by external dependencies.
FLAGS:option to get result of all preceeding arguments directly as compiler flags instead of CMake variables.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • This function has no side effect but simply allow the wrapper build process to get some information about the package it is trying to build. Indeed, building an external package may require to have precise information about package description in order to use adequate compilation flags.

Example

Example of deploy script used for the yaml-cpp wrapper:

get_External_Dependencies_Info(INCLUDES all_includes)
execute_process(COMMAND ${CMAKE_COMMAND} -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=${TARGET_INSTALL_DIR} -DBoost_INCLUDE_DIR=${all_includes} .. WORKING_DIRECTORY ${YAML_BUILD_DIR})

get_User_Option_Info

get_User_Option_Info(OPTION ... RESULT ...)

Allow to get info defined and set by user of the wrapper into deploy script when a wrapper version is built.

Required parameters

OPTION <variable>:
 Target option we need to get the value into the deploy script.
RESULT <returned variable>:
 The variable passed as argument will be filled with the value of the target user option’s value.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • This function has no side effect but simply allow the wrapper build process to get some information about the package it is trying to build. Indeed, building an external package may require additional configuration from the user in order to use adequate compilation flags.

Example

get_User_Option_Info(OPTION BUILD_WITH_CUDA_SUPPORT RESULT using_cuda)
if(using_cuda)
  build_process_using_CUDA(...)
else()
  build_process_without_CUDA(...)
endif()

install_External_Project

install_External_Project([URL ...] ARCHIVE|GIT_CLONE_COMMIT ... FOLDER ... PATH ... [OPTIONS])
Install the external project into build tree. This project can be either:
  • downloaded as an archive from an online archive filesystem
  • cloned from an online git repository
  • extracted from a local archive provided by the wrapper

Required parameters

ARCHIVE|GIT_CLONE_COMMIT <string>:
 The name of the archive downloaded (or its path relative to current source dir if not download) or the identifier of the commit to checkout to. Both keyword ARCHIVE and GIT_CLONE_COMMIT are exclusive.
FOLDER <string>:
 The folder resulting from archive extraction or repository cloning.

Optional parameters

URL <url>:The URL from where to download the archive or to clone the project.
GIT_CLONE_ARGS <list of arguments>:
 List of argument to use when cloning.
PATH <path>:the output variable that contains the path to the installed project, empty if project cannot be installed
PROJECT <string>:
 the name of the project if you want to generate nice outputs about external package install process
VERSION <version string>:
 the version of the external project that is installed, only usefull together with PROJECT keyword.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • This function is used to download and install the archive of an external project.

Example

install_External_Project( PROJECT yaml-cpp
                  VERSION 0.6.2
                  URL https://github.com/jbeder/yaml-cpp/archive/yaml-cpp-0.6.2.tar.gz
                  ARCHIVE yaml-cpp-0.6.2.tar.gz
                  FOLDER yaml-cpp-yaml-cpp-0.6.2)

return_External_Project_Error

return_External_Project_Error()

Make the current wrapper script to return an error.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • generates an error code for the current deploy script.

Example

return_External_Project_Error()

build_B2_External_Project

build_B2_External_Project(PROJECT ... FOLDER ... MODE ... [OPTIONS])

Configure, build and install an external project defined with Boost build. WARNING: this function is usable only in wrappers, to build Boost build projects

Required parameters

PROJECT <string>:
 The name of the external project.
FOLDER <string>:
 The name of the folder containing the project.
MODE <Release|Debug>:
 The build mode.

Optional parameters

QUIET:if used then the output of this command will be silent.
COMMENT <string>:
 A string to append to message to inform about special thing you are doing. Usefull if you intend to buildmultiple time the same external project with different options.
DEFINITIONS <list of definitions>:
 the CMake definitions you need to provide to the cmake build script.
WITH <list of libraries>:
 Libraries to be included in the build
WITHOUT <list of libraries>:
 Libraries to be excluded from the build

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • Build and install the external project into workspace install tree..

Example

in wrapper content description file:

  PID_Wrapper_Environment(b2)

in wrapper deploy script:

  build_B2_External_Project(PROJECT boost FOLDER boost_1_64_0 MODE Release)

build_Autotools_External_Project

build_Autotools_External_Project(PROJECT ... FOLDER ... MODE ... [OPTIONS])

Configure, build and install an external project defined with GNU autotools.

Required parameters

PROJECT <string>:
 The name of the external project.
FOLDER <string>:
 The name of the folder containing the project.
MODE <Release|Debug>:
 The build mode.

Optional parameters

QUIET:if used then the output of this command will be silent.
COMMENT <string>:
 A string to append to message to inform about special thing you are doing. Usefull if you intend to buildmultiple time the same external project with different options.
DEFINITIONS <list of definitions>:
 the CMake definitions you need to provide to the cmake build script.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • Build and install the external project into workspace install tree..

Example

build_Autotools_External_Project(PROJECT aproject FOLDER a_project_v12 MODE Release)

build_Colcon_Workspace

build_Colcon_Workspace(PROJECT ... WORKSPACE ...)

Build a colcon workspace that contains a set of projects.

Required parameters

PROJECT <string>:
 The global name of the external project defined as a workspace.
WORKSPACE <string>:
 The path to the colcon workspace, relative to root build folder.

Optional parameters

MODE <Rlease|Debug>:
 The global name of the external project defined as a workspace.
COMMENT <string>:
 comment printed during execution.
RPATH <list of strings>:
 additionnal rpath to set (for plugins).
DEFINITIONS <list of defs>:
 additionnal cmake definitions for colcon packages.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • build all porjects in the workspace .

Example

build_Colcon_Workspace(PROJECT gazebo WORKSPACE workspace Mode Release)

build_Waf_External_Project

build_Waf_External_Project(PROJECT ... FOLDER ... MODE ... [OPTIONS])

Configure, build and install an external project defined with python Waf tool.

Required parameters

PROJECT <string>:
 The name of the external project.
FOLDER <string>:
 The name of the folder containing the project.
MODE <Release|Debug>:
 The build mode.

Optional parameters

COMMENT <string>:
 A string to append to message to inform about special thing you are doing. Usefull if you intend to buildmultiple time the same external project with different options.
DEFINITIONS <list of definitions>:
 the CMake definitions you need to provide to the cmake build script.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • Build and install the external project into workspace install tree..

Example

build_Waf_External_Project(PROJECT aproject FOLDER a_project_v12 MODE Release)

build_CMake_External_Project

build_CMake_External_Project(URL ... ARCHIVE ... FOLDER ... PATH ... [OPTIONS])

Configure, build and install a Cmake external project.

Required parameters

PROJECT <string>:
 The name of the external project.
FOLDER <string>:
 The name of the folder containing the project.
Mode <Release|Debug>:
 The build mode.

Optional parameters

COMMENT <string>:
 A string to append to message to inform about special thing you are doing. Usefull if you intend to buildmultiple time the same external project with different options.
DEFINITIONS <list of definitions>:
 the CMake definitions you need to provide to the cmake build script.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • Build and install the external project into workspace install tree..

Example

build_CMake_External_Project( PROJECT yaml-cpp FOLDER yaml-cpp-yaml-cpp-0.6.2 MODE Release
                      DEFINITIONS BUILD_GMOCK=OFF BUILD_GTEST=OFF BUILD_SHARED_LIBS=ON YAML_CPP_BUILD_TESTS=OFF YAML_CPP_BUILD_TESTS=OFF YAML_CPP_BUILD_TOOLS=OFF YAML_CPP_BUILD_CONTRIB=OFF gtest_force_shared_crt=OFF
                      COMMENT "shared libraries")

get_Current_External_Version

get_Current_External_Version(RESULT_VERSION)

Get the version of external package that is currently built or defined

check_External_Project_Required_CMake_Version

check_External_Project_Required_CMake_Version(version)

check that current version of CMake is greater than minimum version required by deployment script

patch_CMake_Project_Min_Version

patch_CMake_Project_Min_Version(project_folder)

Automatically patch the project CMakeLists.txt

Required parameters

Project_folder:Target external package that is a dependency of the currently built package, for which we want specific information. Used as a filter to get information only for a given dependency.

Constraints

  • Must be used in deploy scripts defined in a wrapper.

Effects

  • This function change the cmake_minimum_required constraint in the CMakeLists.txt contained in project folder

Example

Example in eigen wrapper:

Platform Configuration functions

found_PID_Configuration

found_PID_Configuration(config value)
Declare the configuration as FOUND or NOT FOUND.

Required parameters

<config>:the name of the configuration .
<value>:TRUE if configuration has been found or FALSE otherwise .

Constraints

  • This function must be called in the find file provided by a configuration.

Effects

Change configuration status to FOUND or NOT FOUND.

Example

found_PID_Configuration(boost TRUE)

installable_PID_Configuration

installable_PID_Configuration(config value)
Declare the configuration as INSTALLABLE or NOT INSTALLABLE.

Required parameters

<config>:the name of the configuration .
<value>:TRUE if configuration can be installed or FALSE otherwise .

Constraints

  • This function must be called in the installable file provided by a configuration.

Effects

Change configuration status to INSTALLABLE or NOT INSTALLABLE.

Example

installable_PID_Configuration(boost TRUE)

execute_OS_Configuration_Command

execute_OS_Configuration_Command([NOT_PRIVILEGED] [OUTPUT_VARIABLE var] ...)
invoque a command of the operating system with adequate privileges.

Required parameters

NOT_PRIVILEGED:is used first argument passed for privileged execution is never required
OUTPUT_VARIABLE var:
 contains the output from std output and error
…:the command to be executed (do not use sudo !)

Effects

Execute the command with adequate privileges .

Example

execute_OS_Configuration_Command(apt-get install -y libgtk2.0-dev libgtkmm-2.4-dev)

resolve_PID_System_Libraries_From_Path

resolve_PID_System_Libraries_From_Path(list_of_path
ALL_SHARED_LIBRARIES_REAL_PATH
ALL_SHARED_LIBRARIES_SONAME
ALL_STATIC_LIBRARIES_REAL_PATH
Utility function to be used in system configuration eval script (cf. Wrapper API). Resolve real path to libraries’ binaries (i.e. resolve linker scripts) and get their soname. Typically used after a call to find_package.

Required parameters

<list_of_path>:the list of path to libraries.
<ALL_SHARED_LIBRARIES_REAL_PATH>:
 the output variable that contains the list of path to real binaries in operating system filesystem.
<ALL_SHARED_LIBRARIES_SONAME>:
 the output variable that contains the list of the libraries sonames.
<ALL_STATIC_LIBRARIES_REAL_PATH>:
 the output variable that contains the list of path to static libraries.
<ALL_LINKS_PATH>:
 the output variable that contains the list of path to links (or real path if no link) used to target the libraries used (either static or shared).

Constraints

  • This function can be called in the eval script of a system configuration.

Effects

No side effect.

Example

find_package(OpenSSL REQUIRED)
resolve_PID_System_Libraries_From_Path("${OpenSSL_LIBRARIES}" ALL OPENSSL_LIBS OPENSSL_SONAMES)

find_PID_Library_In_Linker_Order

find_PID_Library_In_Linker_Order(possible_library_names search_folders_type LIBRARY_PATH LIB_SONAME)
Utility function to be used in configuration find script. Try to find a library in same order as the linker.

Required parameters

<possible_library_names_or_path>:
 the list of possible names or path for the library.
<search_folders_type>:
 if equal to “ALL” all path will be searched in. If equal to “IMPLICIT” only implicit link folders (non user install folders) will be searched in. If equal to “USER” implicit link folders are not used.
<LIBRARY_PATH>:the output variable that contains the path to the library in the system.
<LIB_SONAME>:the output variable that contains the SONAME of the library, if any (for shared libraries).

Optional parameters

<out_var_link>:the output variable that contains the path to link used to target the library (or real path if direct path is used)

Constraints

  • This function can be called in the find file provided by a configuration.

Effects

No side effect.

Example

find_PID_Library_In_Linker_Order("tiff" ALL TIFF_LIB TIFF_SONAME)

convert_PID_Libraries_Into_Library_Directories

convert_PID_Libraries_Into_Library_Directories(list_of_libraries_var OUT_VAR)
Utility function to be used in configuration find script. Extract the library directories to use to find them from absolute path to libraries.

Required parameters

<list_of_libraries_var>:
 the name of the variable that contains the list of libraries to convert.
<OUT_VAR>:the output variable that contains the list of path to libraries folders.

Constraints

  • This function can be called in the find file provided by a configuration.

Effects

No side effect.

Example

convert_PID_Libraries_Into_Library_Directories(BOOST_LIBRARIES BOOST_LIB_DIRS)

extract_Soname_From_PID_Libraries

extract_Soname_From_PID_Libraries(list_of_libraries_var OUT_VAR)
Utility function to be used in configuration find script. Extract the libraries sonames from libraries path.

Required parameters

<list_of_libraries_var>:
 the name of the variable that contains the list of libraries to convert.
<OUT_VAR>:the output variable that contains the list of sonames, in same order.

Constraints

  • This function can be called in the find file provided by a configuration.

Effects

No side effect.

Example

extract_Soname_From_PID_Libraries(CURL_SONAMES CURL_LIB)

extract_Symbols_From_PID_Libraries

extract_Symbols_From_PID_Libraries(list_of_libraries_var list_of_symbols OUT_LIST_OF_SYMBOL_VERSION_PAIRS)
Utility function to be used in configuration find script. Extract the libraries symbols from libraries path.

Required parameters

<list_of_libraries_var>:
 the name of the variable that contains the list of libraries to check.
<list_of_symbols>:
 the name of the variable that contains the list of symbols to find.
<OUT_LIST_OF_SYMBOL_VERSION_PAIRS>:
 the output variable that contains the list of pairs <symbol,max version>.

Constraints

  • This function can be called in the find file provided by a configuration.

Effects

No side effect.

Example

extract_Symbols_From_PID_Libraries(OPENSSL_SYMBOLS OPENSSL_LIB "OPENSSL_")

extract_Version_Numbers

extract_Version_Numbers(MAJOR MINOR PATCH version)
extract numbers from a version string

Required parameters

MAJOR:the output variable that contains the major number of version.
MINOR:the output variable that contains the minor number of version.
PATCH:the output variable that contains the patch number of version.
Version:the full version string

Example

extract_Version_Numbers(MAJOR MINOR PATCH 1.2.3)
message("major number is ${MAJOR}")