Improve overview page to ease new starters to the build scripts

[sxa]

We currently have https://github.com/AdoptOpenJDK/openjdk-build and https://github.com/AdoptOpenJDK/openjdk-build/blob/master/docs/build.md but in terms of seeing where everything is and how it fits together it's not entirely clear what the overall pipeline is, or at which level you would make any given change.

I've got this diagram mostly for my own benefit that lists the Jenkins jobs (J), groovy scripts from github (G), shell scripts (S) and environment scripts (E). I think it would be useful to incorporate this into the documentation (potentially annotated with a bit more info) so people can find their way around the myriad of script levels that we now have.

J - build-scripts/job/utils/job/build-pipeline-generator
G   - Create openjdk*-pipeline jobs from pipelines/jobs/popeline_job_template.groovy
J   - openjdk11-pipeline
G     - pipelines/build/openjdk*_pipeline.groovy
G       - pipelines/build/common/build_base_file.groovy
G         - create_job_from_template.groovy (Generates e.g. jdk11u-linux-x64-hotspot)
G       - configureBuild()
G         - .doBuild() (common/build_base_file.groovy)
J           - context.build job: downstreamJobName (e.g. jdk11u/job/jdk11u-linux-x64-hotspot)
J             (Provides JAVA_TO_BUILD, ARCHITECTURE, VARIANT, TARGET_OS + tests)
G             - openjdk_build_pipeline.groovy
G               - context.sh make-adopt-build-farm.sh
S                 - set-platform-specific-configurations.sh
E                    - sbin/common/constants.sh (DUPLICATED LATER FROM configureBuild.sh)
E                    - platform-specific-configurations/${OPERATING_SYSTEM}.sh
S                 - makejdk-any-platform.sh
E                   - ${SCRIPT_DIR}/sbin/common/config_init.sh (Parse options)
E                   - ${SCRIPT_DIR}/docker-build.sh (Runs build.sh within container)
E                   - ${SCRIPT_DIR}/native-build.sh (Runs build.sh natively)
E                   - ${SCRIPT_DIR}/configureBuild.sh
E                     - ${SCRIPT_DIR}/sbin/common/constants.sh
E                     - ${SCRIPT_DIR}/sbin/common/common.sh
E                     - ${SCRIPT_DIR}/signalhandler.sh (rm container on SIGINT/SIGTERM)
S                   - {buildOpenJDKViaDocker|buildOpenJDKInNativeEnvironment}

[sxa]

A reasonable use case would appear to be "I want to set up a machine with ansible and build with your scripts".

Currently the main documentation we provide is for makejdk-any-platform.sh which does not invoke the environment scripts that we have assembled. A suitable set of instructions would be along the lines of telling people to set these variables and run the script.:

export TARGET_OS=linux
export ARCHITECTURE=s390x
export JAVA_TO_BUILD=jdk8u
export VARIANT=openj9
export JDK7_BOOT_DIR=/usr/lib/jvm/java-1.7.0
build-farm/make-adopt-build-farm.sh

I wonder if we can streamlines the detection of some of these ... makejdk-any-platform.sh does the detection whereas make-adopt-build-farm.sh sets the environment variables to match the playbook - we don't have one script that does both

[sxa]

Related:

• Tidy up the wiki
• Comments for bulid scripts (PR)
• Documentation for github checks
• PR tester documentation
• Where should config parameters be defined
• Overhaul makejdk-any-patform.sh documentation
• CONFIGURE_ARGS confusion