The jenkins build-job ===================== Running the CPF Jenkins job --------------------------- The jenkins job that is created by this package is a parameterized job. The parameters can be used to execute multiple tasks on a CPF CI-project when the job is started via the Jenkins web-interface. Integrating new commits ^^^^^^^^^^^^^^^^^^^^^^^ In this mode, the job verifies the commits made to an integration branch by building the pipeline in all configurations, merge the commits to a main branch and add a new internal-version tag to mark the commit as a successful build. The project web-page will be updated with the latest version of the generated documentation. This mode is the most common use case, which should be triggered automatically when pushing commits to an integration branch of the build repository or one of the package repositories. To do an integration job following parameters must be set: - branchOrTag: origin/\-int-\ - task: integration - package: If a package was changed, this must be set to the package name. Note that this must be a package that has its versioning handled by this build project. all other can be left at their defaults. Tagging a commit with a release version ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this mode the job will overwrite an existing internal version tag with a release version and rebuild the tagged commit to create build artifacts with the new version. In this case you need to specify which part/digit of the version number should be incremented. The less significant digits are reset to zero. This will also update the projects web-page. To create a release tag, the following parameters must be set: - branchOrTag: existing internal version-tag - task: one of incrementMajor, incrementMinor, incrementPatch all other can be left at their defaults. Rebuild an existing commit ^^^^^^^^^^^^^^^^^^^^^^^^^^ Sometimes it is necessary to rebuild an already integrated commit in order to recreate build artifacts. In this mode, the job will not touch the version tags are changed. This will also update the projects web-page. When none of the jobs default parameters are changed, it executes this task for the master branch. To rebuild an existing commit the following parameters must be set: - branchOrTag: \ all other can be left at their defaults. Testing or debugging the job itself ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When working on the CMakeProjectFramework itself, it is sometimes useful to speed up the build-job by running it with a reduced workload and without modifying the repository. Reducing the workload can be achieved by limiting the build to a special configuration and/or a special target. In this case the following parameters must be set: - branchOrTag: origin/\ (this should be the branch you work on) - task: rebuild - package: The package you work on. - cpfConfiguration: The configuration you are interested in. - target: The target that is build. Let the build-job do the code formatting ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you enabled the \ref clang-format_package target, the build-job will format all the owned packages in your project on each execution. This is triggered if the \c Sources/.clang-format file exits. Documentation publishing ------------------------ After a successful build, the jenkins job accumulates the html output from all configurations that are specified in the \c cpfCIBuildConfigurations.json file. This is done, because not all pipeline steps are available for all configurations. For example the OpenCppCoverage report can only be generated on Windows and would miss if only the html-pages generated by a Linux configuration were published. The Doxygen output can be created by all configurations and only one will be used in the accumulated html output. The build-job will take the output from the last configuration in \c cpfCIBuildConfigurations.json file that generates it. This may be important when you want to use the output of a special configuration. Note that the configuration can influence the actual content of the documentation, an example is the dependency graph in which the node shapes are different for shared and static libraries. After accumulation the content of the html directory is copied to the web-server that belongs build project and can be accessed via that server. In case you want to use a custom jenkins-job for publishing the webpage, the CPF-job creates a build-artifact that contains the complete html directory.