A PID package provides a set of useful commands to manage its lifecycle. All these commands must be called from the build folder of the package.

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

> cd <workspace dir>/packages/<package name>/build
> cmake .. #building commands

Once this last command has been executed, developers can use native build tool to execute package 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: compiling the package.
  • make test: running internal tests on the package.
  • make doc: generates the API documentation with doxygen.
  • make install: installing the current package version binary into workspace.
  • make package: generating a relocatable binary archive for the package version.
  • make package_install: installing a relocatable binary archive for the package version.
  • make build: The all-in-one build procedure.
  • make build_release: The all-in-one build procedure in release only mode.
  • make build_debug: The all-in-one build procedure in debug only mode.
  • make clean: Cleaning the build tree of the package.
  • make uninstall: Uninstalling the current package version.
  • make referencing: Referencing the package in the workspace.
  • make licensing: Applying a license to the package content.
  • make update: Updating package to its last available version.
  • make integrate: Integrating local modifications of the package content with those proposed by other developers.
  • make site: Generating the static website supporting the documentation of the package.
  • make list_dependencies: Listing dependencies of the package.

Compiling

  • Call: make or make 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

Running tests

  • Call: make 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

Generating documentation

  • Call: make 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

Installing

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

Generating a binary archive

  • Call: make 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

Installing a binary archive

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

All in one build procedure

  • Call: make build
  • Effect: runs all the previous commands sequentially in the adequate order (same order as items of this list) and according to 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 (using cmake command).
  • Arguments:

    • {optional} force (default to false): if set to true, the build can take place even if the current branch is the master branch.

Build procedure in Release only mode

  • Call: make 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 make build command. It is usefull to save build time while compiling.
  • Arguments:

    • {optional} force (default to false): if set to true, the build can take place even if the current branch is the master branch

Build procedure in Debug only mode

  • Call: make 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.
  • Arguments:

    • {optional} force (default to false): if set to true, the build can take place even if the current branch is the master branch

Cleaning the build tree

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

Uninstalling the current package version

  • Call: make 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

Referencing the package in the workspace

  • Call: make 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

Applying license to the package content

  • Call: make 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

Updating the package

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

Integrating modifications

  • Call: make 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.
  • Arguments:

    • {optional} 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.

Generating documentation website

  • Call: make 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.
  • Arguments:

    • {optional} synchro (default to true): if true the commands will automatically push modifications performed in the static site repository.
    • {optional, 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.

Listing package dependencies

  • Call: make 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.
  • Arguments:

    • {optional} 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.
    • {optional} write_file: if set to a file path, the output will be printed tothis file instead of standard output.