This document covers cover how to perform various repeatable tasks in the repository that might not otherwise be obvious from just looking at the repository.
I wrote this diagram partially for my own benefit in issue 957 that lists the 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.
Note that the "end-user" scripts start at makejdk-any-platform.sh and a
diagram of those relationships can be seen here
See the ci-jenkins-pipelines FAQ.md for the Jenkins side of the pipeline
G - 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}There is also some documentation in CHANGELOG.md
- The upstream OpenJDK build requirements are at Supported Build Platforms
- The Temurin levels we build on are in Minimum-OS-levels although anything with comparable equivalent or later C libraries should work OK (in particular we have built on most current Linux distros without issues)
In terms of compilers, these are what we currently use for each release:
| Version | OS | Compiler |
|---|---|---|
| JDK8/11 | Linux | GCC 7.5 |
| JDK17/18 | Linux | GCC 10.3 |
| JDK19+ | Linux | GCC 11.2 |
| All | Alpine | GCC 10.3.1 |
| JDK8 | Solaris | Sun Studio 12.3 |
| JDK8 | Windows | VS2017 (19) (Win64) or VS2013 (12) (Win32 and J9) |
| JDK11+ | Windows | VS2019 (10) (Win64) or VS2017 (19) (Win32) |
| JDK8 | AIX | xlC/C++ 13.1.3 |
| JDK11+ | AIX | xlC/C++ 16.1.0 |
| JDK8 | macOS | GCC 4.2.1 (LLVM 2336.11.00 |
| JDK11 | macOS | clang-700.1.81 |
| JDK13+ | macOS | clang-900.0.39.2 |
All machines at Temurin are set up using the ansible playbooks from the infrastructure repository.
Where you change them depends on the scope of the parameter or flag:
- If the parameter will affect all users, regardless of environment or OS/Arch
- build.sh OR makejdk-any-platform.sh depending on how high up in the execution stack it needs to be.
- Example PR - Adding a new archival feature for OpenJ9 memory dumps
- If the parameter will affect all machines of a specific OS OR related to the environment set up by our ansible scripts at the shell script level
- Modify the relevant environment files in platform-specific-configurations
- Example PR - Adding a new configure flag for OpenJ9 on all AIX machines
- If the parameter will affect only our jenkins environment or jenkins machine environment
- Modify the pipeline files, although this is normally only done for configuration differences such as OpenJ9 Large Heap builds. See the configuration file documentation for more information about adding or altering custom jenkins param.
- Example PR - Adding Jenkins Support for a Cross Compiled Bisheng Binary
| Parameter Location | Impact |
|---|---|
| build.sh OR makejdk-any-platform.sh | Anyone (including end users) who are running makejdk-any-platform.sh |
| platform-specific-configurations scripts | Those using build-farm/make-adopt-build-farm.sh (inc. our pipelines) - should be stuff specific to our machines |
| Jenkins resources in ci-jenkins-pipelines | Only when run through our jenkins pipelines. See the configuration file documentation for more information |
Since it's quite long, this is covered in a separate RELEASING.md document
If you're making changes ensure you follow the contribution guidelines in CONTRIBUTING.md including running shellcheck if you're modifying the shell scripts.
For more information, see the PR testing documentation.
Smoke tests are quick and simple tests to verify that we 'built the right thing'. They can be found in the buildAndPackage directory Smoke tests verify things like:
- the java -version output is correct
- certain features are available in certain builds (checks for shenandoah GC or xxx)
- the right set of modules are included etc
They use the same mechanisms and automation used by the AQA test suite. This means they can be run on the commandline, or as part of a Jenkins job or in a GitHub workflow. For this repository, they are part of PR testing via the build.yml workflow using the run-aqa action.
They are also run as part of the Jenkins build pipelines (see the runSmokeTests() method in the openjdk_build_pipeline groovy script), triggered after the build is complete and before any AQA tests get run against the build. If smoke tests fail, it likely indicates we built the 'wrong thing' and there is no point running further testing until we resolve the build issues.
To run them on the command-line, one can follow the same general instructions for running any AQA test on the command line, with the additional step of exporting variables to indicate where to find test material (VENDOR_TEST_REPOS, VENDOR_TEST_BRANCHES, VENDOR_TEST_DIRS). See: SmokeTesting.md
The operating systems/distributions which we build or are documented in the temurin-build wiki. Runtime platforms are in our supported platforms page.
This PR demonstrates changes required to add a new build pipeline param and the associated version/platform job configurations for setting the value when needed (note, the pipelines/ dir has since been moved to our jenkins repository).