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     :pre-build: Shell script to run before performing build. Useful for
 124         setting up dependencies. (default: '')
 125     :sonar-additional-args: Command line arguments. (default: '')
 126     :sonar-java-opts: JVM options. For example, use option -Xmx
 127         to increase the memory size limit.  (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     :mvn-settings: The name of settings file containing credentials for the project.
 206     :nexus-group-id: The Maven style Group ID for the namespace of the project
 207         in Nexus.
 208     :staging-profile-id: The unique Nexus Staging Profile ID for the project.
 209         Contact your infra admin if you do not know it.
 210
 211 :Optional parameters:
 212
 213     :branch: Git branch to fetch for the build. (default: master)
 214     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 215     :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
 216     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 217     :cmake-opts: Parameters to pass to cmake. (default: '')
 218     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 219     :install: Install build products to /usr/local. (default: true)
 220     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 221         (default: $BUILD_DIR/output)
 222     :make-opts: Parameters to pass to make. (default: '')
 223     :mvn-global-settings: The name of the Maven global settings to use for
 224         Maven configuration. (default: global-settings)
 225     :pre-build: Shell script to run before performing build. Useful for
 226         setting up dependencies. (default: '')
 227     :stream: Keyword that to represent a release code-name.
 228         Often the same as the branch. (default: master)
 229     :submodule-recursive: Whether to checkout submodules recursively.
 230         (default: true)
 231     :submodule-timeout: Timeout (in minutes) for checkout operation.
 232         (default: 10)
 233     :submodule-disable: Disable submodule checkout operation.
 234         (default: false)
 235     :version: (default: '') Project version to stage release as. There are 2
 236         methods for using this value:
 237
 238         1) Defined explicitly here.
 239         2) Leave this value blank and set /tmp/artifact_version
 240
 241         Use method 2 in conjunction with 'pre-build' configuration to
 242         generate the artifact_version automatically from files in the
 243         project's repository. An example pre-build script appears below.
 244
 245
 246 .. code-block:: bash
 247
 248    #!/bin/bash
 249    MAJOR_VERSION="$(grep 'set(OCIO_VERSION_MAJOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 250    MINOR_VERSION="$(grep 'set(OCIO_VERSION_MINOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 251    PATCH_VERSION="$(grep 'set(OCIO_VERSION_PATCH' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 252    echo "${{MAJOR_VERSION}}.${{MINOR_VERSION}}.${{PATCH_VERSION}}" > /tmp/artifact_version
 253
 254 CMake PackageCloud Stage
 255 ------------------------
 256
 257 Stage job which runs cmake && make, then uploads all DEB/RPM files in the
 258 build directory to PackageCloud.io. Triggered by comment.
 259
 260 The Jenkins system must have a configuration file provider that installs
 261 files ".packagecloud" and "packagecloud_api" to the Jenkins home directory
 262 with appropriate credentials.
 263
 264 The Jenkins build minion must have the Ruby gem "package_cloud" installed.
 265
 266 :Template Names:
 267
 268     - {project-name}-cmake-packagecloud-stage-{stream}
 269     - gerrit-cmake-packagecloud-stage
 270     - github-cmake-packagecloud-stage
 271
 272 :Comment Trigger: stage-release
 273
 274 :Required parameters:
 275
 276     :build-node: The node to run build on.
 277     :debian-distribution-versions: list of DEB package distro/version strings
 278         separated by space; example: "ubuntu/bionic debian/stretch"
 279     :jenkins-ssh-credential: Credential to use for SSH.
 280         (Configure in defaults.yaml)
 281     :packagecloud-account: PackageCloud account ID; example: oran
 282     :packagecloud-repo: PackageCloud repository; example: master, staging
 283     :project: The git repository name.
 284     :project-name: Prefix used to name jobs.
 285     :rpm-distribution-versions: list of RPM package distro/version strings
 286         separated by space; example: "el/4 el/5"
 287
 288 :Optional parameters:
 289
 290     :branch: Git branch to fetch for the build. (default: master)
 291     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 292     :build-dir: Directory to build the project in. (default: $WORKSPACE/build)
 293     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 294     :cmake-opts: Parameters to pass to cmake. (default: '')
 295     :disable-job: Whether to disable the job (default: false)
 296     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 297     :install: Install build products to /usr/local. (default: false)
 298     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 299         (default: $BUILD_DIR/output)
 300     :make-opts: Parameters to pass to make. (default: '')
 301     :pre-build: Shell script to run before performing build. Useful for
 302         setting up dependencies. (default: '')
 303     :stream: Keyword that to represent a release code-name.
 304         Often the same as the branch. (default: master)
 305     :submodule-recursive: Whether to checkout submodules recursively.
 306         (default: true)
 307     :submodule-timeout: Timeout (in minutes) for checkout operation.
 308         (default: 10)
 309     :submodule-disable: Disable submodule checkout operation.
 310         (default: false)
 311
 312 CMake Verify
 313 ------------
 314
 315 Verify job which runs cmake && make to test a project build, then
 316 runs make install, copies the build products to /usr/local and runs
 317 ldconfig to make the shared lib(s) available. The install steps run
 318 by default, see optional parameter "install".
 319
 320 :Template Names:
 321
 322     - {project-name}-cmake-verify-{stream}
 323     - gerrit-cmake-verify
 324     - github-cmake-verify
 325
 326 :Comment Trigger: recheck|reverify
 327
 328 :Required parameters:
 329
 330     :build-node: The node to run build on.
 331     :jenkins-ssh-credential: Credential to use for SSH.
 332         (Configure in defaults.yaml)
 333     :project: The git repository name.
 334     :project-name: Prefix used to name jobs.
 335
 336 :Optional parameters:
 337
 338     :branch: Git branch to fetch for the build. (default: master)
 339     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 340     :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
 341     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 342     :cmake-opts: Parameters to pass to cmake. (default: '')
 343     :disable-job: Whether to disable the job (default: false)
 344     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 345     :install: Install build products to /usr/local. (default: true)
 346     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 347         (default: $BUILD_DIR/output)
 348     :make-opts: Parameters to pass to make. (default: '')
 349     :pre-build: Shell script to run before performing build. Useful for
 350         setting up dependencies. (default: '')
 351     :stream: Keyword that to represent a release code-name.
 352         Often the same as the branch. (default: master)
 353     :submodule-recursive: Whether to checkout submodules recursively.
 354         (default: true)
 355     :submodule-timeout: Timeout (in minutes) for checkout operation.
 356         (default: 10)
 357     :submodule-disable: Disable submodule checkout operation.
 358         (default: false)
 359
 360     :gerrit_verify_triggers: Override Gerrit Triggers.
 361     :gerrit_trigger_file_paths: Override file paths which to filter which file
 362         modifications will trigger a build.