A PID wrapper provides a set of useful commands to manage its lifecycle. As usual these commands can be called from the build folder of the wrapper project using the native build tool (e.g. make) or by using the pid script directly into the wrapper folder.

If using the build tool, the project must be configured before using CMake:

cd <workspace dir>/wrappers/<wrapper name>/build
cmake .. #building commands

We suppose here we use the pid script but any native build system (e.g. make, ninja) can be used with same commands (these commands are then targets for the build tool and arguments are environment variables).

Commands summary

  • build: building the wrapper for a given version.
  • hard_clean: Hard cleaning the build tree of the wrapper.
  • sysinstall: installing the target external package version binaries into a folder of the operating system.
  • uninstall: Uninstalling the wrapper installed binary folder for a given version.
  • update: Updating the wrapper content from its official repository.
  • referencing: Referencing the wrapper in the workspace.
  • site: Generating the static website supporting the documentation of the wrapper.
  • memorizing: Identifying managed versions.
  • gen_system_check: Generating scripts used to check system configuration when wrapper define a system dependency.
  • rem_system_check: Removing scripts used to check system configuration when wrapper define a system dependency.
  • eval_system_check: Evaluating target platform system configuration.
  • list_versions: Listing available versions defined by the external package wrapper.

Building and deploying

  • Call: pid build
  • Effect: runs the deploy script for a given version of the external package wrapper. If everything works well the result is a binary version of the external package deployed in the workspace.

  • Arguments:

    • Mandatory argument:

      • version: indicates which version of the external package has to be built.

    • Optional arguments:

      • skip_script: if true (default to false) then do no execute deployment script, simply regenerate the PID cmake configuration file for the target version.
      • archive: if true (default to false) then the build process generates a binary archive for this version in build folder. This is mainly used for CI, only eprerienced user should use this option.

    • mode: either Release (default) or Debug depending on what kind of binaries the user expects.

  • Example:

  • For a normal build of the boost external package:
pid cd boost
pid build version=1.63.0
  • For a debug build of the boost external package:
pid cd boost
pid build version=1.63.0 mode=Debug

Cleaning the build tree

  • Call: pid hard_clean
  • Effect: Cleaning the whole wrapper build tree in a agressive and definitive way.

  • Arguments: none

  • Example:
pid cd <wrapper>
pid hard_clean

Installing in operating system

  • Call: pid sysinstall
  • Effect: installs the external package binary version resulting from the build and all its dependencies into the target folder of the operating system.
  • Arguments:
    • folder: system folder where to install the package and its dependencies.
    • mode: mode of binaries (Release or Debug). Release is default.
    • version: version of the external package to be installed.
  • Example:
pid cd boost
pid sysinstall folder=/usr/local mode=Release version=1.72.0

Uninstalling a version

  • Call: pid uninstall
  • Effect: uninstall the wrapper target version from install tree. The build tree will not be cleaned by this command.

  • Mandatory Argument:

    • version: indicates which version of the external package has to be uninstalled.
  • Example:
pid cd <wrapper>
pid uninstall version=1.2.3

Updating the wrapper

  • Call: pid update
  • Effect: updates the local repository of the wrapper from its official remote.

  • Arguments: none

  • Example:
pid cd <wrapper>
pid update

Referencing the wrapper in the workspace

  • Call: pid referencing
  • Effect: generates the reference file for the wrapper and places it in the adequate folder of the workspace. When done, the wrapper is known in the local workspace and will be known by all users when workspace official repository will be updated accordingly.

  • Optional argument:

    • space: define the target contribution space to use, in addition to all contributions spaces already containing references for the wrapper. This argument is particularly usefull first time you reference the wrapper.
  • Example:
pid cd <wrapper>
pid referencing

Generating documentation website

  • Call: pid site
  • Effect: generates and updates the website project that support the online documentation of the wrapper. This can be either a lone website or a framework depending on how the website has been defined in the wrapper.

  • Optional arguments:

    • synchro (default to true): if true the commands will automatically push modifications performed in the static site repository.
    • {advanced} force (default to false): if true the commands will force the check process for all modifications. This is used to preserve time of the process and size of the static site git repository. Should not be used by end users except in really rare cases.

  • Example:

  • Generating the site content of the wrapper but without trying to publish it (usefull for documentation debug)
pid cd <wrapper>
pid site synchro=false

Identifying managed versions

  • Call: pid memorizing

  • Effect: memorize a (new or updated) version that is managed by the wrapper. In practice it simply regenerate a version tag and update the official remote which in turn force the launch of the CI process.

  • Mandatory arguments:

    • version: the new or updated version to memorize.
  • Example: let’s suppose the version 1.56.0 of boost is newly managed in the PID wrapper.
pid cd boost
pid memorizing version=1.56.0

Generating platform configuration evaluation

  • Call: pid gen_system_check

  • Effect: Generating scripts used to check system configuration when wrapper defines a system dependency and put them in the adequate place of the install tree. These scripts will be used by packages and other wrappers that want to use the external package as a system dependency.

  • Arguments: none

  • Example: generating platform configuration evaluation scripts for boost
pid cd boost
pid gen_system_check

Removing platform configuration evaluation

  • Call: pid rem_system_check

  • Effect: Removing scripts used to check system configuration when wrapper define a system dependency and uninstalling them from install tree. This is the reverse operation of gen_system_check, usefull when you want to clean the install tree while implementing the wrapper.

  • Arguments: none

  • Example:
pid cd boost
pid rem_system_check

Evaluating platform configuration

  • Call: pid eval_system_check

  • Effect: Evaluating target platform system configuration. Automatically calls the gen_system_check commands if required. This command is usefull to see the result of the evaluation of a platform configuration while developping the corresponding wrapper.

  • Optional argument:

    • arguments: the arguments passed to the evalutaion of the platform configuration. This is a string containing constraint expressions of the form name=value.
    • force: force the regeneration of the set system check scripts, equivalent to calling gen_system_check.

  • Example:

  • Evaluating if a version of boost can be used as a system dependency
pid cd boost
pid eval_system_check

The output should look something like (simplified output for readability):

[PID] INFO : Evaluation of boost system configuration SUCCEEDED
 --- Returned variables ---
- boost_VERSION = 1.58.0
- boost_LIBRARY_DIRS =
- boost_INCLUDE_DIRS = /usr/include
- boost_RPATH = /usr/lib/x86_64-linux-gnu/libboost_atomic.so;/usr/lib/x86_64-linux-gnu/libboost_chrono.so;/usr/lib/x86_64-linux-gnu/libboost_context.so;/usr/lib/x86_64-linux-gnu/libboost_coroutine.so;/usr/lib/x86_64-linux-gnu/libboost_date_time.so;/usr/lib/x86_64-linux-gnu/libboost_exception.a;/usr/lib/x86_64-linux-gnu/libboost_filesystem.so;/usr/lib/x86_64-linux-gnu/libboost_graph.so;...
- boost_LINK_OPTIONS = -lboost_atomic;-lboost_chrono;-lboost_context;-lboost_coroutine;-lboost_date_time;-lboost_exception.a;-lboost_filesystem;-lboost_graph;-lboost_graph_parallel;-lboost_iostreams;-lboost_locale;-lboost_log;-lboost_log_setup;-lboost_math_c99;-lboost_math_c99f;-lboost_math_c99l;-lboost_math_tr1;-lboost_math_tr1f;-lboost_math_tr1l;-lboost_mpi;-lboost_mpi_python-py27;-lboost_mpi_python-py35;-lboost_mpi_python;-lboost_prg_exec_monitor;-lboost_program_options;-lboost_python-py27;-lboost_python-py35;-lboost_python;-lboost_random;-lboost_regex;-lboost_serialization;-lboost_signals;-lboost_system;-lboost_test_exec_monitor.a;-lboost_thread;-lboost_timer;-lboost_unit_test_framework;-lboost_wave;-lboost_wserialization
- boost_COMPONENTS = atomic;chrono;context;coroutine;date_time;exception;filesystem;graph;graph_parallel;iostreams;locale;log;log_setup;math_c99;math_c99f;math_c99l;math_tr1;math_tr1f;math_tr1l;mpi;mpi_python-py27;mpi_python-py35;mpi_python;prg_exec_monitor;program_options;python-py27;python-py35;python;random;regex;serialization;signals;system;test_exec_monitor;thread;timer;unit_test_framework;wave;wserialization
 --- Final contraints in binary ---
- libraries=atomic,chrono,context,coroutine,date_time,exception,filesystem,graph,graph_parallel,iostreams,locale,log,log_setup,math_c99,math_c99f,math_c99l,math_tr1,math_tr1f,math_tr1l,mpi,mpi_python-py27,mpi_python-py35,mpi_python,prg_exec_monitor,program_options,python-py27,python-py35,python,random,regex,serialization,signals,system,test_exec_monitor,thread,timer,unit_test_framework,wave,wserialization
- soname=libboost_atomic.so.1.58.0,libboost_chrono.so.1.58.0,libboost_context.so.1.58.0,libboost_coroutine.so.1.58.0,libboost_date_time.so.1.58.0,libboost_filesystem.so.1.58.0,...
- version=1.58.0*
  • Evaluating if version 1.63.0 of boost can be used as a system dependency
pid cd boost
pid eval_system_check arguments="version=1.63.0"

On the same platform as the one used in previous example (that provides version 1.58.0) the output looks like:

[PID] INFO : installing configuration boost...
...#ask to enter sudoer password
[PID] WARNING : install of configuration boost has failed !
[PID] ERROR : Evaluation of boost system configuration FAILED !
--- Input constraints ---
- version=1.63.0

Listing package versions

  • Call: pid list_versions

  • Effect: write to the standard output the list of known version for this external package.

  • Example:

  • listing all versions of the external package boost
pid cd boost
pid list_versions

Output looks like:

[100%] [PID] boost versions:
- 1.55.0
- 1.58.0
- 1.63.0
- 1.64.0
- 1.65.0
- 1.65.1
- 1.67.0
- 1.69.0
- 1.71.0
- 1.72.0
- 1.75.0