Packages build process is configured according to CMake cache variable called options. PID provides specific options to control parts of the development process that are automatized.

Package Configuration

PID provides some generic options used to manage the development process of a package (independently). These options are CMake cached variables that can be set by the user or that take their current value (they have a default value set in the PID API). Options can be easily configured in CMake using the configuration GUI:

> cd build
> ccmake ..

On can also set directly these variables using -D<VARIABLE>=<VALUE> argument when calling cmake or pid command.

Available options

Available top level options are:

  • ADDITIONAL_DEBUG_INFO (default to OFF): If this option is ON the CMake process will be much more verbose than in a default situation.

  • BUILD_AND_RUN_TESTS (default to OFF): If this option is ON the CMake process will build test applications and run unit tests (in Release only, see RUN_TESTS_IN_DEBUG for running them is debig also) that have been defined in the CMakeList.txt of the test folder.

  • BUILD_COVERAGE_REPORT (default to OFF, depends on BUILD_AND_RUN_TESTS state): If this option is ON the CMake process will generate a coverage report of tests. The target coverage is created only if the lcov tool has been found by CMake on the host system.

  • BUILD_STATIC_CODE_CHECKING_REPORT (default to OFF): If this option is ON the CMake process will generate a static check report on all codes of the packages. If, in addition, BUILD_AND_RUN_TESTS is ON it will generate tests based on critical static checks of the code.

  • RUN_TESTS_IN_DEBUG (default to OFF, depends on BUILD_AND_RUN_TESTS state): If this option is ON the CMake process will run tests also in Debug mode.

  • BUILD_RELEASE_ONLY (default to OFF): If this option is ON the CMake process will only build the release version of components. To be used when one wants to decrease build time without waisting hours building debug versions of their code. The build of dependencies (other package) is not modified by this option.

  • BUILD_API_DOC (default to ON): If this option is ON, the CMake process will build the html API documentation of the package.

  • BUILD_LATEX_API_DOC (default to OFF): If this option is ON and if BUILD_API_DOC is also ON, the CMake process will build the pdf document containing the API documentation of the package.

  • BUILD_EXAMPLES (default to ON): If this option is ON, example application will be build and installed in the binary package resulting from the build process. Otherwise then will be used only for API documentation generation purposes (if the BUILD_API_DOC option is ON). When the option is ON, a dependent option appears for each example of the project (default to ON), to let the user select which example to build. This is particularly interesting to save compilation time where there are numerous example in a project.

  • ENABLE_PARALLEL_BUILD (default to ON): If this option is ON, many jobs will be run in parallel when compiling and running tests. The number of jobs is optimized with respect to system capacities (number of cores/processors). It may be usefull to deactivate this option if you need to read ouputs of the build proces in sequential order, typically when resolving some compilation errors.

  • ENABLE_SANITIZERS (default to OFF): If this option is ON, it will enable compiler specific flags that check and detect bugs such as buffer overflows or accesses, dangling pointer or different types of undefined behavior.

  • WARNINGS_AS_ERRORS (default to OFF): If this option is ON, all warnings will be considered as errors and so will stop build process. This option is automatically set when releasing a package to ensure there is no ignored warnings.

  • BUILD_DEPENDENT_PACKAGES (default to ON): If this option is ON, the build process will first try to build direct dependencies of the package before building the package itself, if these dependencies are satisfied by a source package (a repository residing in the workspace). For each dependency, if this option in set to ON, they will also in turn build their own dependencies first, and so on recursively. Be warn that this option may significantly increase the build time, so after a first build you may set it to OFF in order to decrease build time.

  • GENERATE_INSTALLER (default to OFF): If this option is ON the CMake process will generate a ready to install relocatable binary archive of the package version for the current platform.

  • REQUIRED_PACKAGES_AUTOMATIC_DOWNLOAD (default to ON): If this option is ON the CMake process will automatically try to install adequate binary package version when they cannot be found in the local workspace. The “automatic download” procedure will do one of the following action:

    • if the required package repository exists in the workspace, CMake will retrieve the adequate Git tag corresponding to the version to install, “jump” to the corresponding commit and build the binary package for this commit.

    • If the required package repository does not exist, CMake will use package reference files contained in the workspace in order to know where to find the package on the internet. Then depending on the situation:

      • CMake will download a binary package version archive that is 1) available on internet, 2) adequate regarding version constraints. After download, CMake will install the archive.
      • if no adequate binary package version archive is available, then CMake will clone the git repository (if the user has access to it) and then do the same as the first possible action.
      • if the user has no access to the package source repository, then the build/install process will stop on an error.

  • REQUIRED_PACKAGES_AUTOMATIC_UPDATE (default to OFF): If this option is ON the CMake process will automatically check if an updated version of the package exists and will automatically install it. The procedure works quite like the REQUIRED_PACKAGES_AUTOMATIC_DOWNLOAD one.

Controlling the build process

The package build process is controlled with native build tools. For now, only UNIX Makefiles compatible build systems have been tested, so examples are provided considering this native build system. All build related commands used must be called from the build folder of the package. Then Each time a file or directory is added to the package CMake is used to reference it or each time any CMakeList.txt file of the package is modified the system must be reconfigured. This can be achieved “by hand” by doing:

cd <path to package>
pid configure	#native build system is generated again

Once this last command has been executed, developers can use native build tool to build the package. PID defines a set of targets that can be used, but to keep it simple there is a common global command that automatically perform everything in the adequate order according to configuration of the project:

pid build

Build modes

The build process takes place in release and debug mode in the same time: the release sub-folder of the build folder contains build artefacts for the Release mode and the debug sub-folder contains build artefacts for the Debug mode. Developers don’t have to worry about these directories they are automatically created and managed by PID system. The CMake cache variables of the package are the same for both modes. Nevertheless, depending on the configuration mode, dependencies, notably those to external packages, can vary and so some dedicated CMake variables can appear in the CMake cache. The only thing to understand is that variable with _DEBUG appended are relative to Debug mode otherwise they are relative to Release mode.

The CMakeList.txt of the package can do different things according to the mode using the CMAKE_BUILD_TYPE variable to check built mode as in any CMake script. Nevertheless there are some rules to respect in order to make PID work correctly:

  • All components defined in Release mode must also be defined in Debug mode. In other words, both modes define the same components for the package (i.e. with same names).
  • Components and package dependencies can be different between modes, nevertheless the developer should always keep in mind that debug version of a component should reflect as closely as possible the release version.