Skip to content

Latest commit

 

History

History
204 lines (160 loc) · 11.9 KB

BUILD.md

File metadata and controls

204 lines (160 loc) · 11.9 KB
Raw

Maven build options

AspectJ is based on a multi-module Maven build with several options influencing

  • what to build,
  • whether to run tests,
  • whether to create documentation for the AspectJ website,
  • whether to create source and javadoc artifacts,
  • whether to GPG-sign artifacts for a release.

Typical build scenarios

As a developer, which modules or artifacts you want to build depends on your situation. For example:

  • When building a stable, non-snapshot release (milestone, release candidate, final), your goal is to publish a full set of artifacts on Maven Central (MC). Because MC requires you to publish javadocs and source code together with the corresponding binaries and to sign all artifacts with GPG, this is the most complex and complete, but also the slowest build you are about to encounter. Probably, you also want to build the AspectJ documentation to be deployed to the website.

  • When building a snapshot, the requirements are less strict, even if you are planning to make the release publicly available in the Sonatype OSSRH snapshots repository. In this case, you can skip creating javadocs and source JARs and also do not need to sign the artifacts. You might want to decide to sign anyway or at least to publish source JARs (which modern IDEs can also use in order to display javadoc information). So even if you are not working with an active Maven release profile, you want to have control over those options by setting properties. Probably, you do not wish to generate the AspectJ documentation for the website, because presently there is not even a dedicated place to deploy snapshot versions of it on the Eclipse webserver.

  • When building during development without the need to publish it, you probably want to skip as many non-essential parts of the build as possible. Firstly, you do not need them. Secondly, you want your build and run development cycles to be as quick as possible. So in this case, definitely you are going to skip javadoc and source JARs, website documentation and GPG signatures - unless you are in the process of changing and/or testing those parts of the build.

  • Independently of the above scenarios, you want to have control over whether to run (or even compile) any tests, and if so, which one(s).

How to customise the build process

You can customise the Maven build process by using build profiles and/or set corresponding system properties for fine-tuning.

Build profiles

Main profiles

The main profiles you are going to use are:

  • By default, when not specifying any profiles or properties, the build skips a few non-essential, time-consuming steps, but runs all tests: no javadocs, no source JARs, no GPG signatures, but generate documentation.

  • release - Run tests, create javadoc and source JARs, generate documentation, activate GPG artifact signing. Furthermore, each module creating one of the main build artifacts individually uses Nexus Staging Maven Plugin in order to take care of deploying non-snapshot artifacts to Sonatype OSSRH staging repositories and subsequently releasing them to Maven Central. See How to release AspectJ for more information. Snapshot artifacts are being deployed normally, using Maven Deploy Plugin. See description of property maven.deploy.skip below for more information.

  • fast-build - In a way, this is the opposite of the release profile, trying to build the product as quickly as possible by skipping all non-essential build steps: no tests (skipping even test compilation), no javadocs, no source JARs, no GPG signatures, no documentation.

  • create-docs - If you intend to run a build with all tests, but still wish to skip generating documentation, deactivate this profile by

    mvn -P !create-docs ...

    On UNIX-like shells like Bash (also Git Bash under Windows), you probably need to escape the "!":

    mvn -P \!create-docs ...

    You can also deactivate the profile using a system property instead:

    mvn -DcreateDocs=false ...

Special profiles for lib module

Defined in the lib module, there are two special profiles, helping to make the build more efficient:

  • provision-libs - Downloads and installs software used during tests, such as Apache Ant and several libraries. Some are downloaded from Maven Central, others directly from product download sites. Additionally, the build downloads several missing source packages, so developers can use them during development in order to access source code and javadoc. Because this build step is costly and should be performed only once after cloning the AspectJ repository or when other circumstances require re-provisioning at least one of those libraries, it is activated automatically, if marker file lib/provisioned.marker does not exist. After successful provisioning, the marker file is created, helping to avoid repeating this build step henceforth.

  • clean-libs - By default, mvn clean will not delete any of the libraries provisioned in profile provision-libs. This is intentional and one of the reasons why the libraries are not provisioned into the target directory but directly into lib subdirectories. If you wish to re-provision the libraries, simply run

    mvn -pl lib -P clean-libs clean

    Now you have a clean slate and during the next build, the libraries will be freshly downloaded and installed into their respective lib subdirectories.

Please note: An additional build step using Maven Enforcer Plugin also verifies the existence of several key files which ought to exist after a successful download. This heuristic check runs independently of the two build profiles mentioned above. It helps to detect accidental corruption of the provisioned libs, e.g., due to manual deletion or a previously failed provisioning build step (network problems, manually interrupted build).

Other profiles

Other existing profiles, which developers are less likely to actively use because they are applied automatically, are:

  • repeat-all-unit-tests - Maven module run-all-junit-tests has the sole purpose of providing a convenient means of running all tests across modules from an IDE instead of from Maven, in order to get JUnit build reporting directly there instead of on the console. As a developer, you simply run test suite RunTheseBeforeYouCommitTests. This profile is inactive by default, because in the context of a Maven build it would cause all tests to be run twice (during module build and again when running the big suite), hence the profile name.

  • jdk-8-to-15 - Activated automatically on JDKs 8-15, setting properties jvm.arg.addOpens and jvm.arg.allowSecurityManager to empty values, because they are only needed on JDK 16+ or 18+, respectively. See next bullet point.

  • jdk-16-to-xx - Activated automatically on JDKs 16+, setting property jvm.arg.addOpens to value --add-opens java.base/java.lang=ALL-UNNAMED, which is needed in order to run LTW tests.

  • jdk-18-to-xx - Activated automatically on JDKs 18+, setting property jvm.arg.allowSecurityManager to value -Djava.security.manager=allow, which is needed by some tests in order to override System.exit.

Build properties

The following properties and their default values in different profile are used in order to activate or skip Maven plugin executions:

  • maven.deploy.skip (default true) - By default, do not deploy artifacts, because only the main AspectJ artifacts are meant to be shared with the general public, i.e. deployed to Sonatype OSSRH Snapshots or Maven Central artifact repositories. The main AspectJ artifact modules override the default, setting the value to false. This property is used independently of build profiles, it simply has a global default and module-specific overrides.

  • maven.gpg.skip (default: true) - By default, do not GPG-sign artifacts, because only the main AspectJ artifacts need to be signed before publishing them on Maven Central. The main AspectJ artifact modules override the default, setting the value to false. This property is used independently of build profiles, it simply has a global default and module-specific overrides. Given the additional fact that Maven GPG Plugin is only active in the release profile, it also means that the build globally skips signing if that profile is inactive. So if you wish to sign snapshot artifacts, you need to activate the release profile (also activating all the other build steps that profile has).

  • maven.javadoc.skip (default: true) - By default, do not create javadoc. Overridden in the release profile. When javadoc generation is skipped while producing the uber JAR assemblies for the main AspectJ artifacts, also unzipping of source uber JARs is skipped, because that step is only needed in order to create uber JAR javadocs in the first place. (Do not worry too much, if you do not fully understand what I just wrote.)

  • maven.source.skip (default: true) - By default, do not create source JARs. Overridden in the release profile. Actually, this property is meant to be used in order to skip execution of Maven Source Plugin, but currently the AspectJ build does not even use that plugin, because the build does not create source JARs for individual modules. That might change in the future, though, so we use this property to also influence Maven Assembly Plugin, which is responsible for creating source uber JARs for the main AspectJ artifacts.

  • skipTests (default: false) - By default, execute tests. Profile fast-build overrides this property.

  • maven.test.skip (default: false) - By default, compile and execute tests. Profile fast-build overrides this property. Actually, activating this property also implies skipTests, but fast-build sets both of them in order to be explicit about its intentions.

  • createDocs (default: true) - By default, create user documentation for the AspectJ website. Profile fast-build overrides this property.

Examples

In addition to the examples above, concerning how to skip website documentation generation in the docs module and how to clean downloaded libraries in the lib module, here are a few more:

  • Run a clean default build including tests and generating Aspect documentation:

    mvn clean verify

    If you wish to install all artifacts in the local Maven repository, because subsquently maybe you want to run builds for submodules you are working on and which need to find other artifacts in the repository for a successful build, you rather use:

    mvn clean install

  • Run a fast build, no test compilation and execution, no AspectJ documentation, no javadoc, no source JARs

    mvn -P fast-build package

  • Run a release build incl. tests, GPG artifact signing and deployment:

    mvn -P release clean deploy

  • Run a release build incl. deployment, but without compiling and running tests because you ran all tests before successfully already:

    mvn -P release,fast-build clean deploy

    This is effectively the same as:

    mvn -P release -Dmaven.test.skip=true clean deploy

    In a UNIX shell, you probably have to double-quote when using properties containing dots:

    mvn -P release "-Dmaven.test.skip=true" clean deploy

In general, you should not combine profiles setting the same properties in contradictory ways. If you need a very specific build configuration, you might want to use a profile matching your needs most closely and override specific properties. However, I am not going to share examples for this approach, because generally it is not necessary and also both error-prone and sensitive to even small changes in Maven POMs.