From 56262484841c048e2127151c46f5863eea321862 Mon Sep 17 00:00:00 2001 From: "Lott, Christopher (cl778h)" Date: Mon, 23 Dec 2019 15:32:48 -0500 Subject: [PATCH] Generate javadoc from a project in a subdirectory Lift the assumption that all files are in the git repository root. Extend maven-javadoc publish and javadoc-verify macros with mvn-dir configuration parameter (like tox-dir), defaults to '.' to preserve existing behavior. Extend maven-javadoc-generate.sh script to invoke mvn with the -f option and use the directory name when archiving the generated HTML; drop -x setting to conform with other scripts. Document the new configuration parameter. Projects using macros lf-maven-javadoc-publish, lf-maven-javadoc-verify (i.e., using job templates gerrit-maven-javadoc-publish, github-maven-javadoc-publish, gerrit-maven-javadoc-verify or github-maven-javadoc-verify) must ensure the maven -f option is not used in config parameter mvn-params. Change-Id: Ib02a12a3192b8be577a0367476628c46db333231 Issue-ID: RELENG-1872 Signed-off-by: Lott, Christopher (cl778h) --- docs/jjb/lf-maven-jobs.rst | 28 ++++++++++++++-------- jjb/lf-maven-jobs.yaml | 9 ++++++- .../extend-javadoc-mvn-dir-7324879c369a9d8b.yaml | 17 +++++++++++++ shell/maven-javadoc-generate.sh | 7 +++--- 4 files changed, 47 insertions(+), 14 deletions(-) create mode 100644 releasenotes/notes/extend-javadoc-mvn-dir-7324879c369a9d8b.yaml diff --git a/docs/jjb/lf-maven-jobs.rst b/docs/jjb/lf-maven-jobs.rst index bdee524a..3c45aaf6 100644 --- a/docs/jjb/lf-maven-jobs.rst +++ b/docs/jjb/lf-maven-jobs.rst @@ -140,7 +140,7 @@ Produces a CLM scan of the code into Nexus IQ Server. Maven configuration. (default: global-settings) :mvn-goals: The maven goals to perform for the build. (default: clean install) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') :mvn-version: Version of maven to use. (default: mvn35) :nexus-iq-namespace: Insert a namespace to project AppID for projects that @@ -165,7 +165,9 @@ Maven JavaDoc Publish Produces and publishes javadocs for a Maven project. -Expects javadocs to be available in $WORKSPACE/target/site/apidocs +Expects javadocs to be available in $WORKSPACE/target/site/apidocs, unless +the mvn-dir parameter is supplied, in which case expects javadocs to be +available in $WORKSPACE/{mvn-dir}/target/site/apidocs. :Template Names: @@ -192,10 +194,12 @@ Expects javadocs to be available in $WORKSPACE/target/site/apidocs :build-timeout: Timeout in minutes before aborting build. (default: 60) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) :java-version: Version of Java to use for the build. (default: openjdk8) + :mvn-dir: Directory supplied as argument to -f option (default: '.') :mvn-global-settings: The name of the Maven global settings to use for Maven configuration. (default: global-settings) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') + Must not include a "-f" option; see parameter mvn-dir. :mvn-version: Version of maven to use. (default: mvn35) :stream: Keyword that can be used to represent a release code-name. Often the same as the branch. (default: master) @@ -213,7 +217,9 @@ Maven JavaDoc Verify Produces javadocs for a Maven project. -Expects javadocs to be available in $WORKSPACE/target/site/apidocs +Expects javadocs to be available in $WORKSPACE/target/site/apidocs, unless +the mvn-dir parameter is supplied, in which case expects javadocs to be +available in $WORKSPACE/{mvn-dir}/target/site/apidocs. :Template Names: @@ -237,10 +243,12 @@ Expects javadocs to be available in $WORKSPACE/target/site/apidocs :deploy-path: The path in Nexus to deploy javadoc to. (default: $PROJECT/$STREAM) :git-url: URL clone project from. (default: $GIT_URL/$PROJECT) :java-version: Version of Java to use for the build. (default: openjdk8) + :mvn-dir: Directory supplied as argument to -f option (default: '.') :mvn-global-settings: The name of the Maven global settings to use for Maven configuration. (default: global-settings) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') + Must not include a "-f" option; see parameter mvn-dir. :mvn-version: Version of maven to use. (default: mvn35) :stream: Keyword that can be used to represent a release code-name. Often the same as the branch. (default: master) @@ -302,7 +310,7 @@ This job uses the following strategy to deploy jobs to Nexus: :java-version: Version of Java to use for the build. (default: openjdk8) :mvn-global-settings: The name of the Maven global settings to use for Maven configuration. (default: global-settings) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') :mvn-version: Version of maven to use. (default: mvn35) :nexus-cut-dirs: Number of directories to cut from file path for `wget -r`. @@ -393,7 +401,7 @@ directory is then used later to deploy to Nexus. :maven-versions-plugin: Whether to call Maven versions plugin or not. (default: false) :mvn-global-settings: The name of the Maven global settings to use for Maven configuration. (default: global-settings) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') :mvn-version: Version of maven to use. (default: mvn35) :ossrh-profile-id: Profile ID for project as provided by OSSRH. @@ -488,7 +496,7 @@ interest in that kind of support. Maven configuration. (default: global-settings) :mvn-goals: The maven goals to perform for the build. (default: clean install) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') :mvn-version: Version of maven to use. (default: mvn35) :sonar-mvn-goals: Maven goals to run for sonar analysis. @@ -545,7 +553,7 @@ Verify job which runs mvn clean install to test a project build.. :java-version: Version of Java to use for the build. (default: openjdk8) :mvn-global-settings: The name of the Maven global settings to use for Maven configuration. (default: global-settings) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') :mvn-version: Version of maven to use. (default: mvn35) :stream: Keyword that can be used to represent a release code-name. @@ -614,7 +622,7 @@ via comment trigger. :java-version: Version of Java to use for the build. (default: openjdk8) :mvn-global-settings: The name of the Maven global settings to use for Maven configuration. (default: global-settings) - :mvn-opts: Sets MAVEN_OPTS. (default: '') + :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '') :mvn-params: Additional mvn parameters to pass to the cli. (default: '') :mvn-version: Version of maven to use. (default: mvn35) :stream: Keyword that can be used to represent a release code-name. diff --git a/jjb/lf-maven-jobs.yaml b/jjb/lf-maven-jobs.yaml index a01af957..77f34de6 100644 --- a/jjb/lf-maven-jobs.yaml +++ b/jjb/lf-maven-jobs.yaml @@ -311,6 +311,7 @@ git-url: "$GIT_URL/$PROJECT" github-url: "https://github.com" java-version: openjdk8 + mvn-dir: "." mvn-global-settings: global-settings mvn-opts: "" mvn-params: "" @@ -343,7 +344,9 @@ - lf-infra-create-netrc: server-id: "{mvn-site-id}" - inject: - properties-content: "DEPLOY_PATH={javadoc-path}" + properties-content: | + DEPLOY_PATH={javadoc-path} + MAVEN_DIR={mvn-dir} - shell: !include-raw-escape: - ../shell/common-variables.sh - ../shell/maven-javadoc-generate.sh @@ -440,6 +443,7 @@ git-url: "$GIT_URL/$PROJECT" github-url: "https://github.com" java-version: openjdk8 + mvn-dir: "." mvn-global-settings: global-settings mvn-opts: "" mvn-params: "" @@ -474,6 +478,9 @@ - lf-provide-maven-settings: global-settings-file: "{mvn-global-settings}" settings-file: "{mvn-settings}" + - inject: + properties-content: | + MAVEN_DIR={mvn-dir} - shell: !include-raw-escape: - ../shell/common-variables.sh - ../shell/maven-javadoc-generate.sh diff --git a/releasenotes/notes/extend-javadoc-mvn-dir-7324879c369a9d8b.yaml b/releasenotes/notes/extend-javadoc-mvn-dir-7324879c369a9d8b.yaml new file mode 100644 index 00000000..af276d14 --- /dev/null +++ b/releasenotes/notes/extend-javadoc-mvn-dir-7324879c369a9d8b.yaml @@ -0,0 +1,17 @@ +--- +upgrade: + - | + Projects using macros lf-maven-javadoc-publish or lf-maven-javadoc-verify + (i.e., using job templates gerrit-maven-javadoc-publish, github-maven-javadoc-publish, + gerrit-maven-javadoc-verify or github-maven-javadoc-verify) must ensure the + maven -f option is not used in config parameter mvn-params. +features: + - | + Generate javadoc from a project in a subdirectory, which lifts the + assumption that all files are in the git repository root. + Extend maven-javadoc publish and javadoc-verify templates with mvn-dir + configuration parameter (like tox-dir), defaults to '.' to keep existing + behavior. + Extend maven-javadoc-generate.sh script to invoke mvn with the -f option + and use the directory name when archiving the generated HTML. + Document the new configuration parameter. diff --git a/shell/maven-javadoc-generate.sh b/shell/maven-javadoc-generate.sh index ec4743a7..299559d8 100644 --- a/shell/maven-javadoc-generate.sh +++ b/shell/maven-javadoc-generate.sh @@ -11,9 +11,9 @@ echo "---> maven-javadoc-generate.sh" # Generates javadoc in a Maven project. -# DO NOT enable -u because $MAVEN_PARAMS and $MAVEN_OPTIONS could be unbound. # Ensure we fail the job if any steps fail. -set -xe -o pipefail +# DO NOT enable -u because $MAVEN_PARAMS and $MAVEN_OPTIONS could be unbound. +set -e -o pipefail set +u JAVADOC_DIR="$WORKSPACE/archives/javadoc" @@ -30,9 +30,10 @@ $MVN clean install javadoc:aggregate \ -Dfindbugs.skip=true \ --global-settings "$GLOBAL_SETTINGS_FILE" \ --settings "$SETTINGS_FILE" \ + -f "$MAVEN_DIR" \ $MAVEN_OPTIONS $MAVEN_PARAMS -mv "$WORKSPACE/target/site/apidocs" "$JAVADOC_DIR" +mv "$WORKSPACE/$MAVEN_DIR/target/site/apidocs" "$JAVADOC_DIR" # TODO: Nexus unpack plugin throws a "504 gateway timeout" for jobs archiving # large number of small files. Remove the workaround only we move away from -- 2.16.6