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 uses the build wrapper to invoke cmake && make, runs the scanner to
  13 analyze code files, and publishes the results to SonarCloud. Does not
  14 support reporting of code coverage. Optionally runs a shell script before
  15 the build to install prerequisites.
  16
  17 This job purposely runs on the master branch because the basic SonarCloud
  18 configuration does not support multi-branch.
  19
  20 :Template Names:
  21
  22     - {project-name}-cmake-sonar
  23     - gerrit-cmake-sonar
  24     - github-cmake-sonar
  25
  26 :Comment Trigger: run-sonar
  27
  28 :Required parameters:
  29
  30     :build-node: The node to run build on.
  31     :jenkins-ssh-credential: Credential to use for SSH. (Configure in
  32         defaults.yaml)
  33     :sonarcloud-api-token: SonarCloud API Token.
  34     :sonarcloud-organization: SonarCloud project organization.
  35     :sonarcloud-project-key: SonarCloud project key.
  36
  37 :Optional parameters:
  38
  39     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  40     :build-timeout: Timeout in minutes before aborting build. (default: 15)
  41     :cmake-opts: Parameters to pass to cmake. (default: '')
  42     :cron: Cron schedule when to trigger the job. This parameter also
  43         supports multiline input via YAML pipe | character in cases where
  44         one may want to provide more than 1 cron timer.  (default: '@daily')
  45     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  46     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
  47         (default: $BUILD_DIR/output)
  48     :make-opts: Parameters to pass to make. (default: '')
  49     :pre-build: Shell script to run before performing build. Useful for
  50         setting up dependencies. (default: '')
  51     :sonar-scanner-version: Version of sonar-scanner to install.
  52         (see YAML for default value; e.g., 3.3.0.1492)
  53     :submodule-recursive: Whether to checkout submodules recursively.
  54         (default: true)
  55     :submodule-timeout: Timeout (in minutes) for checkout operation.
  56         (default: 10)
  57     :submodule-disable: Disable submodule checkout operation.
  58         (default: false)
  59
  60     :gerrit_sonar_triggers: Override Gerrit Triggers.
  61
  62 CMake Stage
  63 -----------
  64
  65 Stage job which runs cmake && make && make install and then packages the
  66 project into a tar.xz tarball to produce a release candidate.
  67
  68 :Template Names:
  69
  70     - {project-name}-cmake-stage-{stream}
  71     - gerrit-cmake-stage
  72     - github-cmake-stage
  73
  74 :Comment Trigger: stage-release
  75
  76 :Required parameters:
  77
  78     :build-node: The node to run build on.
  79     :jenkins-ssh-credential: Credential to use for SSH.
  80         (Configure in defaults.yaml)
  81     :nexus-group-id: The Maven style Group ID for the namespace of the project
  82         in Nexus.
  83     :staging-profile-id: The unique Nexus Staging Profile ID for the project.
  84         Contact your infra admin if you do not know it.
  85
  86 :Optional parameters:
  87
  88     :branch: Git branch to fetch for the build. (default: master)
  89     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  90     :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
  91     :build-timeout: Timeout in minutes before aborting build. (default: 60)
  92     :cmake-opts: Parameters to pass to cmake. (default: '')
  93     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  94     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
  95         (default: $BUILD_DIR/output)
  96     :make-opts: Parameters to pass to make. (default: '')
  97     :pre-build: Shell script to run before performing build. Useful for
  98         setting up dependencies. (default: '')
  99     :stream: Keyword that to represent a release code-name.
 100         Often the same as the branch. (default: master)
 101     :submodule-recursive: Whether to checkout submodules recursively.
 102         (default: true)
 103     :submodule-timeout: Timeout (in minutes) for checkout operation.
 104         (default: 10)
 105     :submodule-disable: Disable submodule checkout operation.
 106         (default: false)
 107     :version: (default: '') Project version to stage release as. There are 2
 108         methods for using this value:
 109
 110         1) Defined explicitly here.
 111         2) Leave this value blank and set /tmp/artifact_version
 112
 113         Use method 2 in conjunction with 'pre-build' configuration to
 114         generate the artifact_version automatically from files in the
 115         project's repository. For example with pre-build script:
 116
 117         .. code-block:: bash
 118
 119            #!/bin/bash
 120            MAJOR_VERSION="$(grep 'set(OCIO_VERSION_MAJOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 121            MINOR_VERSION="$(grep 'set(OCIO_VERSION_MINOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 122            PATCH_VERSION="$(grep 'set(OCIO_VERSION_PATCH' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
 123            echo "${{MAJOR_VERSION}}.${{MINOR_VERSION}}.${{PATCH_VERSION}}" > /tmp/artifact_version
 124
 125 CMake Verify
 126 ------------
 127
 128 Verify job which runs cmake && make && make install to test a project build..
 129
 130 :Template Names:
 131
 132     - {project-name}-cmake-verify-{stream}
 133     - gerrit-cmake-verify
 134     - github-cmake-verify
 135
 136 :Comment Trigger: recheck|reverify
 137
 138 :Required parameters:
 139
 140     :build-node: The node to run build on.
 141     :jenkins-ssh-credential: Credential to use for SSH.
 142         (Configure in defaults.yaml)
 143
 144 :Optional parameters:
 145
 146     :branch: Git branch to fetch for the build. (default: master)
 147     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 148     :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
 149     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 150     :cmake-opts: Parameters to pass to cmake. (default: '')
 151     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 152     :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
 153         (default: $BUILD_DIR/output)
 154     :make-opts: Parameters to pass to make. (default: '')
 155     :pre-build: Shell script to run before performing build. Useful for
 156         setting up dependencies. (default: '')
 157     :stream: Keyword that to represent a release code-name.
 158         Often the same as the branch. (default: master)
 159     :submodule-recursive: Whether to checkout submodules recursively.
 160         (default: true)
 161     :submodule-timeout: Timeout (in minutes) for checkout operation.
 162         (default: 10)
 163     :submodule-disable: Disable submodule checkout operation.
 164         (default: false)
 165
 166     :gerrit_verify_triggers: Override Gerrit Triggers.
 167     :gerrit_trigger_file_paths: Override file paths which to filter which file
 168         modifications will trigger a build.