A PID packages 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

  • all: compiling the package.
  • test: running internal tests on the package.
  • doc: generates the API documentation with doxygen.
  • coverage: generates the coverage report using gcov-lcov.
  • staticchecks: generates the static check report using cppcheck.
  • installing: installing the current package version binary into workspace.
  • package: generating a relocatable binary archive for the package version.
  • package_install: installing a relocatable binary archive for the package version.
  • build: The all-in-one build procedure.
  • build_release: The all-in-one build procedure in release only mode.
  • build_debug: The all-in-one build procedure in debug only mode.
  • cleaning: Cleaning the build tree of the package.
  • hard_clean: Hard cleaning the build tree of the package.
  • uninstall: Uninstalling the current package version.
  • referencing: Referencing the package in the workspace.
  • licensing: Applying a license to the package content.
  • format: formatting source code of the package.
  • update: Updating package to its last available version.
  • integrate: Integrating local modifications of the package content with those proposed by other developers.
  • site: Generating the static website supporting the documentation of the package.
  • list_dependencies: Listing dependencies of the package.

Compiling

  • Call: pid or pid all
  • Effect: compiles and links the source code. Depending on the ENABLE_PARALLEL_BUILD option it will perform parallel build or not. This command will not build exmaples applications and tests if the options BUILD_EXAMPLES and BUILD_AND_RUN_TESTS are respectively OFF. The compilation takes place in both release and debug modes.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid

Running tests

  • Call: pid test
  • Effect: runs the test units defined in the package. Test units must have been compile first. This command is available only if BUILD_AND_RUN_TESTS option has been set to ON. Depending on the ENABLE_PARALLEL_BUILD option these tests will be performed in parallel or not. Tests are run only in release mode, except if BUILD_TESTS_IN_DEBUG option has been set to ON.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid test

Generating documentation

  • Call: pid doc
  • Effect: generates API documentation. This command is available only if BUILD_API_DOC option has been set to ON. If BUILD_LATEX_API_DOC option has been set to ON, the pdf document of the API is generated when running the command. API documentation is only generated for release mode.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid doc

Generating coverage report

  • Call: pid coverage
  • Effect: generates the coverage report using gcov-lcov. This command is available only if BUILD_AND_RUN_TESTS, BUILD_TESTS_IN_DEBUG and BUILD_COVERAGE_REPORT options have been set to ON.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid coverage -DBUILD_AND_RUN_TESTS=ON -DBUILD_TESTS_IN_DEBUG=ON -DBUILD_COVERAGE_REPORT=ON
# then for next times simply do
pid coverage

The coverage report is installed in share/coverage_report of the package install folder.

Generating static check report

  • Call: pid staticchecks
  • Effect: generates the static check report using cppcheck. This command is available only if BUILD_STATIC_CODE_CHECKING_REPORT option has been set to ON.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid staticchecks -BUILD_STATIC_CODE_CHECKING_REPORT=ON
# then for next times simply do
pid staticchecks

The report is installed in share/static_checks of the package install folder.

Installing

  • Call: pid installing
  • Effect: generates API documentation. This command installs the package binary version resulting from the build into the adequate folder of the workspace. Depends on all, and test.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid install

Generating a binary archive

  • Call: pid package
  • Effect: generates a relocatable binary archive for current package version (using the CPack tool of CMake). As we wanted vendor and distribution independent UNIX binary archives, we use the classical .tar.gz archive format. This command is available only if the GENERATE_INSTALLER option has been set to ON. It also installs the binary package version relocatable archive in the adequate installers folder of the workspace.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid package

Installing a binary archive

  • Call: pid package_install
  • Effect: install a relocatable binary archive for current package version. This command installs the binary package version previously generated by the package command relocatable archive in the adequate installers folder of the workspace.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid package_install

All in one build procedure

  • Call: pid build
  • Effect: runs all the previous commands sequentially in the adequate order (same order as items of this list) and according to CMake options selected by the user. Usually this is the only called command when building the package. This command will also check for modifications of the source tree and in that case will relaunch the package configuration.
  • Optional arguments:

    • force (default to false): if set to true, the build can take place even if the current branch is the master branch.
  • Example:
pid cd pid-rpath
pid build
#building the last version released
git checkout master
pid build force=true

Build procedure in Release only mode

  • Call: pid build_release
  • Effect: all in one command in release mode only. This is a variant of build: it applies the same rules and commands, but will only build the release version instead of both release and debug. The same as selecting option BUILD_RELEASE_ONLY as tying a build command. It is usefull to save build time while compiling.
  • Optional arguments:

    • force (default to false): if set to true, the build can take place even if the current branch is the master branch
  • Example:
pid cd pid-rpath
pid build_release

Build procedure in Debug only mode

  • Call: pid build_debug
  • Effect: all in one command in debug mode only. Yet another variant of build: it applies the same rules and commands, but will only build the debug version instead of both release and debug. It is usefull to save build time while compiling.
  • Optional arguments:

    • force (default to false): if set to true, the build can take place even if the current branch is the master branch
  • Example:
pid cd pid-rpath
pid build_debug

Cleaning the build tree

  • Call: pid cleaning
  • Effect: runs a global clean for the package in order to force the system to rebuild at next build. Only the build tree will be cleaned NOT the install tree.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid cleaning

Deleting the build tree

  • Call: pid hard_clean
  • Effect: Hard cleaning the build tree of the package in a agressive and definitive way. This force the package to be reconfigured at next command.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid hard_clean

Uninstalling the current package version

  • Call: pid uninstall
  • Effect: uninstall the package‚Äôs currently built version from the install tree. The build tree will not be cleaned by this command.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid uninstall

Referencing the package in the workspace

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

  • Example:
pid cd pid-rpath
pid referencing

Applying license to the package content

  • Call: pid licensing
  • Effect: adds/updates the license comment into each source file of the package (except test source files). This is an important command to ensure that the whole content of the package is consistent regarding the license defined at global level.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid licensing

Formatting source code

  • Call: pid format
  • Effect: Formatting the c/c++ files in the package using clang-format. A format must have been defined for the package in its description and clang-format executable must be found on the host system.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid format

Just have a look at the code, it has been formatted according to the rules defined in the format defined by the package.

Updating the package

  • Call: pid update
  • Effect: updates the package content and install last release version of the package, if any.
  • Arguments: none

  • Example:
pid cd pid-rpath
pid update

Integrating modifications

  • Call: pid integrate
  • Effect: integrate the current in development version of the package with its online couterpart. This result in a merge of integration branches of both local and origin repositories and the update of origin, if needed.
  • Optional arguments:

    • official (default to false): if set to true the official repository of the package will be used instead of origin. This is used to force sharing current development state with all developers of the package, not only a subgroup of them.
  • Example: integrate in development work with content of the official repository
pid cd pid-rpath
pid integrate official=true

Generating documentation website

  • Call: pid site
  • Effect: generates and updates the website project that support the online documentation of the package. This can be either a lone website or a framework depending on how the website has been defined in the package.
  • 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: update the web site locally but do not publish it online
pid cd pid-rpath
pid site synchro=false

Listing package dependencies

  • Call: pid list_dependencies
  • Effect: write to the standard output the list of package on which the current depends on. This is a command useful to debug package relationships.
  • Optional arguments:

    • flat (default to false): if true the commands will print the a flat list of dependencies, whether they are direct or undirect dependencies of the package.
    • {advanced} write_file: if set to a file path, the output will be printed to this file instead of standard output.
  • Example:

  • listing all dependencies of the package in tree-like view
pid cd pid-log
pid list_dependencies

Output looks like:

[100%] [PID] listing dependencies of the package pid-log ...
Dependencies of pid-log, version 3.1.1
target platform: x86_64_linux_stdc++11 (type=x86, arch=64, os=linux, abi=stdc++11)
* posix
* threads
* python
--------------Release Mode--------------
+ pid-rpath:  2.2.0
	- boost: 1.71.0
- boost: 1.71.0
- yaml-cpp: 0.6.3

boost package appears 2 times: first as a dependency of pid-rpath and second as a direct dependency to pid-log.

  • Getting a flat list of all dependencies of the package:
pid cd pid-log
pid list_dependencies flat=true

Output looks like:

[100%] [PID] listing dependencies of the package pid-log ...
Dependencies of pid-log, version 3.1.1
target platform: x86_64_linux_stdc++11 (type=x86, arch=64, os=linux, abi=stdc++11)
* posix
* threads
* python
--------------Release Mode--------------
+ pid-rpath:  2.2.0
- boost:  1.71.0
- yaml-cpp:  0.6.3

Now all dependencies are printed only once and all as if they were direct dependencies of the package.