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.
17 **Deprecated**; new projects should use a CMake SonarQube template.
19 This job purposely runs on the master branch because the basic SonarCloud
20 configuration does not support multi-branch.
24 - {project-name}-cmake-sonar
28 :Comment Trigger: run-sonar
32 :build-node: The node to run build on.
33 :jenkins-ssh-credential: Credential to use for SSH. (Configure in
35 :sonarcloud-api-token: SonarCloud API Token.
36 :sonarcloud-organization: SonarCloud project organization.
37 :sonarcloud-project-key: SonarCloud project key.
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.
57 :submodule-timeout: Timeout (in minutes) for checkout operation.
59 :submodule-disable: Disable submodule checkout operation.
62 :gerrit_sonar_triggers: Override Gerrit Triggers.
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.
74 Requires ``SonarQube Scanner for Jenkins``
76 This job runs on the master branch because the basic Sonar configuration
77 does not support multi-branch.
79 Plug-in configurations
80 Manage Jenkins --> Configure System --> SonarQube servers
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
86 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
87 - Name: SonarQube Scanner (fixed)
88 - Install automatically
89 - Select latest version
93 - {project-name}-cmake-sonarqube
94 - gerrit-cmake-sonarqube
95 - github-cmake-sonarqube
97 :Comment Trigger: ``run-sonar``
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.
108 .. comment Start ignoring WriteGoodLintBear
110 :Optional Parameters:
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: '')
133 .. comment Stop ignoring
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``.
141 :Required Sonar Properties:
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".
152 :Optional Sonar Properties:
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/
159 Example job definition
160 ^^^^^^^^^^^^^^^^^^^^^^
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.
170 name: my-project-sonar
172 project-name: my-project
173 sonar-project-file: ""
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
181 sonar.cfamily.build-wrapper-output=$WORKSPACE/bw-output
182 sonar.cfamily.gcov.reportsPath=test
184 - gerrit-cmake-sonarqube
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.
194 - {project-name}-cmake-stage-{stream}
198 :Comment Trigger: stage-release
200 :Required parameters:
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
207 :staging-profile-id: The unique Nexus Staging Profile ID for the project.
208 Contact your infra admin if you do not know it.
210 :Optional parameters:
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.
227 :submodule-timeout: Timeout (in minutes) for checkout operation.
229 :submodule-disable: Disable submodule checkout operation.
231 :version: (default: '') Project version to stage release as. There are 2
232 methods for using this value:
234 1) Defined explicitly here.
235 2) Leave this value blank and set /tmp/artifact_version
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.
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
253 Verify job which runs cmake && make && make install to test a project build..
257 - {project-name}-cmake-verify-{stream}
258 - gerrit-cmake-verify
259 - github-cmake-verify
261 :Comment Trigger: recheck|reverify
263 :Required parameters:
265 :build-node: The node to run build on.
266 :jenkins-ssh-credential: Credential to use for SSH.
267 (Configure in defaults.yaml)
269 :Optional parameters:
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.
286 :submodule-timeout: Timeout (in minutes) for checkout operation.
288 :submodule-disable: Disable submodule checkout operation.
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.