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-api-token: SonarCloud API Token.
289 :sonarcloud-organization: SonarCloud project organization.
290 :sonarcloud-project-key: SonarCloud project key.
292 :Optional parameters:
294 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
295 :build-timeout: Timeout in minutes before aborting build. (default: 15)
296 :cmake-opts: Parameters to pass to cmake. (default: '')
297 :cron: Cron schedule when to trigger the job. This parameter also
298 supports multiline input via YAML pipe | character in cases where
299 one may want to provide more than 1 cron timer. (default: '@daily')
300 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
301 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
302 (default: $BUILD_DIR/output)
303 :make-opts: Parameters to pass to make. (default: '')
304 :pre-build: Shell script to run before performing build. Useful for
305 setting up dependencies. (default: '')
306 :sonar-scanner-version: Version of sonar-scanner to install.
307 (see YAML for default value; e.g., 3.3.0.1492)
308 :submodule-recursive: Whether to checkout submodules recursively.
310 :submodule-timeout: Timeout (in minutes) for checkout operation.
312 :submodule-disable: Disable submodule checkout operation.
315 :gerrit_sonar_triggers: Override Gerrit Triggers.
320 The SonarQube job installs the SonarQube CXX build wrapper, runs cmake, uses
321 the build wrapper to invoke make, then runs the SonarQube Scanner Jenkins
322 plug-in to analyze code for bugs, code smells and security vulnerabilities,
323 and to upload the result (possibly including code-coverage statistics) to
324 a SonarQube server or to SonarCloud.io. Optionally runs a shell script
325 before the build to install prerequisites.
327 Requires ``SonarQube Scanner for Jenkins``
329 This job runs on the master branch because the basic Sonar configuration
330 does not support multi-branch.
332 Plug-in configurations
333 Manage Jenkins --> Configure System --> SonarQube servers
334 - Name: Sonar (fixed)
335 - Server URL: https://sonar.project.org/ or https://sonarcloud.io
336 - Server authentication token: none for local, API token (saved as
337 a "secret text" credential) for Sonarcloud
339 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
340 - Name: SonarQube Scanner (fixed)
341 - Install automatically
342 - Select latest version
346 - {project-name}-cmake-sonarqube
347 - gerrit-cmake-sonarqube
348 - github-cmake-sonarqube
350 :Comment Trigger: ``run-sonar``
352 :Required parameters:
354 :build-node: The node to run the build on.
355 (Commonly in defaults.yaml)
356 :jenkins-ssh-credential: Credential to use for SSH.
357 (Commonly in defaults.yaml)
358 :project: The git repository name.
359 :project-name: Prefix used to name jobs.
361 .. comment Start ignoring WriteGoodLintBear
363 :Optional Parameters:
365 :archive-artifacts: Pattern for files to archive to the logs server
366 (default: '\*\*/\*.log')
367 :build-wrap-dir: Build wrapper output subdirectory name.
368 (default: $WORKSPACE/bw-output)
369 :cmake-opts: Parameters to pass to cmake. (default: '')
370 :cron: Cron schedule when to trigger the job. This parameter also
371 supports multiline input via YAML pipe | character in cases where
372 one may want to provide more than 1 cron timer. (default: @weekly)
373 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
374 (default: $BUILD_DIR/output)
375 :make-opts: Parameters to pass to make. (default: '')
376 :pre-build: Shell script to run before performing build. Useful for
377 setting up dependencies. (default: '')
378 :sonar-additional-args: Command line arguments. (default: '')
379 :sonar-java-opts: JVM options. For example, use option -Xmx
380 to increase the memory size limit. (default: '')
381 :sonar-project-file: The file name with Sonar configuration properties
382 (default: sonar-project.properties)
383 :sonar-properties: Sonar configuration properties. (default: '')
384 :sonar-task: Sonar task to run. (default: '')
386 .. comment Stop ignoring
388 .. note:: A job definition must provide one of the optional parameters
389 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
390 empty. Set Sonar properties directly in the job definition by setting
391 the ``sonar-project-file`` property to ``""`` and adding all properties
392 under ``sonar-properties``.
394 :Required Sonar Properties:
396 - sonar.login: The API token for authentication at SonarCloud.
397 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
398 - sonar.organization: The umbrella project name; e.g., "opendaylight".
399 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
400 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
401 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
402 teams use the catenation of sonar.organization, an underscore, and
403 sonar.projectName; e.g., "opendaylight_infrautils".
405 :Optional Sonar Properties:
407 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
408 - Documentation of SonarQube properties is here:
409 https://docs.sonarqube.org/latest/analysis/overview/
412 Example job definition
413 ^^^^^^^^^^^^^^^^^^^^^^
415 The following example defines a job for a project with CXX source files
416 in the "src" directory, and unit tests that write coverage files in
417 GCOV format to the "test" directory. This definition uses configuration
418 parameters in the umbrella project's defaults.yaml file.
423 name: my-project-sonar
425 project-name: my-project
426 sonar-project-file: ""
428 sonar.login={sonarcloud_api_token}
429 sonar.projectKey={sonarcloud_project_organization}_{project-name}
430 sonar.projectName={project-name}
431 sonar.organization={sonarcloud_project_organization}
432 sonar.sourceEncoding=UTF-8
434 sonar.cfamily.build-wrapper-output=$WORKSPACE/bw-output
435 sonar.cfamily.gcov.reportsPath=test
437 - gerrit-cmake-sonarqube
442 Stage job which runs cmake && make && make install and then packages the
443 project into a tar.xz tarball to produce a release candidate.
447 - {project-name}-cmake-stage-{stream}
451 :Comment Trigger: stage-release
453 :Required parameters:
455 :build-node: The node to run build on.
456 :jenkins-ssh-credential: Credential to use for SSH.
457 (Configure in defaults.yaml)
458 :mvn-settings: The name of settings file containing credentials for the project.
459 :nexus-group-id: The Maven style Group ID for the namespace of the project
461 :staging-profile-id: The unique Nexus Staging Profile ID for the project.
462 Contact your infra admin if you do not know it.
464 :Optional parameters:
466 :branch: Git branch to fetch for the build. (default: master)
467 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
468 :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
469 :build-timeout: Timeout in minutes before aborting build. (default: 60)
470 :cmake-opts: Parameters to pass to cmake. (default: '')
471 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
472 :install: Install build products to /usr/local. (default: true)
473 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
474 (default: $BUILD_DIR/output)
475 :make-opts: Parameters to pass to make. (default: '')
476 :mvn-global-settings: The name of the Maven global settings to use for
477 Maven configuration. (default: global-settings)
478 :pre-build: Shell script to run before performing build. Useful for
479 setting up dependencies. (default: '')
480 :stream: Keyword that to represent a release code-name.
481 Often the same as the branch. (default: master)
482 :submodule-recursive: Whether to checkout submodules recursively.
484 :submodule-timeout: Timeout (in minutes) for checkout operation.
486 :submodule-disable: Disable submodule checkout operation.
488 :version: (default: '') Project version to stage release as. There are 2
489 methods for using this value:
491 1) Defined explicitly here.
492 2) Leave this value blank and set /tmp/artifact_version
494 Use method 2 in conjunction with 'pre-build' configuration to
495 generate the artifact_version automatically from files in the
496 project's repository. An example pre-build script appears below.
502 MAJOR_VERSION="$(grep 'set(OCIO_VERSION_MAJOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
503 MINOR_VERSION="$(grep 'set(OCIO_VERSION_MINOR' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
504 PATCH_VERSION="$(grep 'set(OCIO_VERSION_PATCH' CMakeLists.txt | awk '{{print $NF}}' | awk -F')' '{{print $1}}')"
505 echo "${{MAJOR_VERSION}}.${{MINOR_VERSION}}.${{PATCH_VERSION}}" > /tmp/artifact_version
507 CMake PackageCloud Stage
508 ------------------------
510 Stage job which runs cmake && make, then uploads all DEB/RPM files in the
511 build directory to PackageCloud.io. Triggered by comment.
513 The Jenkins system must have a configuration file provider that installs
514 files ".packagecloud" and "packagecloud_api" to the Jenkins home directory
515 with appropriate credentials.
517 The Jenkins build minion must have the Ruby gem "package_cloud" installed.
521 - {project-name}-cmake-packagecloud-stage-{stream}
522 - gerrit-cmake-packagecloud-stage
523 - github-cmake-packagecloud-stage
525 :Comment Trigger: stage-release
527 :Required parameters:
529 :build-node: The node to run build on.
530 :debian-distribution-versions: list of DEB package distro/version strings
531 separated by space; example: "ubuntu/bionic debian/stretch"
532 :jenkins-ssh-credential: Credential to use for SSH.
533 (Configure in defaults.yaml)
534 :packagecloud-account: PackageCloud account ID; example: oran
535 :packagecloud-repo: PackageCloud repository; example: master, staging
536 :project: The git repository name.
537 :project-name: Prefix used to name jobs.
538 :rpm-distribution-versions: list of RPM package distro/version strings
539 separated by space; example: "el/4 el/5"
541 :Optional parameters:
543 :branch: Git branch to fetch for the build. (default: master)
544 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
545 :build-dir: Directory to build the project in. (default: $WORKSPACE/build)
546 :build-timeout: Timeout in minutes before aborting build. (default: 60)
547 :cmake-opts: Parameters to pass to cmake. (default: '')
548 :disable-job: Whether to disable the job (default: false)
549 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
550 :install: Install build products to /usr/local. (default: false)
551 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
552 (default: $BUILD_DIR/output)
553 :make-opts: Parameters to pass to make. (default: '')
554 :pre-build: Shell script to run before performing build. Useful for
555 setting up dependencies. (default: '')
556 :stream: Keyword that to represent a release code-name.
557 Often the same as the branch. (default: master)
558 :submodule-recursive: Whether to checkout submodules recursively.
560 :submodule-timeout: Timeout (in minutes) for checkout operation.
562 :submodule-disable: Disable submodule checkout operation.
568 Verify job which runs cmake && make to test a project build, then
569 runs make install, copies the build products to /usr/local and runs
570 ldconfig to make the shared lib(s) available. The install steps run
571 by default, see optional parameter "install".
575 - {project-name}-cmake-verify-{stream}
576 - gerrit-cmake-verify
577 - github-cmake-verify
579 :Comment Trigger: recheck|reverify
581 :Required parameters:
583 :build-node: The node to run build on.
584 :jenkins-ssh-credential: Credential to use for SSH.
585 (Configure in defaults.yaml)
586 :project: The git repository name.
587 :project-name: Prefix used to name jobs.
589 :Optional parameters:
591 :branch: Git branch to fetch for the build. (default: master)
592 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
593 :build-dir: Directory to build the project in. (default: $WORKSPACE/target)
594 :build-timeout: Timeout in minutes before aborting build. (default: 60)
595 :cmake-opts: Parameters to pass to cmake. (default: '')
596 :disable-job: Whether to disable the job (default: false)
597 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
598 :install: Install build products to /usr/local. (default: true)
599 :install-prefix: CMAKE_INSTALL_PREFIX to use for install.
600 (default: $BUILD_DIR/output)
601 :make-opts: Parameters to pass to make. (default: '')
602 :pre-build: Shell script to run before performing build. Useful for
603 setting up dependencies. (default: '')
604 :stream: Keyword that to represent a release code-name.
605 Often the same as the branch. (default: master)
606 :submodule-recursive: Whether to checkout submodules recursively.
608 :submodule-timeout: Timeout (in minutes) for checkout operation.
610 :submodule-disable: Disable submodule checkout operation.
613 :gerrit_verify_triggers: Override Gerrit Triggers.
614 :gerrit_trigger_file_paths: Override file paths which to filter which file
615 modifications will trigger a build.