The PID workspace project provides a set of commands which are basically implemented with CMake and can be called :

  • using native build system in use (e.g. make) from the build folder of the workspace.
  • using the shell script pid from the workspace root folder or from any package/wrapper/framework/environment folder by using workspace as first argument.

Before being able to use native build system commands, pid-workspace project must be configured at least once:

  • directly calling
cd <workspace dir>/build
cmake .. #building commands

Once this last command has been executed, developers can use native build tool to execute commands defined by the PID system.

If you use pid script then the configuration of workspace is automatic.

Commands summary

  • man: print information about available workspace commands.
  • info: print information about the workspace content.
  • create: create new deployments units like packages or wrappers.
  • connect: connect a deployment unit to a remote git repository.
  • deploy: deploying a deployment unit like native or external packages, and its dependencies, in the workspace.
  • update: updating deployment units.
  • uninstall: uninstalling a binary package.
  • remove: removing a deployment unit from your local workspace.
  • build: building packages.
  • rebuild: rebuilding packages.
  • hard_clean: cleaning packages build folder.
  • register: registering a package or framework in the remote workspace.
  • release: releasing a new version of a package.
  • ugrade: upgrading the workspace to its last released version.
  • resolve: resolving runtime dependencies of a native package.
  • install: installing a binary package and its dependencies into a system folder.
  • profiles: Managing host environment profiles to configure the global build process (e.g. defining target platforms).
  • contributions: Managing contribution spaces in use in the local workspace.

About the pid script

The pid script is available at workspace root folder and is symlinked in each deployment unit’s source folder so that it can be easily used anywhere you are working.

Available commands for this script are exactly the same as when using the native build system (e.g. make), so for instance:

cd <workspace dir>
pid man

is equivalent to:

cd <workspace dir>/build
make man

Using pid script as many advantages:

  • You do not have to bother about the native build tool to call
  • The configuration of CMake project is automatic, so if the project has not been configured yet it will be performed by the script.
  • You can directly pass CMake options to the pid script (e.g. -DBUILD_EXAMPLES=ON) together with any command, it will perform reconfiguration of CMake project before executing the command.
  • It provides additional commands (see below) that are not implemented in native build tool.

Specific commands

Here are commands that are specific to the pid script:

  • configure: is used to force the (re)configruation of the CMake project (workspace or deployment unit). It is a way to avoid using CMake directly.
cd <workspace dir>

is equivalent to:

cd <workspace dir>/build
  • workspace: is used as a command header that simply executes a workspace command from a deployment unit folder. It is a way to avoid navigating between packages and workspace folders. So for instance:
cd <package dir>
pid workspace man

is equivalent to:

cd <package dir>
cd <workspace dir>
pid man
cd <package dir>
  • cd: is used to switch from one place of the workspace to anoher in a quick way. For instance:
cd <my_package>
pid cd # goto the workspace folder
pid cd my_package # go back to my_package folder

Remark: Since cd affects the current shell it requires an additional configuration step of your workspace: you need to source the script. See next section for explanations.

  • exec: executes a command in the given project. Used to avoid moving from one place to another. For instance
pid cd <my_package>
pid exec pid-rpath build

is equivalent to:

pid cd <my_package>
pid cd pid-rpath
pid build
pid cd <my_package>
  • run: runs the given executable matching the specified platform, package and version. Used to avoid navigating in the install tree to launch executables. For instance:
pid cd <my_package>
pid run x86_64_linux_stdc++11 pid-rpath 2.0.5 pid-rpath_rpath-example

Sourcing the script

You should consider sourcing the script in your terminal.

source <workspace dir>/share/

Sourcing the script has somes benefits:

  • you can use workspace navigation commands (cd).
  • auto completion is available.
  • you do no more need to enter the path to the script to use it. So for instance:

instead of writing:

cd <workspace dir>
./pid man

you can type:

cd <workspace dir>
pid man

In following commands usage examples, we consider that the script has been sourced.

Getting help

  • Call: pid man

  • Effect: print all available workspace commands and their required/optional arguments.

  • Arguments: none

Getting information

  • Call: pid info

  • Effect: print information about the workspace or its content (packages, wrappers, environments, frameworks).

  • Arguments: Only one argument is possible. It is used to decide which information to print:

    • no argument. The command prints general information about the workspace, notably the current version of PID in use (since version 2).
    • framework=<name>|all. The command prints information about the framework with given <name> and list all packages belonging to that framework, ordered by categories they contribute to. If all is specified then list all available frameworks.
    • package=<name>|all: print information about the native or external package with given <name>, including its binary versions available for current platform. If all is specified then list all available packages ordered by categories.
    • environment=<name>|all: print information about the environment with given <name>. If all is specified then print information about all available envrionments.
    • license=<name>|all: print precise information on the license with given <name>. If all is specified then list all licenses that are available in the local workspace (and can so be used in packages description).
    • language=<name>|all: print information on the language with given <name> (which is a CMake language identifier like CXX). If all is specified then print information on all languages available for current workspace configuration.
  • Examples:

  • to get info about a package:

pid info package=pid-rpath

Resulting output in terminal:

DESCRIPTION: Default package of PID, used to manage runtime path in executables
DATES: 2015
CONTACT: Robin Passama ( - LIRMM/CNRS
	Robin Passama - LIRMM/CNRS
	Benjamin Navarro - LIRMM
		x86_32_linux_stdc++: CANNOT BE INSTALLED
		x86_64_linux_stdc++11: CAN BE INSTALLED
		x86_64_linux_stdc++: CANNOT BE INSTALLED
		x86_64_linux_stdc++11: CAN BE INSTALLED
		x86_64_linux_stdc++11: CAN BE INSTALLED
		x86_64_linux_stdc++11: CAN BE INSTALLED
  • to get info about a license:
pid info license=CeCILL-C

Resulting output in terminal:

OFFICIAL NAME: Contrat de license de logiciel libre CeCILL-C
  • to list all available packages:
pid info package=all

Resulting output in terminal should look like:

programming: boost cpp-taskflow dlib
	resources_management: pid-rpath
	operating_system: asio boost cpp-taskflow dlib libusb pid-network-utilities pid-os-utilities
	network: asio nanomsg poco simple-web-server nanomsgxx
	meta: boost dlib
	log: boost dlib
	python: boost pybind11
	math: boost eigen openblas sophus
	serialization: boost dlib flatbuffers json libxml2 protobuf tinyxml2 yaml-cpp
	parser: cli11 fmt json libxml2 tinyxml2 yaml-cpp
	image: dlib opencv
	gui: dlib fltk freetype2 libfltk wxwidgets
	multimedia: ffmpeg
	linear_algebra: lapack
	threading: qtlibs
	io: qtlibs
	timing: qtlibs
	windows: qtlibs
	plot: knowbotics-tools
	configuration: pid-config
	logging: pid-log
		vision: blackmagic-decklink libfreenect2 open-igtlink-io open-igtlink openvr plus-toolkit vimba kinect1-driver
	robot: forcedimension-sdk
		arm: virtuose-api api-driver-ur libfranka panda-robot
		mobile: neobotix-mpo700-udp-interface pioneer3DX-driver
  • Remarks:

    • each category defines a specific subject that helps classifying packages. Categories can be hierarchically refined into sub categories for instance the category camera refines the category sensor. The process of categorization of packages is based on package and framework description. Indeed a package specifies the categories it belongs to in its CMakeLists.txt and this information is written in the package reference file when generated. Frameworks specify in their CMakeLists.txt the categories they used internally to classify packages that belong to this framework.

    • when listing deployment units using the all option: packages are searched only in used contribution spaces. Indeed used contributions spaces in the local workspace define what is available.

Creating a new deployment unit in the local workspace

  • Call: pid create

  • Effect: create a new deployment unit, either a package, a wrapper, an environment or a framework, into the local workspace.

  • Arguments:

    • use one of the following argument to create the correspondinng deployment unit. The name given to the deployment unit to be created must be unavailable in the local workspace. This means that the name must be unavailable in any contribution space in use.

      • package=<name>. Create a native package with given <name>.
      • wrapper=<name>. Create an external package wrapper with given <name>.
      • framework=<name>. Create a framework with given <name>.
      • environment=<name>. Create an environment with given <name>.
    • Optional arguments:

      • license=<name of license>. Define a license for the project created, default is CeCILL license.
      • author=<name of author>. Set the author name, default is current user on local workstation.
      • affiliation=<name of the institution>. Set the author institution name.
      • url=<git address of the official repository>. set the official address of the remote repository to which the created project is connected to. This mostly do the same as connect command. If not specified the deployment unit stays purely local to your worstation. Otherwise the official remote repository is automatically configured just after package creation.
      • {only for frameworks} site=<http address of the web site>. Set the URL of the website generated by the framework.
  • Examples:

  • Create a purely local package (take a look at the result in <workspace>/packages/my-test-package):

pid create package=my-test-package license=CeCILL-C author="Robin Passama" affiliation="LIRMM"
  • Create a local package connected to an official remote repository:
pid create package=my-test-package url=<a git address>
  • Create a local framework connected to an official remote repository:
pid create framework=a-new-framework url=<a git address> site=<url of the framework web site>
  • Remark: The deployment unit will only exist in the local workspace of the user if no official remote repository has been specified. If no url has been specified then the user has to connect the package to an official remote repository later, using connect command.

Synchronizing a local deployment unit with a remote repository

  • Call: pid connect

  • Effect: synchronizes the local repository of a deployment unit with a target remote repository.

  • Remark: this command is typically used after create command (and after some modifications made by the package creator) to provide the package to other users using the register command.

  • Arguments:

    • use one of the following argument to connect the correspondinng deployment unit. The name given to the deployment unit to connect must match an existing deployment unit in the local workspace. This means the deployment unit source repository must lie in the corresponding folder of the workspace (e.g. packages folder for native packages).

      • package=<name>: connect a native package source repository.
      • wrapper=<name>: connect an external package wrapper repository.
      • framework=<name>: connect a framework respository.
      • environment=<name>: connect an environment repository.
    • use one of te following argument to target teh adequate repository remote:

      • official=<url>: Set the url of the official remote repository. It must be used only on empty remote repositories (first time the package is connected).
      • origin=<url>: Set the url of the origin remote repository. Used by non official developpers to change the private repository used (by default origin target the same remote as official).
    • Optional Argument only when using official argument:

      • force=true: force the update of the official repository. This is used when official repository has migrated to another place (when official remote is not empty) et you need to reconnect it with this new remote.
  • Example:

pid connect package=my-test-package

Deploying a deployment unit in the local workspace

  • Call: pid deploy

  • Effect: Deploy an existing deployment unit in the local workspace, so that this later can then be used. This can be either a framework, an environment, a native package or an external package. For a package, either native or external, it can be deployed either from soure repository or from binary relocatable archive.

By default, the source repository will be cloned/built/installed . If version is specified then the target relocatable binary version archive of the package is downloaded/resolved and installed if available, otherwise the build process of source repository takes place.

  • Arguments:

    • use one of the following argument to deploy the correspondinng deployment unit. The name given to the deployment unit to deploy must match an existing deployment unit in contributions spaces used in local workspace.

      • package=<name>: deploy source repository of a native package or external package wrapper wit hgigen <name>. If repository is not accessible then try to install it from a binary archive.
      • environment=<name>: deploy the environment with given <name> from its repository.
      • framework=<name>: deploy the framework with given <name> from its repository.
    • Optional arguments when using package argument:

      • version=<version number>. Deploy a specific version of the package. If not specified the last available version of the package is deployed.
      • no_source=true: force the download of an existing binary package version archive. Default value is false.
      • force=true: force deployment even if the adequate version already lies in the workspace. Default value is false.
      • verbose=true: get more debug information during the deployment process. Default value is false.
    • Optional arguments available only when deploying a native package:

      • branch=<name>: deploy a package repository from a specific branch. Cannot be combined with no_source=true.
      • test=true: run tests to complete the deployment. Default value is false.
  • Examples:

  • To deploy the repository of a package (if you have access to this repository):

pid deploy package=pid-rpath
  • To deploy relocatable binary archive of the package (if you have access to the archive site):
pid deploy package=pid-rpath version=2.0.0 no_source=true
  • To deploy a framework’s repository (if you have access to this repository):
pid deploy framework=pid

Uninstalling binary package versions

  • Call: pid uninstall

  • Effect: uninstall package versions from workspace. Works for native or external packages.. It is more precise and general than the uninstall command of individual packages as it can target any version, not only the currenlty built one.

  • Arguments:

    • package=<name>: native or external package to uninstall.
    • version=<version number>|all: target version to uninstall. The target version is eithe specific (using MAJOR.MINOR.PATCH expression for <version number>) or all versions are uninstalled when using the keywork all.
  • Example:

    • Uninstalling version 2.0.0 of package pid-rpath:
pid uninstall package=pid-rpath version=2.0.0

After this command there is no more folder at <workspace>/install/<platform>/pid-rpath/2.0.0.

  • Uninstalling all versions of package pid-rpath:
pid uninstall package=pid-rpath version=all

After this command there is no more version folder in <workspace>/install/<platform>/pid-rpath.

Updating a deployment unit

  • Call: pid update

  • Effect: update the target deployment unit. If the deployment unit repository is available in workspace, it is updated then project is build. For external and native packages, if the corresponding repository is not used it will try instead to update the installed binary versions (e.g. patch of installed versions).

  • Arguments: use one of the following arguments

    • package=<name>: target native or external package to update. If the keyword all is used then all installed packages will be updated.
    • framework=<name>: target framework to update.
    • environment=<name>: target environment to update.
  • Example:

  • Updating the pid-rpath package:

pid update package=pid-rpath
  • Updating all packages installed in the local workspace:
pid update package=all

Removing a deployment unit from local workspace

  • Call: pid remove

  • Effect: Remove a deployment unit from the local workspace. Can be useful if for instance you do no more work on a given package for a long time, after a release for instance. For native and external packages, it will also clear the installed binary package’s versions by doing something equivalent to pid uninstall package=<name> version=all.

  • Arguments:

    • use one of the following argument to deploy the correspondinng deployment unit.

      • package=<name>: remove the native or external package with given name from local workspace. Will also remove all installed versions of the package.
      • framework=<name>: remove the framework with given name from local workspace.
      • environment=<name>: remove the environment with given name from local workspace.
  • Examples:

    • Removing a package:
pid remove package=pid-rpath

After this call there is no source or binary code for the package named pid-rpath, look into <workspace>/packages and into <workspace>/install/<platform>.

+ Removing a framework:
pid remove framework=pid

After this call there is no source framework named pid, look into <workspace>/sites/frameworks.

Building a package

  • Call: pid build

  • Effect: builds the target source native package.

  • Arguments:

    • {optional} package=<name>: target package to build. If the keyword all is used, or if no argument is passed to the command, then all source packages will be built.
  • Example:

  • Building the pid-rpath package:

pid build package=pid-rpath
  • Building all source packages in the local workspace:
pid build package=all

Force rebuilding of a package

  • Call: pid rebuild

  • Effect: this commands clean and rebuilds the target native package.

  • Arguments:

    • {optional} package=<name>: target package to rebuild. If the keyword all is used, or if no argument is passed to the command, then all source packages will be rebuilt.
  • Example:

  • Rebuilding the pid-rpath package:

pid rebuild package=pid-rpath
  • Rebuilding all source packages in the local workspace:
pid rebuild package=all

Cleaning build folders of packages

  • Call: pid hard_clean

  • Effect: Deep cleaning the build folder of a native package or an external package wrapper. For instance may be usefull after compiler changes or if you face some strange CMake problems.

  • Arguments:

    • package=<name>: clean the target package or wrapper with given <name>. If all is used then all source packages in workspace are cleaned.
    • {optional} configure=true: reconfigure the package or wrapper after cleaning. Default value is false.
  • Example:

pid hard_clean package=pid-rpath

Registering a deployment unit into a remote workspace

  • Call: pid register

  • Effect: register a deployment unit into contribution space(s) used in the local workspace. This results in updating the contribution space(s) that contains or will contain the contribution files generated by the deployment unit. After this operation the deployment unit can now be deployed into the local workspace of people using corresponding contribution spaces and owning the adequate rights (no restriction if deployment unit is public).

  • Arguments: use either the package or framework argument.

    • use one of the following argument to register the corresponding deployment unit. The <name> must match a corresponding deployment unit in the local workspace.

      • package=<name>: Register native or external package with given <name> in the adequate contribution spaces.
      • framework=<name>. Register a framework with given <name> in the adequate contribution spaces.
      • environment=<name>. Register an environment with given <name> in the adequate contribution spaces.
  • Example:

  • Registering a package:

pid register package=my-new-package
  • Registering a framework:
pid register framework=my-framework

Releasing a native package version

  • Call: pid release

  • Effect: release a new version of a native package. A general definition of a release is to memorize a version (i.e. a commit) of the package in order to be able to retrieve this version later. From a technical perspective: the source package 1) integration branch is merged into package master branch, then 2) master branch is tagged, 3) master branch is pushed to the official remote repository, 4) package description on integration branch is updated with a new version number, then 5) local integration branch is synchronized with origin remote integration branch. After all of this the writing of a new version is ready. This new version number will be an increment of current version either on MAJOR or MINOR or PATCH number depending on the nextversion argument value.

  • Arguments:

    • Mandatory argument:

      • package=<name>: the native package to release.
    • Optional arguments:

      • nextversion=MAJOR or MINOR or PATCH: tells which digit of the released version will be incremented. When not specified the default value is MINOR.
      • recursive=true: makes the release process recursive so that if version of dependencies have not been released yet, they are released before starting target package release. Otherwise the release fails in any version of a dependency has not been released.
      • branch=<branch name>: perform the release from another branch than default integration branch. This allows to release patches for previous version than current one in git history.
  • Example:

pid release name=pid-rpath nextversion=PATCH

Upgrading the local workspace

  • Call: pid upgrade

  • Effect: upgrade the workspace, which installs the more recent version of the PID API and update all contribution spaces in use.

  • Optional arguments:

    • update=true: all packages of the workspace will be updated, as with a pid update package=all command.
    • official=false: use a non official repository, the one pointed by origin, to update the workspace. Default value is true.
  • Example:

  • Simply upgrading workspace API and references

pid upgrade
  • Upgrading workspace API and references then updating all packages to their last version:
pid upgrade update=true

Resolving runtime dependencies of an installed native package

  • Call: pid resolve

  • Effect: resolve runtime dependencies of an already installed binary native package installed in local workspace. Used to fix missing runtime dependencies without rebuilding, for instance after you moved the workspace. For instance it causes the binary package to use newer version of its required packages’ libraries. This is useful when, for some reasons, runtime dependencies have been broken and need to be resolved or just to update the binary with new more recent dependencies (released patch versions). As most of time runtime dependencies of libraries will be updated at build time when other components use them this command should be used only to resolve some library problem when running installed applications or modules.

  • Mandatory arguments:

    • package=<name>: package for which you want to resolve runtime dependencies.
    • version=<version>: version of package for which runtime dependencies must be resolved.
  • Example:

pid resolve package=pid-rpath version=2.0.0

This command will go into <workspace>/install/<platform>/pid-rpath/2.0.0 and reconfigure symlinks for all its libraries and applications.

Installing a package in system

  • Call: pid install

  • Effect: install a binary package and all its dependencies into a folder of the target platform operating system.

  • Arguments:

    • Mandatory arguments:

      • package=<name>: the binary package to install.
      • version=<version number>: version of package to install.
    • Optional arguments:

      • folder=<path>: the system install path to install workspace content in. If not set the workspace’s CMAKE_INSTALL_PREFIX variable is used instead.
      • mode=Debug or Release. The build mode of the binary package to install. If not set the workspàce’s CMAKE_BUILD_TYPE variable is used instead.
  • Example:

  • Install pid-log in default system install folder:

pid install package=pid-log version=3.0.0

Configuring the workspace with profiles

  • Call: pid profiles

  • Effect: Manage the profiles in use in the workspace. Used to configure build environment in use for the whole workspace. It may lead to a reconfiguration of the target platform.

  • Arguments:

    • Mandatory argument:

      • cmd=<name of the command>: apply the given command to profiles. Possible values:
        • ls: list currenlty defined profiles.
        • reset: reset currently used profile to default one.
        • mk: create a new profile and make it current profile.
        • del: remove an available profile. It it was current one, then current becomes default profile.
        • load: make the target profile the current one.
        • add: add an additionnal environment to a target available profile.
        • rm: remove an additionnal environment from a target available profile.
    • Mandatory argument for mk, del, load and optional for add, rm:

      • profile=<name>: name of the target profile. If not specified for add and rm commands, the target profile is default.
    • Mandatory argument for mk, add and rm:

      • env=<name>: name of the target environment.
    • Optional arguments:

      • sysroot=<path>: set the sysroot path when environment is used to cross compile.
      • staging=<path>: set the staging path when environment is used to cross compile.
      • instance=<string>: set the instance name for target platform.
      • platform=<platform string>: set a constraint on the target platform - equivalent to specifying proc_type, proc_arch, os and abi.
      • proc_type=<proc type string>: set a constraint on the target processor type - e.g. x86, arm.
      • proc_arch=<proc arch string>: set a constraint on the target processor architecture - e.g. 32, 64.
      • os=<os string>: set a constraint on the target operating system - e.g. linux, macosx.
      • abi=<ABI name>: set a constraint on the target C++ ABI used - stdc++ or stdc++11 for instance.
      • distribution=<string>: set a constraint on the target distribution - e.g. ubuntu.
      • distrib_version=<version string>: set a constraint on the target distribution version - e.g. 18.04.
  • Example:

  • Create a new profile that uses Clang toolchain version 9.0 instead of the default compiler toolchain:

pid profiles profile=using_clang cmd=mk env=clang_toolchain[version=9.0]

The newly created profile automatically becomes the current one.

  • Using the default profile, automatically generated from default host settings:
pid profiles cmd=reset
  • Makes a specific profile the current one:
pid profiles cmd=load profile=using_clang
  • List available profiles:
pid profiles cmd=ls

Output looks something like:

[PID] current profile: default
[PID] all available profiles:
 - default: based on host environment
   + additionnal environments: pkg-config f2c
 - my_test: based on host environment
 - use_clang: based on clang_toolchain environment
   + additionnal environments: pkg-config
  • Use pkg-config tool in current profile:
pid profiles cmd=add env=pkg-config

Managing contribution spaces in the local workspace

  • Call: pid contributions

  • Effect: manage contribution spaces in use in the local workspace. There are various possible actions that can be set using the cmd argument.

  • Arguments:

    • Mandatory argument:

      • cmd=<name>: apply the given command to contribution spaces. Possible values:
        • ls: list currenlty used contribution spaces.
        • reset: remove all contribution space in use and go back to workspace original configuration.
        • add: add a new contribution space to use.
        • rm: remove a contribution space in use.
        • churl: change remotes used for the contribution space.
        • prio_min: give to the contribution space the lowest priority.
        • prio_max: give to the contribution space the highest priority.
        • publish: publish the content the contribution space.
        • update: update the content the contribution space.
        • status: see the new content into a contribution space. Usefull in combination to move/copy and publish commands to migrate contributions from one contribution space to another.
        • move: move a contribution from one contribution space to another.
        • copy: copy a contribution from one contribution space to another.
        • delete: delete a contribution from one contribution space.
    • Mandatory argument for add, rm, churl, prio_min, prio_max, status, publish, update, move, copy, delete:

      • space=<name>: name of the target contribution space.
    • Mandatory or optional arguments for add and churl commands:

      • update=<url>: URL of the git remote used to update the contribution space. Mandatory for add command.
      • publish=<url>: URL of the remote used to publish new content into the contribution space. Mandatory for churl command.
    • Mandatory arguments for move and copy commands:

      • from=<name>: name of the contribution space to move or copy content from. Target space is then the one specified using space argument.
    • Mandatory arguments for move, copy and delete commands:

      • content=<name>: name of the content to move, copy or delete. This content must belong to contribution space specified by from argument. The content may refer to any kind of contribution (configuration, reference files, find files, licenses, formats, plugin). All files and folders matching the given name will be moved / copied / deleted.
  • Example:

  • Listing contribution spaces currently used in local workspace:

pid contributions cmd=ls
  • Adding a new contribution space to the local workspace:
pid contributions cmd=add space=pid-tests
  • Copy specific content from one contribution space into another:
pid contributions cmd=copy from=my-contribs space=pid content=my-super-package