The PID workspaces provide a set of useful commands to manage workspace content at global level. All these commands must be called from the pid folder of the workspace.

Before being able to use this command, they must be “built” from CMake configuration script defined in CMakeLists.txt of the workspace:

cd <workspace dir>/pid
cmake .. #building commands

Once this last command has been executed, developers can use native build tool to execute workspace specific commands that are defined by PID system. We suppose here we use the make tool but any other tool can be used the same way.

The commands are simply called using built tool specific targets, that are listed below.

Commands summary

  • make help: about workspace commands.
  • make info: getting information about workspace content, including packages and frameworks.
  • make create: create new package or framework.
  • make connect: connect a package to a git repository.
  • make deploy: deploying a package and its dependencies in the workspace. Can also be used to deploy frameworks.
  • make remove: removing a package or framework from your workspace.
  • make register: registering a package or framework in the remote workspace.
  • make resolve: resolving runtime dependencies of a package.
  • make clear: uninstalling a binary package’s version.
  • make release: releasing a package’s version.
  • make update: updating packages.
  • make build: building packages.
  • make rebuild: rebuilding packages.
  • make ugrade: upgrading the workspace to its last released version.
  • make system_install: installing the content of the workspace into a system folder.
  • make configure: defining the target platform for which all packages will be built or deployed.

Getting help

  • Call: make help
  • Effect: printing all available workspace specific commands and their required/optional arguments.
  • Arguments: none

Getting information

  • Call: make info
  • Effect: provides general information about the workspace and its content.
  • Arguments: different possibilities

    • no argument. The command prints general information about the workspace, notably the current version of PID in use (since version 2).
    • framework=<name of a framework>. The command prints information about a framework and list all packages belonging to that framework, ordered by categories they contribute to.
    • framework=all. The command lists all available framework referenced in the workspace.
    • package=<name of a package>. The command prints information about a given package, including the possible binary versions of teh package for the current platform.
    • package=all. The command lists all packages ordered by categories defined in the workspace.
    • license=all. The command lists all licenses that are available in the workspace (and can so be used in packages description).
    • license=<name of a license>. The command print precise information on the license.
  • Example:

  • to get info about a package
make info package=pid-rpath

Resulting output in terminal:

NATIVE PACKAGE: pid-rpath
DESCRIPTION: Default package of PID, used to manage runtime path of executables
LICENSE: CeCILL-C
DATES: 2015
REPOSITORY: git@gite.lirmm.fr:pid/pid-rpath.git
DOCUMENTATION: /packages/pid-rpath
CONTACT: Robin Passama (passama@lirmm.fr) - LIRMM
AUTHORS:
	Robin Passama - LIRMM
CATEGORIES:
	programming/resources_management
BINARY VERSIONS:
	1.0.0:
		linux64: CANNOT BE INSTALLED
		linux32: CANNOT BE INSTALLED
		linux64cxx11: CANNOT BE INSTALLED
  • to get info about a license
make info license=CeCILL-C

Resulting output in terminal:

LICENSE: CeCILL-C
VERSION: 1
OFFICIAL NAME: Contrat de license de logiciel libre CeCILL-C
AUTHORS: the CEA CNRS INRIA
  • to list all available packages
make info package=all

Resulting output in terminal:

CATEGORIES:
programming
	plot: knowbotics-tools
	threading: qtlibs boost
	io: qtlibs boost
	timing: qtlibs boost
	windows: qtlibs
	gui: libfltk freetype2
	container: boost
	meta: boost
	video: ffmpeg
	log: pid-log
	parser: libxml2 yaml-cpp
	configuration: pid-config
	resources_management: pid-rpath
knowbotics
	plot: knowbotics-tools
	force-sensor: ati-force-sensor-driver vrep-simulator-knowbotics
	mobile-robot: neobotix-mpo700-vrep-driver neobotix-mpo700-knowbotics
	hand: shadow-hand-driver-vrep shadow-hand-biotac-calibration shadow-hand-knowbotics
	generic: knowbotics vrep-simulator-knowbotics
	arm: arm-controllers-knowbotics kuka-lwr-knowbotics
	vision: leapmotion-knowbotics image-knowbotics
	camera: avt-camera-knowbotics ptz-dlink-knowbotics
	fes: fes-knowbotics prostim-knowbotics
	ptz-unit: ptz-dlink-knowbotics
	laser-scanner: hokuyo-laser-scanner-knowbotics vrep-simulator-knowbotics
	application: cobot_cart_docker neobotix-mpo700-applications
	cobot: cobot_cart_docker
...
  • Remark: 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 sensors. 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.

Creating a new deployment unit

  • Call: make create
  • Effect: create a package or a framework into the workspace.
  • Arguments: use either the package or framework argument (see below) to create corresponding deployment unit. Then use optional arguments.
    • package=<name of the new package>. Create a package with given name if same name is not already used.
    • framework=<name of a framework>. Create a framework with given name if same name is not already used.
    • {optional} license=<name of a given license>. If not specified default license “CeCILL” is used. Otherwise the license passed as argument will apply to the package if it exists.
    • {optional} author=<name of the author>. If not specified (not recommended) author will be the name of the current user on the machine.
    • {optional} affiliation=<name of the institution to which the author belongs to>.
    • {optional} url=<git address of the official repository>. If not specified the package or framework stays purely local to your worstation. Otherwise the official remote repository is automatically configured just after package creation.
    • {optional} site=<http address of the web site>. This option is used to set the address where the web site of the framework can be found. Only usable for frameworks.
  • Example:

  • Create a purely local package:
make create package=my-test-package license=CeCILL-C author="Robin Passama" affiliation="LIRMM"

You can take a look at the result in : <workspace>/packages/my-test-package

  • Create a local package connected to an official remote repository:
make create package=my-test-package url=<a git address>
  • Create a local framework connected to an official remote repository:
make 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 make connect command.

Synchronizing a local deployment unit with an empty remote repository

  • Call: make connect
  • Effect: synchronizes a package or framework with the target remote repository so that this repository becomes the official of the package. This is typically used after a make create command and after some modifications made by the package creator to provide the package to other users (that can then classically clone the repository).
  • Arguments: use either package or framework argument. If package is used it must be combined with either official or origin argument.
    • package=<name of the package>. This is the package to connect to a remote repository.
    • framework=<name of the framework>. This is the framework to connect to a remote repository.

    • official=<url of the remote repository>. This is the url of the official remote repository. It must be used only on empty remote repositories (first time the package is connected).
    • force=true. Use this argument to force the update of the official repository of a package. This is used when package official repository has migrated to another place.
    • origin=<url of the remote repository>. This is the url of the origin remote repository. It can be used to change the private repository used by the developper (by default origin target the same remote as official).
  • Example:
make connect package=my-test-package official=git@gite.lirmm.fr:own/my-test-package

Deploying a deployment unit in the local workspace

  • Call: make deploy
  • Effect: this command is used to deploy an existing package in the local workspace. 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.
  • Arguments: use either the package, external or framework argument
    • package=<name of the package>. The name of the package to deploy. This name must be referenced in the workspace through a reference file.
    • external=<name of the external package>. The name of the external package to deploy. This name must be referenced in the workspace through a reference file.
    • framework=<name of the framework>. The name of the framework to deploy that must be referenced in the workspace through a reference file.
    • {optional, only for packages} version=<version of the binary package>. This is used when one wants to get a installable binary version of the package instead of cloning the official package repository. This argument is mandatory for external packages.
  • Example:

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

make deploy package=pid-rpath

To deploy relocatable binary archive of the package (if you have access to the archive site):

make deploy package=pid-rpath version=2.0.0

To deploy a framework’s repository (if you have access to this repository):

make deploy framework=pid

Removing a deployment unit from local workspace

  • Call: make remove
  • Effect: this command removes the source package or framework 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. It will also clear the installed binary package by doing something equivalent to make clear package=<name of the package> version=all.
  • Arguments: use either the package or framework argument.
    • package=<name of the package>. The target package to remove from local workspace.
    • framework=<name of the framework>. The target framework to remove from local workspace.
  • Example:

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

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

  • Removing a framework:
make remove framework=pid

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

Registering a deployment unit into a remote workspace

  • Call: make register

  • Effect: this command register the target deployment unit (package or framework) that lies in the local workspace into a remote workspace, (most of time a private workspace, denoted by origin remote of the workspace). This action simply consist in updating the origin remote workspace with references and find files used to manage the target package so that other persons will be able to find, clone or download it (depending on their access rights and requirements) after the update of their own local workspace.

  • Arguments: use either the package or framework argument.
    • package=<name of the package>. The target package to register in the remote workspace.
    • framework=<name of the framework>. The target framework to register in the remote workspace.
  • Example:

  • Registering a package
make register package=my-new-package
  • Registering a framework
make register framework=my-framework

Resolving runtime dependencies of an installed binary package

  • Call: make resolve

  • Effect: this command is used to resolve runtime dependencies of a binary package installed in local workspace. For instance it will cause 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. 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.

  • Arguments:
    • package=<name of the binary package>. The name of the package for which resolving references.
    • version=<version of the binary package>. The target version for which references must be resolved.
  • Example:
make resolve package=knowbotics version=1.2.0

This command will go into <workspace>/install/<platform>/knowbotics/1.2.0 and reconfigure links for the libraries and applications.

Clearing an installed binary package

  • Call: make clear
  • Effect: this command is used to uninstall versions of binary packages. It is more precise and general than the make uninstall command of individual packages as it can target any version, not only the currenlty built one.
  • Arguments:
    • package=<name of the binary package>. The target binary package to uninstall.
    • version=<version of the binary package>. The target version to uninstall. The target version is eithe specific (using MAJOR.MINOR.PATCH expression for name) or all version are tergetted using the keywork all.
  • Example:

  • Clearing installed version 1.2.0 of package knowbotics:
make clear package=knowbotics version=1.2.0

After this command there is no more folder at <workspace>/install/<platform>/knowbotics/1.2.0.

  • Clearing all binary versions of package knowbotics:
make clear package=knowbotics version=all

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

Releasing a package version

  • Call: make release

  • Effect: this commands releases a package. That means that the coding lying in the source package integration branch is released as a new version of the package. It is 1) merged into package master branch, then 2) tagged, 3) synchronized with remote package repository, 4) go back to integration and version number of package is modified according to nextversion, then 5) local integration branch is synchronized with 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:
    • package=<name of the package>. The target package to release.
    • {optional} nextversion=MAJOR or MINOR or PATCH. Tells what will be the next version of the package. WHen not specified the default value is MINOR.
  • Example:
make release name=knowbotics nextversion=PATCH

Updating a package

  • Call: make update

  • Effect: this commands update the target source or binary package’s code or all packages lying in the workspace if the keyword all is used. Concretely the update consists in installing latest published binaries of a binary package and updating the repository of a source package then building it.

  • Arguments:
    • package=<name of the package>. The target package to update. If the keyword all is used then all installed packages will be updated.
  • Example:

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

Building a package

  • Call: make build

  • Effect: this commands builds the target source package.

  • Arguments:
    • {optional} package=<name of the package>. The 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:
make build package=pid-rpath
  • Building all source packages in the local workspace:
make build package=all

Force rebuilding of a package

  • Call: make rebuild

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

  • Arguments:
    • {optional} package=<name of the package>. The 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:
make rebuild package=pid-rpath
  • Rebuilding all source packages in the local workspace:
make rebuild package=all

Upgrading the workspace

  • Call: make upgrade

  • Effect: this commands upgrades the workspace which consist in installing the more recent versions of the PID API and most up to date references to packages.

  • Arguments:
    • {optionnal}update=ON or OFF. If ON (default) then all packages of the workspace will be updated, as with a make update package=all command.
    • {optionnal}remote=<name of the remote>. The target remote workspace to use for the update, by default it is the origin remote (the private workspace your are working with- except your are an administrator of the remote workspace).
  • Example:

  • Simply upgrading workspace API and references
make upgrade
  • Upgrading workspace API and references then updating all packages to their last version:
make upgrade update=ON

Installing the workspace in system

  • Call: make system_install

  • Effect: this commands install a binary package and all its dependencies into a system folder.

  • Arguments:
    • package=<name>. The name of the binary package to install.
    • version=<version number>. The package version to install.
    • {optionnal}folder=<path>. the system install path to install workspace content in. If not set the workspace CMAKE_INSTALL_PREFIX is used instead.
    • {optionnal}mode=Debug or Release. The build mode of the binary package to install. If not set the workspàce CMAKE_BUILD_TYPE is used instead.
  • Example:

  • Install pid-log in default system install folder:
make system_install package=pid-log version=3.0.0

Configuring the workspace

  • Call: make configure

  • Effect: this commands is used to set the current development environment used within the workspace. It may lead to a reconfiguration of the current target platform.

  • Arguments:
    • environment=<name of the environment>. You have to set the name of the environment to use. Environment may redefine the current compiler and its default options, and can also configure crosscompilation. Using value host reset build tools setteings to the default system configuration.
    • {optionnal} proc_type: specify a constraint on target processor type when evaluating environment (e.g. x86, arm).
      • {optionnal} proc_arch: specify a constraint on target processor architecture (e.g. 32, 64).
      • {optionnal} os: specify a constraint on target operating system (e.g. linux, macosx).
      • {optionnal} abi: specify a constraint on target C++ ABI (e.g. 98, 11).
      • {optionnal} distribution: specify a constraint on target distribution (e.g. ubuntu, debian).
      • {optionnal} distrib_version: specify a constraint on target distribution version.
      • {optionnal} sysroot: specify a sysroot for crosscompilation.
      • {optionnal} staging: specify a staging folder for crosscompilation.
      • other arguments are environment specific and defined by their respective constraints. A very common specific argument is version to specify version of a toolchain.
  • Example:

  • Using Clang toolchain instead of the default compiler toolchain:
make configure environment=clang_toolchain
  • Using python 3 instead of the default python 2 installed on your machine:
version=3.5 make configure environment=python_interpreter