8 Autotools PackageCloud Stage
9 ----------------------------
11 Stage job which runs configure && make, then uploads all DEB/RPM files
12 in the build directory to PackageCloud.io. Triggered by comment.
14 The default configuration supplies a pre-build script that runs GNU
15 Autotools to generate the configure shell script. Must be overridden
16 if that script is in the version-control system.
18 The Jenkins system must have a configuration file provider that
19 installs files ".packagecloud" and "packagecloud_api" to the Jenkins
20 home directory with appropriate credentials.
22 The Jenkins build minion must have the Ruby gem "package_cloud"
27 - {project-name}-autotools-packagecloud-stage-{stream}
28 - gerrit-autotools-packagecloud-stage
29 - github-autotools-packagecloud-stage
31 :Comment Trigger: stage-release
35 :build-node: The node to run build on.
36 :debian-distribution-versions: list of DEB package distro/version strings
37 separated by space; example: "ubuntu/bionic debian/stretch"
38 :jenkins-ssh-credential: Credential to use for SSH.
39 (Configure in defaults.yaml)
40 :packagecloud-account: PackageCloud account ID; example: oran
41 :packagecloud-repo: PackageCloud repository; example: master, staging
42 :project: The git repository name.
43 :project-name: Prefix used to name jobs.
44 :rpm-distribution-versions: list of RPM package distro/version strings
45 separated by space; example: "el/4 el/5"
49 :branch: Git branch to fetch for the build. (default: master)
50 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
51 :build-dir: Directory with package files (default: $WORKSPACE)
52 :build-timeout: Timeout in minutes before aborting build. (default: 15)
53 :configure-opts: Parameters to pass to configure. (default: '')
54 :disable-job: Whether to disable the job (default: false)
55 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
56 :install: Install build products to /usr/local. (default: false)
57 :install-prefix: Path to use for install. (default: $BUILD_DIR/output)
58 :make-opts: Parameters and targets for make. (default: '')
59 :pre-build: Shell script to generate the configure file and install
60 dependencies. (default: 'autoreconf --install')
61 :stream: Keyword that to represent a release code-name.
62 Often the same as the branch. (default: master)
63 :submodule-recursive: Whether to checkout submodules recursively.
65 :submodule-timeout: Timeout (in minutes) for checkout operation.
67 :submodule-disable: Disable submodule checkout operation.
73 The SonarQube job installs the SonarQube CXX build wrapper, runs
74 configure, uses the build wrapper to invoke make, then runs the
75 SonarQube Scanner Jenkins plug-in to analyze code for bugs, code
76 smells and security vulnerabilities, and to upload the result
77 (possibly including code-coverage statistics) to a SonarQube server or
78 to SonarCloud.io. Optionally runs a shell script before the build to
79 install prerequisites.
81 The default configuration supplies a pre-build script that runs GNU
82 Autotools to generate the configure shell script. Must be overridden
83 if that script is in the version-control system.
85 Requires ``SonarQube Scanner for Jenkins``
87 This job runs on the master branch because the basic Sonar
88 configuration does not support multi-branch.
90 Plug-in configurations
91 Manage Jenkins --> Configure System --> SonarQube servers
93 - Server URL: https://sonar.project.org/ or https://sonarcloud.io
94 - Server authentication token: none for local, API token (saved as
95 a "secret text" credential) for Sonarcloud
97 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
98 - Name: SonarQube Scanner (fixed)
99 - Install automatically
100 - Select latest version
104 - {project-name}-autotools-sonarqube
105 - gerrit-autotools-sonarqube
106 - github-autotools-sonarqube
108 :Comment Trigger: ``run-sonar``
110 :Required parameters:
112 :build-node: The node to run the build on.
113 (Commonly in defaults.yaml)
114 :jenkins-ssh-credential: Credential to use for SSH.
115 (Commonly in defaults.yaml)
116 :project: The git repository name.
117 :project-name: Prefix used to name jobs.
119 .. comment Start ignoring WriteGoodLintBear
121 :Optional Parameters:
123 :branch: Git branch to fetch for the build. (default: master)
124 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
125 :build-timeout: Timeout in minutes before aborting build. (default: 15)
126 :build-wrap-dir: Build wrapper output subdirectory name.
127 (default: $WORKSPACE/bw-output)
128 :configure-opts: Parameters to pass to configure. (default: '')
129 :cron: Cron schedule when to trigger the job. This parameter also
130 supports multiline input via YAML pipe | character in cases where
131 one may want to provide more than 1 cron timer. (default: @weekly)
132 :disable-job: Whether to disable the job (default: false)
133 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
134 :install-prefix: Path to use for install. (default: $BUILD_DIR/output)
135 :make-opts: Parameters and targets for make. (default: '')
136 :pre-build: Shell script to generate the configure file and install
137 dependencies. (default: 'autoreconf --install')
138 :sonar-additional-args: Command line arguments. (default: '')
139 :sonar-java-opts: JVM options. For example, use option -Xmx
140 to increase the memory size limit. (default: '')
141 :sonar-project-file: The file name with Sonar configuration properties
142 (default: sonar-project.properties)
143 :sonar-properties: Sonar configuration properties. (default: '')
144 :sonar-task: Sonar task to run. (default: '')
145 :stream: Keyword that to represent a release code-name.
146 Often the same as the branch. (default: master)
147 :submodule-recursive: Whether to checkout submodules recursively.
149 :submodule-timeout: Timeout (in minutes) for checkout operation.
151 :submodule-disable: Disable submodule checkout operation.
154 .. comment Stop ignoring
156 .. note:: A job definition must provide one of the optional parameters
157 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
158 empty. Set Sonar properties directly in the job definition by setting
159 the ``sonar-project-file`` property to ``""`` and adding all properties
160 under ``sonar-properties``.
162 :Required Sonar Properties:
164 - sonar.login: The API token for authentication at SonarCloud.
165 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
166 - sonar.organization: The umbrella project name; e.g., "opendaylight".
167 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
168 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
169 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
170 teams use the catenation of sonar.organization, an underscore, and
171 sonar.projectName; e.g., "opendaylight_infrautils".
173 :Optional Sonar Properties:
175 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
176 - Documentation of SonarQube properties is here:
177 https://docs.sonarqube.org/latest/analysis/overview/
180 Example job definition
181 ^^^^^^^^^^^^^^^^^^^^^^
183 The following example defines a job for a project with CXX source files
184 in the "src" directory, and unit tests that write coverage files in
185 GCOV format to the "test" directory. This definition uses configuration
186 parameters in the umbrella project's defaults.yaml file.
191 name: my-project-sonar
193 project-name: my-project
194 sonar-project-file: ""
196 sonar.login={sonarcloud_api_token}
197 sonar.projectKey={sonarcloud_project_organization}_{project-name}
198 sonar.projectName={project-name}
199 sonar.organization={sonarcloud_project_organization}
200 sonar.sourceEncoding=UTF-8
202 sonar.cfamily.build-wrapper-output=$WORKSPACE/bw-output
203 sonar.cfamily.gcov.reportsPath=test
205 - gerrit-autotools-sonarqube
210 Verify job which runs configure && make to test a project build, then
211 optionally runs make install, copies the build products to /usr/local
212 and runs ldconfig to make the shared lib(s) available. The install steps
213 run by default, see parameter "install".
215 The default configuration supplies a pre-build script that runs GNU
216 Autotools to generate the configure shell script. Must be overridden
217 if the script is in the version-control system.
221 - {project-name}-autotools-verify-{stream}
222 - gerrit-autotools-verify
223 - github-autotools-verify
225 :Comment Trigger: recheck|reverify
227 :Required parameters:
229 :build-node: The node to run build on.
230 :jenkins-ssh-credential: Credential to use for SSH.
231 (Configure in defaults.yaml)
232 :project: The git repository name.
233 :project-name: Prefix used to name jobs.
235 :Optional parameters:
237 :branch: Git branch to fetch for the build. (default: master)
238 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
239 :build-timeout: Timeout in minutes before aborting build. (default: 15)
240 :configure-opts: Parameters to pass to configure. (default: '')
241 :disable-job: Whether to disable the job (default: false)
242 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
243 :install: Install build products to /usr/local. (default: true)
244 :install-prefix: Path to use for install. (default: $BUILD_DIR/output)
245 :make-opts: Parameters and targets for make. (default: 'test')
246 :pre-build: Shell script to generate the configure file and install
247 dependencies. (default: 'autoreconf --install')
248 :stream: Keyword that to represent a release code-name.
249 Often the same as the branch. (default: master)
250 :submodule-recursive: Whether to checkout submodules recursively.
252 :submodule-timeout: Timeout (in minutes) for checkout operation.
254 :submodule-disable: Disable submodule checkout operation.
257 :gerrit_verify_triggers: Override Gerrit Triggers.
258 :gerrit_trigger_file_paths: Override file paths which to filter which file
259 modifications will trigger a build.
264 The Sonar job installs the SonarQube CXX build wrapper and scanner tools,
265 runs cmake, uses the build wrapper to invoke make, runs the scanner to
266 analyze code files, then publishes the results to a SonarQube server like
267 SonarCloud. Optionally runs a shell script before the build to install
268 prerequisites. Does not support code coverage reporting.
270 **Deprecated**; new projects should use a CMake SonarQube template.
272 This job purposely runs on the master branch because the basic SonarCloud
273 configuration does not support multi-branch.
277 - {project-name}-cmake-sonar
281 :Comment Trigger: run-sonar
283 :Required parameters:
285 :build-node: The node to run build on.
286 :jenkins-ssh-credential: Credential to use for SSH. (Configure in
288 :sonarcloud-organization: SonarCloud project organization.
289 :sonarcloud-project-key: SonarCloud project key.
291 :Optional parameters:
293 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
294 :build-timeout: Timeout in minutes before aborting build. (default: 15)
295 :cmake-opts: Parameters to pass to cmake. (default: '')
296 :cron: Cron schedule when to trigger the job. This parameter also
297 supports multiline input via YAML pipe | character in cases where
298 one may want to provide more than 1 cron timer. (default: '@daily')
299 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
300 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
301 (default: $BUILD_DIR/output)
302 :make-opts: Parameters to pass to make. (default: '')
303 :pre-build: Shell script to run before performing build. Useful for
304 setting up dependencies. (default: '')
305 :sonar-scanner-version: Version of sonar-scanner to install.
306 (see YAML for default value; e.g., 3.3.0.1492)
307 :sonarcloud-api-token-cred-id: Jenkins credential ID which has the SonarCloud API Token.
308 This one SHOULDN'T be overwritten as per we are standarizing the credential ID for all
309 projects (default: 'sonarcloud-api-token')
310 :submodule-recursive: Whether to checkout submodules recursively.
312 :submodule-timeout: Timeout (in minutes) for checkout operation.
314 :submodule-disable: Disable submodule checkout operation.
317 :gerrit_sonar_triggers: Override Gerrit Triggers.
322 The SonarQube job installs the SonarQube CXX build wrapper, runs cmake, uses
323 the build wrapper to invoke make, then runs the SonarQube Scanner Jenkins
324 plug-in to analyze code for bugs, code smells and security vulnerabilities,
325 and to upload the result (possibly including code-coverage statistics) to
326 a SonarQube server or to SonarCloud.io. Optionally runs a shell script
327 before the build to install prerequisites.
329 Requires ``SonarQube Scanner for Jenkins``
331 This job runs on the master branch because the basic Sonar configuration
332 does not support multi-branch.
334 Plug-in configurations
335 Manage Jenkins --> Configure System --> SonarQube servers
336 - Name: Sonar (fixed)
337 - Server URL: https://sonar.project.org/ or https://sonarcloud.io
338 - Server authentication token: none for local, API token (saved as
339 a "secret text" credential) for Sonarcloud
341 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
342 - Name: SonarQube Scanner (fixed)
343 - Install automatically
344 - Select latest version
348 - {project-name}-cmake-sonarqube
349 - gerrit-cmake-sonarqube
350 - github-cmake-sonarqube
352 :Comment Trigger: ``run-sonar``
354 :Required parameters:
356 :build-node: The node to run the build on.
357 (Commonly in defaults.yaml)
358 :jenkins-ssh-credential: Credential to use for SSH.
359 (Commonly in defaults.yaml)
360 :project: The git repository name.
361 :project-name: Prefix used to name jobs.
363 .. comment Start ignoring WriteGoodLintBear
365 :Optional Parameters:
367 :archive-artifacts: Pattern for files to archive to the logs server
368 (default: '\*\*/\*.log')
369 :build-wrap-dir: Build wrapper output subdirectory name.
370 (default: $WORKSPACE/bw-output)
371 :cmake-opts: Parameters to pass to cmake. (default: '')
372 :cron: Cron schedule when to trigger the job. This parameter also
373 supports multiline input via YAML pipe | character in cases where
374 one may want to provide more than 1 cron timer. (default: @weekly)
375 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
376 (default: $BUILD_DIR/output)
377 :make-opts: Parameters to pass to make. (default: '')
378 :pre-build: Shell script to run before performing build. Useful for
379 setting up dependencies. (default: '')
380 :sonar-additional-args: Command line arguments. (default: '')
381 :sonar-java-opts: JVM options. For example, use option -Xmx
382 to increase the memory size limit. (default: '')
383 :sonar-project-file: The file name with Sonar configuration properties
384 (default: sonar-project.properties)
385 :sonar-properties: Sonar configuration properties. (default: '')
386 :sonar-task: Sonar task to run. (default: '')
388 .. comment Stop ignoring
390 .. note:: A job definition must provide one of the optional parameters
391 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
392 empty. Set Sonar properties directly in the job definition by setting
393 the ``sonar-project-file`` property to ``""`` and adding all properties
394 under ``sonar-properties``.
396 :Required Sonar Properties:
398 - sonar.login: The API token for authentication at SonarCloud.
399 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
400 - sonar.organization: The umbrella project name; e.g., "opendaylight".
401 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
402 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
403 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
404 teams use the catenation of sonar.organization, an underscore, and
405 sonar.projectName; e.g., "opendaylight_infrautils".
407 :Optional Sonar Properties:
409 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
410 - Documentation of SonarQube properties is here:
411 https://docs.sonarqube.org/latest/analysis/overview/
414 Example job definition
415 ^^^^^^^^^^^^^^^^^^^^^^
417 The following example defines a job for a project with CXX source files
418 in the "src" directory, and unit tests that write coverage files in
419 GCOV format to the "test" directory. This definition uses configuration
420 parameters in the umbrella project's defaults.yaml file.
425 name: my-project-sonar
427 project-name: my-project
428 sonar-project-file: ""
430 sonar.login={sonarcloud_api_token}
431 sonar.projectKey={sonarcloud_project_organization}_{project-name}
432 sonar.projectName={project-name}
433 sonar.organization={sonarcloud_project_organization}
434 sonar.sourceEncoding=UTF-8
436 sonar.cfamily.build-wrapper-output=$WORKSPACE/bw-output
437 sonar.cfamily.gcov.reportsPath=test
439 - gerrit-cmake-sonarqube
444 Stage job which runs cmake && make && make install and then packages the
445 project into a tar.xz tarball to produce a release candidate.
449 - {project-name}-cmake-stage-{stream}
453 :Comment Trigger: stage-release
455 :Required parameters:
457 :build-node: The node to run build on.
458 :jenkins-ssh-credential: Credential to use for SSH.
459 (Configure in defaults.yaml)
460 :mvn-settings: The name of settings file containing credentials for the project.
461 :nexus-group-id: The Maven style Group ID for the namespace of the project
463 :staging-profile-id: The unique Nexus Staging Profile ID for the project.
464 Contact your infra admin if you do not know it.
466 :Optional parameters:
468 :branch: Git branch to fetch for the build. (default: master)
469 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
470 :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
471 :build-timeout: Timeout in minutes before aborting build. (default: 60)
472 :cmake-opts: Parameters to pass to cmake. (default: '')
473 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
474 :install: Install build products to /usr/local. (default: true)
475 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
476 (default: $BUILD_DIR/output)
477 :make-opts: Parameters to pass to make. (default: '')
478 :mvn-global-settings: The name of the Maven global settings to use for
479 Maven configuration. (default: global-settings)
480 :pre-build: Shell script to run before performing build. Useful for
481 setting up dependencies. (default: '')
482 :stream: Keyword that to represent a release code-name.
483 Often the same as the branch. (default: master)
484 :submodule-recursive: Whether to checkout submodules recursively.
486 :submodule-timeout: Timeout (in minutes) for checkout operation.
488 :submodule-disable: Disable submodule checkout operation.
490 :version: (default: '') Project version to stage release as. There are 2
491 methods for using this value:
493 1) Defined explicitly here.
494 2) Leave this value blank and set /tmp/artifact_version
496 Use method 2 in conjunction with 'pre-build' configuration to
497 generate the artifact_version automatically from files in the
498 project's repository. An example pre-build script appears below.
504 MAJOR_VERSION="$(grep 'set(OCIO_VERSION_MAJOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
505 MINOR_VERSION="$(grep 'set(OCIO_VERSION_MINOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
506 PATCH_VERSION="$(grep 'set(OCIO_VERSION_PATCH' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
507 echo "${{MAJOR_VERSION}}.${{MINOR_VERSION}}.${{PATCH_VERSION}}" > /tmp/artifact_version
509 CMake PackageCloud Stage
510 ------------------------
512 Stage job which runs cmake && make, then uploads all DEB/RPM files in the
513 build directory to PackageCloud.io. Triggered by comment.
515 The Jenkins system must have a configuration file provider that installs
516 files ".packagecloud" and "packagecloud_api" to the Jenkins home directory
517 with appropriate credentials.
519 The Jenkins build minion must have the Ruby gem "package_cloud" installed.
523 - {project-name}-cmake-packagecloud-stage-{stream}
524 - gerrit-cmake-packagecloud-stage
525 - github-cmake-packagecloud-stage
527 :Comment Trigger: stage-release
529 :Required parameters:
531 :build-node: The node to run build on.
532 :debian-distribution-versions: list of DEB package distro/version strings
533 separated by space; example: "ubuntu/bionic debian/stretch"
534 :jenkins-ssh-credential: Credential to use for SSH.
535 (Configure in defaults.yaml)
536 :packagecloud-account: PackageCloud account ID; example: oran
537 :packagecloud-repo: PackageCloud repository; example: master, staging
538 :project: The git repository name.
539 :project-name: Prefix used to name jobs.
540 :rpm-distribution-versions: list of RPM package distro/version strings
541 separated by space; example: "el/4 el/5"
543 :Optional parameters:
545 :branch: Git branch to fetch for the build. (default: master)
546 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
547 :build-dir: Directory to build the project in. (default: $WORKSPACE/build)
548 :build-timeout: Timeout in minutes before aborting build. (default: 60)
549 :cmake-opts: Parameters to pass to cmake. (default: '')
550 :disable-job: Whether to disable the job (default: false)
551 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
552 :install: Install build products to /usr/local. (default: false)
553 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
554 (default: $BUILD_DIR/output)
555 :make-opts: Parameters to pass to make. (default: '')
556 :pre-build: Shell script to run before performing build. Useful for
557 setting up dependencies. (default: '')
558 :stream: Keyword that to represent a release code-name.
559 Often the same as the branch. (default: master)
560 :submodule-recursive: Whether to checkout submodules recursively.
562 :submodule-timeout: Timeout (in minutes) for checkout operation.
564 :submodule-disable: Disable submodule checkout operation.
570 Verify job which runs cmake && make to test a project build, then
571 runs make install, copies the build products to /usr/local and runs
572 ldconfig to make the shared lib(s) available. The install steps run
573 by default, see optional parameter "install".
577 - {project-name}-cmake-verify-{stream}
578 - gerrit-cmake-verify
579 - github-cmake-verify
581 :Comment Trigger: recheck|reverify
583 :Required parameters:
585 :build-node: The node to run build on.
586 :jenkins-ssh-credential: Credential to use for SSH.
587 (Configure in defaults.yaml)
588 :project: The git repository name.
589 :project-name: Prefix used to name jobs.
591 :Optional parameters:
593 :branch: Git branch to fetch for the build. (default: master)
594 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
595 :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
596 :build-timeout: Timeout in minutes before aborting build. (default: 60)
597 :cmake-opts: Parameters to pass to cmake. (default: '')
598 :disable-job: Whether to disable the job (default: false)
599 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
600 :install: Install build products to /usr/local. (default: true)
601 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
602 (default: $BUILD_DIR/output)
603 :make-opts: Parameters to pass to make. (default: '')
604 :pre-build: Shell script to run before performing build. Useful for
605 setting up dependencies. (default: '')
606 :stream: Keyword that to represent a release code-name.
607 Often the same as the branch. (default: master)
608 :submodule-recursive: Whether to checkout submodules recursively.
610 :submodule-timeout: Timeout (in minutes) for checkout operation.
612 :submodule-disable: Disable submodule checkout operation.
615 :gerrit_verify_triggers: Override Gerrit Triggers.
616 :gerrit_trigger_file_paths: Override file paths which to filter which file
617 modifications will trigger a build.