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