docs/jjb/lf-c-cpp-jobs.rst

   1 ##########
   2 C/C++ Jobs
   3 ##########
   4
   5 Job Templates
   6 =============
   7
   8 CMake Sonar
   9 -----------
  10
  11 The Sonar job installs the SonarQube CXX build wrapper and scanner tools,
  12 runs cmake, uses the build wrapper to invoke make, runs the scanner to
  13 analyze code files, then publishes the results to a SonarQube server like
  14 SonarCloud. Optionally runs a shell script before the build to install
  15 prerequisites. Does not support code coverage reporting.
  16
  17 **Deprecated**; new projects should use a CMake SonarQube template.
  18
  19 This job purposely runs on the master branch because the basic SonarCloud
  20 configuration does not support multi-branch.
  21
  22 :Template Names:
  23
  24     - {project-name}-cmake-sonar
  25     - gerrit-cmake-sonar
  26     - github-cmake-sonar
  27
  28 :Comment Trigger: run-sonar
  29
  30 :Required parameters:
  31
  32     :build-node: The node to run build on.
  33     :jenkins-ssh-credential: Credential to use for SSH. (Configure in
  34         defaults.yaml)
  35     :sonarcloud-api-token: SonarCloud API Token.
  36     :sonarcloud-organization: SonarCloud project organization.
  37     :sonarcloud-project-key: SonarCloud project key.
  38
  39 :Optional parameters:
  40
  41     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  42     :build-timeout: Timeout in minutes before aborting build. (default: 15)
  43     :cmake-opts: Parameters to pass to cmake. (default: '')
  44     :cron: Cron schedule when to trigger the job. This parameter also
  45         supports multiline input via YAML pipe | character in cases where
  46         one may want to provide more than 1 cron timer.  (default: '@daily')
  47     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  48     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
  49         (default: $BUILD_DIR/output)
  50     :make-opts: Parameters to pass to make. (default: '')
  51     :pre-build: Shell script to run before performing build. Useful for
  52         setting up dependencies. (default: '')
  53     :sonar-scanner-version: Version of sonar-scanner to install.
  54         (see YAML for default value; e.g., 3.3.0.1492)
  55     :submodule-recursive: Whether to checkout submodules recursively.
  56         (default: true)
  57     :submodule-timeout: Timeout (in minutes) for checkout operation.
  58         (default: 10)
  59     :submodule-disable: Disable submodule checkout operation.
  60         (default: false)
  61
  62     :gerrit_sonar_triggers: Override Gerrit Triggers.
  63
  64 CMake SonarQube
  65 ---------------
  66
  67 The SonarQube job installs the SonarQube CXX build wrapper, runs cmake, uses
  68 the build wrapper to invoke make, then runs the SonarQube Scanner Jenkins
  69 plug-in to analyze code for bugs, code smells and security vulnerabilities,
  70 and to upload the result (possibly including code-coverage statistics) to
  71 a SonarQube server or to SonarCloud.io. Optionally runs a shell script
  72 before the build to install prerequisites.
  73
  74 Requires ``SonarQube Scanner for Jenkins``
  75
  76 This job runs on the master branch because the basic Sonar configuration
  77 does not support multi-branch.
  78
  79 Plug-in configurations
  80     Manage Jenkins --> Configure System --> SonarQube servers
  81         - Name: Sonar (fixed)
  82         - Server URL: https://sonar.project.org/ or https://sonarcloud.io
  83         - Server authentication token: none for local, API token (saved as
  84           a "secret text" credential) for Sonarcloud
  85
  86     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
  87         - Name: SonarQube Scanner (fixed)
  88         - Install automatically
  89         - Select latest version
  90
  91 :Template Names:
  92
  93     - {project-name}-cmake-sonarqube
  94     - gerrit-cmake-sonarqube
  95     - github-cmake-sonarqube
  96
  97 :Comment Trigger: ``run-sonar``
  98
  99 :Required parameters:
 100
 101     :build-node: The node to run the build on.
 102         (Commonly in defaults.yaml)
 103     :jenkins-ssh-credential: Credential to use for SSH.
 104         (Commonly in defaults.yaml)
 105     :project: The git repository name.
 106     :project-name: Prefix used to name jobs.
 107
 108 .. comment Start ignoring WriteGoodLintBear
 109
 110 :Optional Parameters:
 111
 112     :archive-artifacts: Pattern for files to archive to the logs server
 113         (default: '\*\*/\*.log')
 114     :build-wrap-dir: Build wrapper output subdirectory name.
 115         (default: $WORKSPACE/bw-output)
 116     :cmake-opts: Parameters to pass to cmake. (default: '')
 117     :cron: Cron schedule when to trigger the job. This parameter also
 118         supports multiline input via YAML pipe | character in cases where
 119         one may want to provide more than 1 cron timer.  (default: @weekly)
 120     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 121         (default: $BUILD_DIR/output)
 122     :make-opts: Parameters to pass to make. (default: '')
 123     :sonar-additional-args: Command line arguments. (default: '')
 124     :sonar-java-opts: JVM options. For example, use option -Xmx
 125         to increase the memory size limit.  (default: '')
 126     :sonar-prescan-script: A shell script to run before the build and scan.
 127          Useful for setting up dependencies. (default: '')
 128     :sonar-project-file: The file name with Sonar configuration properties
 129         (default: sonar-project.properties)
 130     :sonar-properties: Sonar configuration properties. (default: '')
 131     :sonar-task: Sonar task to run. (default: '')
 132
 133 .. comment Stop ignoring
 134
 135 .. note:: A job definition must provide one of the optional parameters
 136     ``sonar-project-file`` and ``sonar-properties``; they cannot both be
 137     empty.  Set Sonar properties directly in the job definition by setting
 138     the ``sonar-project-file`` property to ``""`` and adding all properties
 139     under ``sonar-properties``.
 140
 141 :Required Sonar Properties:
 142
 143     - sonar.login: The API token for authentication at SonarCloud.
 144       Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
 145     - sonar.organization: The umbrella project name; e.g., "opendaylight".
 146       Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
 147     - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
 148     - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
 149       teams use the catenation of sonar.organization, an underscore, and
 150       sonar.projectName; e.g., "opendaylight_infrautils".
 151
 152 :Optional Sonar Properties:
 153
 154     - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
 155     - Documentation of SonarQube properties is here:
 156       https://docs.sonarqube.org/latest/analysis/overview/
 157
 158
 159 Example job definition
 160 ^^^^^^^^^^^^^^^^^^^^^^
 161
 162 The following example defines a job for a project with CXX source files
 163 in the "src" directory, and unit tests that write coverage files in
 164 GCOV format to the "test" directory. This definition uses configuration
 165 parameters in the umbrella project's defaults.yaml file.
 166
 167 .. code-block:: yaml
 168
 169     - project:
 170         name: my-project-sonar
 171         project: my/project
 172         project-name: my-project
 173         sonar-project-file: ""
 174         sonar-properties: |
 175             sonar.login={sonarcloud_api_token}
 176             sonar.projectKey={sonarcloud_project_organization}_{project-name}
 177             sonar.projectName={project-name}
 178             sonar.organization={sonarcloud_project_organization}
 179             sonar.sourceEncoding=UTF-8
 180             sonar.sources=src
 181             sonar.cfamily.build-wrapper-output=$WORKSPACE/bw-output
 182             sonar.cfamily.gcov.reportsPath=test
 183         jobs:
 184           - gerrit-cmake-sonarqube
 185
 186 CMake Stage
 187 -----------
 188
 189 Stage job which runs cmake && make && make install and then packages the
 190 project into a tar.xz tarball to produce a release candidate.
 191
 192 :Template Names:
 193
 194     - {project-name}-cmake-stage-{stream}
 195     - gerrit-cmake-stage
 196     - github-cmake-stage
 197
 198 :Comment Trigger: stage-release
 199
 200 :Required parameters:
 201
 202     :build-node: The node to run build on.
 203     :jenkins-ssh-credential: Credential to use for SSH.
 204         (Configure in defaults.yaml)
 205     :nexus-group-id: The Maven style Group ID for the namespace of the project
 206         in Nexus.
 207     :staging-profile-id: The unique Nexus Staging Profile ID for the project.
 208         Contact your infra admin if you do not know it.
 209
 210 :Optional parameters:
 211
 212     :branch: Git branch to fetch for the build. (default: master)
 213     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 214     :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
 215     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 216     :cmake-opts: Parameters to pass to cmake. (default: '')
 217     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 218     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 219         (default: $BUILD_DIR/output)
 220     :make-opts: Parameters to pass to make. (default: '')
 221     :pre-build: Shell script to run before performing build. Useful for
 222         setting up dependencies. (default: '')
 223     :stream: Keyword that to represent a release code-name.
 224         Often the same as the branch. (default: master)
 225     :submodule-recursive: Whether to checkout submodules recursively.
 226         (default: true)
 227     :submodule-timeout: Timeout (in minutes) for checkout operation.
 228         (default: 10)
 229     :submodule-disable: Disable submodule checkout operation.
 230         (default: false)
 231     :version: (default: '') Project version to stage release as. There are 2
 232         methods for using this value:
 233
 234         1) Defined explicitly here.
 235         2) Leave this value blank and set /tmp/artifact_version
 236
 237         Use method 2 in conjunction with 'pre-build' configuration to
 238         generate the artifact_version automatically from files in the
 239         project's repository. An example pre-build script appears below.
 240
 241
 242 .. code-block:: bash
 243
 244    #!/bin/bash
 245    MAJOR_VERSION="$(grep 'set(OCIO_VERSION_MAJOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 246    MINOR_VERSION="$(grep 'set(OCIO_VERSION_MINOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 247    PATCH_VERSION="$(grep 'set(OCIO_VERSION_PATCH' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 248    echo "${{MAJOR_VERSION}}.${{MINOR_VERSION}}.${{PATCH_VERSION}}" > /tmp/artifact_version
 249
 250 CMake Verify
 251 ------------
 252
 253 Verify job which runs cmake && make && make install to test a project build..
 254
 255 :Template Names:
 256
 257     - {project-name}-cmake-verify-{stream}
 258     - gerrit-cmake-verify
 259     - github-cmake-verify
 260
 261 :Comment Trigger: recheck|reverify
 262
 263 :Required parameters:
 264
 265     :build-node: The node to run build on.
 266     :jenkins-ssh-credential: Credential to use for SSH.
 267         (Configure in defaults.yaml)
 268
 269 :Optional parameters:
 270
 271     :branch: Git branch to fetch for the build. (default: master)
 272     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 273     :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
 274     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 275     :cmake-opts: Parameters to pass to cmake. (default: '')
 276     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 277     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 278         (default: $BUILD_DIR/output)
 279     :make-opts: Parameters to pass to make. (default: '')
 280     :pre-build: Shell script to run before performing build. Useful for
 281         setting up dependencies. (default: '')
 282     :stream: Keyword that to represent a release code-name.
 283         Often the same as the branch. (default: master)
 284     :submodule-recursive: Whether to checkout submodules recursively.
 285         (default: true)
 286     :submodule-timeout: Timeout (in minutes) for checkout operation.
 287         (default: 10)
 288     :submodule-disable: Disable submodule checkout operation.
 289         (default: false)
 290
 291     :gerrit_verify_triggers: Override Gerrit Triggers.
 292     :gerrit_trigger_file_paths: Override file paths which to filter which file
 293         modifications will trigger a build.