Skip to content

Commit 826174a

Browse files
jimklimovjimklimov
committed
Problem: testing buildability of docs, then building them again to publish a package, is a waste of resources
Solution: add a way to post a standard "dist" tarball of the package with prepared manpages, so the publishing helper (as implemented by Jenkins farm admins) can use it for quicker packaging. Signed-off-by: Jim Klimov <[email protected]>
1 parent ea45f82 commit 826174a

5 files changed

+52
-6
lines changed

‎Jenkinsfile

+16-2
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,10 @@ pipeline {
5252
defaultValue: false,
5353
description: 'Attempt a build with docs in this run? (Note: corresponding tools are required in the build environment)',
5454
name: 'DO_BUILD_DOCS')
55+
booleanParam (
56+
defaultValue: false,
57+
description: 'Publish as an archive a "dist" tarball from a build with docs in this run? (Note: corresponding tools are required in the build environment; enabling this enforces DO_BUILD_DOCS too)',
58+
name: 'DO_DIST_DOCS')
5559
booleanParam (
5660
defaultValue: true,
5761
description: 'Attempt "make check" in this run?',
@@ -145,12 +149,19 @@ pipeline {
145149
}
146150
}
147151
stage ('build with DOCS') {
148-
when { expression { return ( params.DO_BUILD_DOCS ) } }
152+
when { expression { return ( params.DO_BUILD_DOCS || params.DO_DIST_DOCS ) } }
149153
steps {
150154
dir("tmp/build-DOCS") {
151155
deleteDir()
152156
unstash 'prepped'
153157
sh 'CCACHE_BASEDIR="`pwd`" ; export CCACHE_BASEDIR; ./configure --enable-drafts=yes --with-docs=yes'
158+
script {
159+
if ( params.DO_DIST_DOCS ) {
160+
sh 'CCACHE_BASEDIR="`pwd`" ; export CCACHE_BASEDIR; make dist-gzip || exit ; DISTFILE="`ls -1tc *.tar.gz | head -1`" && [ -n "$DISTFILE" ] && [ -s "$DISTFILE" ] || exit ; mv -f "$DISTFILE" __dist.tar.gz'
161+
archiveArtifacts artifacts: '__dist.tar.gz'
162+
sh "rm -f __dist.tar.gz"
163+
}
164+
}
154165
sh 'CCACHE_BASEDIR="`pwd`" ; export CCACHE_BASEDIR; make -k -j4 || make'
155166
sh 'echo "Are GitIgnores good after make with docs? (should have no output below)"; git status -s || if [ "${params.REQUIRE_GOOD_GITIGNORE}" = false ]; then echo "WARNING GitIgnore tests found newly changed or untracked files" >&2 ; exit 0 ; else echo "FAILED GitIgnore tests" >&2 ; exit 1; fi'
156167
stash (name: 'built-docs', includes: '**/*', excludes: '**/cppcheck.xml')
@@ -362,10 +373,13 @@ pipeline {
362373
if ( env.BRANCH_NAME =~ myDEPLOY_BRANCH_PATTERN ) {
363374
def GIT_URL = sh(returnStdout: true, script: """git remote -v | egrep '^origin' | awk '{print \$2}' | head -1""").trim()
364375
def GIT_COMMIT = sh(returnStdout: true, script: 'git rev-parse --verify HEAD').trim()
376+
def DIST_ARCHIVE = ""
377+
if ( params.DO_DIST_DOCS ) { DIST_ARCHIVE = env.BUILD_URL + "artifact/__dist.tar.gz" }
365378
build job: "${myDEPLOY_JOB_NAME}", parameters: [
366379
string(name: 'DEPLOY_GIT_URL', value: "${GIT_URL}"),
367380
string(name: 'DEPLOY_GIT_BRANCH', value: env.BRANCH_NAME),
368-
string(name: 'DEPLOY_GIT_COMMIT', value: "${GIT_COMMIT}")
381+
string(name: 'DEPLOY_GIT_COMMIT', value: "${GIT_COMMIT}"),
382+
string(name: 'DEPLOY_DIST_ARCHIVE', value: "${DIST_ARCHIVE}")
369383
], quietPeriod: 0, wait: myDEPLOY_REPORT_RESULT, propagate: myDEPLOY_REPORT_RESULT
370384
} else {
371385
echo "Not deploying because branch '${env.BRANCH_NAME}' did not match filter '${myDEPLOY_BRANCH_PATTERN}'"

‎Jenkinsfile-deploy.example

+7-2
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ pipeline {
3131
defaultValue: '',
3232
description: 'The commit ID of the sources to check out (may be not current HEAD of that repo/branch)',
3333
name: 'DEPLOY_GIT_COMMIT')
34+
string (
35+
defaultValue: '',
36+
description: 'URL to a "dist" archive prepared by the build (e.g. with pregenerated docs and config script) which will be fetched, and used instead of (or combined with) git-archive checkout contents during further packaging; note all the DEPLOY_GIT_* arguments are still required if this feature is used.',
37+
name: 'DEPLOY_DIST_ARCHIVE')
3438
string (
3539
defaultValue: 'https://github.com/myorg/myjenkinsscripts.git',
3640
description: 'GIT Repo with CI scripts and tools',
@@ -127,12 +131,13 @@ pipeline {
127131
stage ('Deploy') {
128132
steps {
129133
script {
130-
manager.addShortText("Pushing: " + ( (params.DEPLOY_GIT_URL).substring( (params.DEPLOY_GIT_URL).lastIndexOf("/") + 1 ).replace(".git", "") ) + " / " + params.DEPLOY_GIT_BRANCH + " @ " + ( (params.DEPLOY_GIT_COMMIT).take(7) ) )
134+
manager.addShortText("Pushing: " + ( (params.DEPLOY_GIT_URL).substring( (params.DEPLOY_GIT_URL).lastIndexOf("/") + 1 ).replace(".git", "") ) + " / " + params.DEPLOY_GIT_BRANCH + " @ " + ( (params.DEPLOY_GIT_COMMIT).take(7) ) + ( (params.DEPLOY_DIST_ARCHIVE == "") ? "(no dist tarballs)" : (" using " + params.DEPLOY_DIST_ARCHIVE) ) )
131135
def statusCode = sh returnStatus:true, script: """
132136
DEPLOY_GIT_URL="${params["DEPLOY_GIT_URL"]}"
133137
DEPLOY_GIT_BRANCH="${params["DEPLOY_GIT_BRANCH"]}"
134138
DEPLOY_GIT_COMMIT="${params["DEPLOY_GIT_COMMIT"]}"
135-
export DEPLOY_GIT_URL DEPLOY_GIT_BRANCH DEPLOY_GIT_COMMIT
139+
DEPLOY_DIST_ARCHIVE="${params["DEPLOY_DIST_ARCHIVE"]}"
140+
export DEPLOY_GIT_URL DEPLOY_GIT_BRANCH DEPLOY_GIT_COMMIT DEPLOY_DIST_ARCHIVE
136141
cd project && \
137142
../ci/update-deployment.sh
138143
"""

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -405,6 +405,9 @@ zproject's `project.xml` contains an extensive description of the available conf
405405
which may be not installed on a particular deployment, so by
406406
default this option is disabled if not set explicitly. Same idea
407407
goes for build_docs as it requires asciidoc and xmlto toolkits.
408+
A further dist_docs enables preparation of a "dist" tarball from
409+
the workspace configured with docs, so you can forward it to the
410+
publishing helper job and avoid rebuilding manpages for packaging.
408411
409412
The triggers_pollSCM option sets up the pipeline-generated job
410413
for regular polling of the original SCM repository, using the
@@ -444,6 +447,7 @@ zproject's `project.xml` contains an extensive description of the available conf
444447
<option name = "build_without_draft_api" value = "0" />
445448
<option name = "build_with_draft_api" value = "0" />
446449
<option name = "build_docs" value = "1" />
450+
<option name = "dist_docs" value = "1" />
447451
<option name = "require_gitignore" value = "0" />
448452
<option name = "use_deleteDir_rm_first" value = "1" />
449453
<option name = "use_test_timeout" value = "30" />

‎project.xml

+4
Original file line numberDiff line numberDiff line change
@@ -230,6 +230,9 @@
230230
which may be not installed on a particular deployment, so by
231231
default this option is disabled if not set explicitly. Same idea
232232
goes for build_docs as it requires asciidoc and xmlto toolkits.
233+
A further dist_docs enables preparation of a "dist" tarball from
234+
the workspace configured with docs, so you can forward it to the
235+
publishing helper job and avoid rebuilding manpages for packaging.
233236
234237
The triggers_pollSCM option sets up the pipeline-generated job
235238
for regular polling of the original SCM repository, using the
@@ -269,6 +272,7 @@
269272
<option name = "build_without_draft_api" value = "0" />
270273
<option name = "build_with_draft_api" value = "0" />
271274
<option name = "build_docs" value = "1" />
275+
<option name = "dist_docs" value = "1" />
272276
<option name = "require_gitignore" value = "0" />
273277
<option name = "use_deleteDir_rm_first" value = "1" />
274278
<option name = "use_test_timeout" value = "30" />

‎zproject_jenkins.gsl

+21-2
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,15 @@ pipeline {
130130
description: 'Attempt a build with docs in this run? (Note: corresponding tools are required in the build environment)',
131131
name: 'DO_BUILD_DOCS')
132132
booleanParam (
133+
. if ( !(defined(project.jenkins_dist_docs)) | (project.jenkins_dist_docs ?= 0) )
134+
. # asciidoc and xmlto are external tools that may be not installed in general case
135+
defaultValue: false,
136+
. else
137+
defaultValue: true,
138+
. endif
139+
description: 'Publish as an archive a "dist" tarball from a build with docs in this run? (Note: corresponding tools are required in the build environment; enabling this enforces DO_BUILD_DOCS too)',
140+
name: 'DO_DIST_DOCS')
141+
booleanParam (
133142
. if project.jenkins_test_check ?= 0
134143
defaultValue: false,
135144
. else
@@ -295,7 +304,7 @@ pipeline {
295304
}
296305
}
297306
stage ('build with DOCS') {
298-
when { expression { return ( params.DO_BUILD_DOCS ) } }
307+
when { expression { return ( params.DO_BUILD_DOCS || params.DO_DIST_DOCS ) } }
299308
. jenkins_agent (project, 0)
300309
steps {
301310
. if !(isSingle_jenkins_agent (project, 0))
@@ -307,6 +316,13 @@ pipeline {
307316
. endif
308317
unstash 'prepped'
309318
sh 'CCACHE_BASEDIR="`pwd`" ; export CCACHE_BASEDIR; ./configure --enable-drafts=yes --with-docs=yes'
319+
script {
320+
if ( params.DO_DIST_DOCS ) {
321+
sh 'CCACHE_BASEDIR="`pwd`" ; export CCACHE_BASEDIR; make dist-gzip || exit ; DISTFILE="`ls -1tc *.tar.gz | head -1`" && [ -n "\$DISTFILE" ] && [ -s "\$DISTFILE" ] || exit ; mv -f "\$DISTFILE" __dist.tar.gz'
322+
archiveArtifacts artifacts: '__dist.tar.gz'
323+
sh "rm -f __dist.tar.gz"
324+
}
325+
}
310326
sh 'CCACHE_BASEDIR="`pwd`" ; export CCACHE_BASEDIR; make -k -j4 || make'
311327
sh 'echo "Are GitIgnores good after make with docs? (should have no output below)"; git status -s || if [ "${params.REQUIRE_GOOD_GITIGNORE}" = false ]; then echo "WARNING GitIgnore tests found newly changed or untracked files" >&2 ; exit 0 ; else echo "FAILED GitIgnore tests" >&2 ; exit 1; fi'
312328
stash (name: 'built-docs', includes: '**/*', excludes: '**/cppcheck.xml')
@@ -703,10 +719,13 @@ pipeline {
703719
if ( env.BRANCH_NAME =~ myDEPLOY_BRANCH_PATTERN ) {
704720
def GIT_URL = sh(returnStdout: true, script: """git remote -v | egrep '^origin' | awk '{print \\$2}' | head -1""").trim()
705721
def GIT_COMMIT = sh(returnStdout: true, script: 'git rev-parse --verify HEAD').trim()
722+
def DIST_ARCHIVE = ""
723+
if ( params.DO_DIST_DOCS ) { DIST_ARCHIVE = env.BUILD_URL + "artifact/__dist.tar.gz" }
706724
build job: "\$\{myDEPLOY_JOB_NAME}", parameters: [
707725
string(name: 'DEPLOY_GIT_URL', value: "\$\{GIT_URL}"),
708726
string(name: 'DEPLOY_GIT_BRANCH', value: env.BRANCH_NAME),
709-
string(name: 'DEPLOY_GIT_COMMIT', value: "\$\{GIT_COMMIT}")
727+
string(name: 'DEPLOY_GIT_COMMIT', value: "\$\{GIT_COMMIT}"),
728+
string(name: 'DEPLOY_DIST_ARCHIVE', value: "\$\{DIST_ARCHIVE}")
710729
], quietPeriod: 0, wait: myDEPLOY_REPORT_RESULT, propagate: myDEPLOY_REPORT_RESULT
711730
} else {
712731
echo "Not deploying because branch '\$\{env.BRANCH_NAME}' did not match filter '\$\{myDEPLOY_BRANCH_PATTERN}'"

0 commit comments

Comments
 (0)