diff options
| -rw-r--r-- | README.md | 7 | ||||
| -rw-r--r-- | ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java | 6 | ||||
| -rw-r--r-- | aspectjmatcher/pom.xml | 3 | ||||
| -rw-r--r-- | aspectjrt/pom.xml | 3 | ||||
| -rw-r--r-- | aspectjtools/pom.xml | 3 | ||||
| -rw-r--r-- | aspectjweaver/pom.xml | 3 | ||||
| -rw-r--r-- | docs/developer/BUILD.md | 200 | ||||
| -rw-r--r-- | docs/pom.xml | 5 | ||||
| -rw-r--r-- | installer/pom.xml | 2 | ||||
| -rw-r--r-- | pom.xml | 16 | ||||
| -rw-r--r-- | run-all-junit-tests/pom.xml | 3 | ||||
| -rw-r--r-- | runtime/pom.xml | 23 |
12 files changed, 241 insertions, 33 deletions
@@ -21,7 +21,11 @@ These are the artifacts published to Maven Central for each release. In addition In the root of a cloned AspectJ simply run: -`./mvnw clean install` +```shell +./mvnw clean install +``` + +You can also use a reasonably recent (3.6.3+), locally installed Maven installation instead of the Maven wrapper script. This will build all the modules, run all the tests and install the key artifacts in your local repository. Once built, access the Maven dependencies from your local repository or run the installer to install AspectJ locally: @@ -45,6 +49,7 @@ Ensure you run this with a JDK - the more recent the better since some tests wil * [How to contribute to AspectJ](CONTRIBUTING.md) * [How to release AspectJ](docs/developer/RELEASE.md) +* [Maven build options (profiles, properties)](docs/developer/BUILD.md) ## Maven releases diff --git a/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java b/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java index a32c1bd8a..763a5f5d2 100644 --- a/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java +++ b/ajdoc/src/main/java/org/aspectj/tools/ajdoc/Main.java @@ -265,8 +265,8 @@ public class Main implements Config { javadocargs[numExtraArgs + options.size() + packageList.size() + k] = fileList.elementAt(k); } if (LangUtil.is9VMOrGreater()) { - options = new Vector<>(); - Collections.addAll(options, javadocargs); + options = new Vector<>(); + Collections.addAll(options, javadocargs); } } else { javadocargs = new String[options.size() + signatureFiles.length]; @@ -281,7 +281,7 @@ public class Main implements Config { } } if (LangUtil.is9VMOrGreater()) { - JavadocRunner.callJavadocViaToolProvider(options, files); + JavadocRunner.callJavadocViaToolProvider(options, files); } else { JavadocRunner.callJavadoc(javadocargs); } diff --git a/aspectjmatcher/pom.xml b/aspectjmatcher/pom.xml index 94a43ac1a..64cf71eaa 100644 --- a/aspectjmatcher/pom.xml +++ b/aspectjmatcher/pom.xml @@ -49,6 +49,8 @@ <properties> <!-- By default, do not deploy artifacts - but deploy this public one --> <maven.deploy.skip>false</maven.deploy.skip> + <!-- By default, do not sign artifacts - but sign this public one --> + <maven.gpg.skip>false</maven.gpg.skip> </properties> <build> @@ -146,6 +148,7 @@ <configuration> <!-- The assembly ID 'sources' becomes the artifact classifier, exactly what we want --> <appendAssemblyId>true</appendAssemblyId> + <skipAssembly>${maven.source.skip}</skipAssembly> <archive> </archive> <descriptors> diff --git a/aspectjrt/pom.xml b/aspectjrt/pom.xml index b4e73c1fa..3937407f4 100644 --- a/aspectjrt/pom.xml +++ b/aspectjrt/pom.xml @@ -48,6 +48,8 @@ <properties> <!-- By default, do not deploy artifacts - but deploy this public one --> <maven.deploy.skip>false</maven.deploy.skip> + <!-- By default, do not sign artifacts - but sign this public one --> + <maven.gpg.skip>false</maven.gpg.skip> </properties> <build> @@ -139,6 +141,7 @@ <configuration> <!-- The assembly ID 'sources' becomes the artifact classifier, exactly what we want --> <appendAssemblyId>true</appendAssemblyId> + <skipAssembly>${maven.source.skip}</skipAssembly> <archive> </archive> <descriptors> diff --git a/aspectjtools/pom.xml b/aspectjtools/pom.xml index 869e1882b..2c2cdd80f 100644 --- a/aspectjtools/pom.xml +++ b/aspectjtools/pom.xml @@ -50,6 +50,8 @@ <properties> <!-- By default, do not deploy artifacts - but deploy this public one --> <maven.deploy.skip>false</maven.deploy.skip> + <!-- By default, do not sign artifacts - but sign this public one --> + <maven.gpg.skip>false</maven.gpg.skip> </properties> <build> @@ -164,6 +166,7 @@ <configuration> <!-- The assembly ID 'sources' becomes the artifact classifier, exactly what we want --> <appendAssemblyId>true</appendAssemblyId> + <skipAssembly>${maven.source.skip}</skipAssembly> <archive> </archive> <descriptors> diff --git a/aspectjweaver/pom.xml b/aspectjweaver/pom.xml index 73abc26f1..c5f1fda1e 100644 --- a/aspectjweaver/pom.xml +++ b/aspectjweaver/pom.xml @@ -48,6 +48,8 @@ <properties> <!-- By default, do not deploy artifacts - but deploy this public one --> <maven.deploy.skip>false</maven.deploy.skip> + <!-- By default, do not sign artifacts - but sign this public one --> + <maven.gpg.skip>false</maven.gpg.skip> </properties> <build> @@ -165,6 +167,7 @@ <configuration> <!-- The assembly ID 'sources' becomes the artifact classifier, exactly what we want --> <appendAssemblyId>true</appendAssemblyId> + <skipAssembly>${maven.source.skip}</skipAssembly> <archive> </archive> <descriptors> diff --git a/docs/developer/BUILD.md b/docs/developer/BUILD.md new file mode 100644 index 000000000..119b33832 --- /dev/null +++ b/docs/developer/BUILD.md @@ -0,0 +1,200 @@ +# 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 created 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](RELEASE.md) for more information. Snapshot artifacts + are being deployed normally, using Maven Deploy Plugin. See description of + [property `maven.deploy.skip`](#build-properties) 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 + ```shell + mvn -P !create-docs ... + ``` + On UNIX-like shells like Bash (also Git Bash under Windows), you probably need to escape the "!": + ```shell + mvn -P \!create-docs ... + ``` + You can also deactivate the profile using a system property instead: + ```shell + 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 + ```shell + 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 property `jvm.arg.addOpens` to an empty value, because + it is only needed on JDK 16+, 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. + +### 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: + ```shell + 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: + ```shell + mvn clean install + ``` + + * Run a fast build, no test compilation and execution, no AspectJ documentation, no javadoc, no source JARs + ```shell + mvn -P fast-build package + ``` + + * Run a release build incl. tests, GPG artifact signing and deployment: + ```shell + 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: + ```shell + mvn -P release,fast-build clean deploy + ``` + This is effectively the same as: + ```shell + mvn -P release -Dmaven.test.skip=true clean deploy + ``` + In a UNIX shell, you probably have to double-quote when using properties containing dots: + ```shell + 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 evan small changes in Maven POMs. diff --git a/docs/pom.xml b/docs/pom.xml index f2caccaf8..57baa3603 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -14,7 +14,10 @@ <profile> <id>create-docs</id> <activation> - <activeByDefault>true</activeByDefault> + <property> + <name>createDocs</name> + <value>true</value> + </property> </activation> <build> diff --git a/installer/pom.xml b/installer/pom.xml index 082c27640..74f83354b 100644 --- a/installer/pom.xml +++ b/installer/pom.xml @@ -54,6 +54,8 @@ --> <!-- By default, do not deploy artifacts - but deploy this public one --> <!--<maven.deploy.skip>false</maven.deploy.skip>--> + <!-- By default, do not sign artifacts - but sign this public one --> + <!--<maven.gpg.skip>false</maven.gpg.skip>--> </properties> <dependencies> @@ -182,8 +182,8 @@ <profile> <id>release</id> <properties> - <!-- By default, do not create javadoc - override in release profile --> <maven.javadoc.skip>false</maven.javadoc.skip> + <maven.source.skip>false</maven.source.skip> </properties> <build> <plugins> @@ -194,6 +194,17 @@ </plugins> </build> </profile> + <profile> + <id>fast-build</id> + <properties> + <!-- Do not compile tests (also skips execution) --> + <maven.test.skip>true</maven.test.skip> + <!-- Do not execute tests (redundant, but just to be sure) --> + <skipTests>true</skipTests> + <!-- Do not create documentation for AspectJ website --> + <createDocs>false</createDocs> + </properties> + </profile> </profiles> <build> @@ -322,7 +333,7 @@ </goals> <configuration> <!-- Only sign artifacts which are also meant to be deployed --> - <skip>${maven.deploy.skip}</skip> + <skip>${maven.gpg.skip}</skip> </configuration> </execution> </executions> @@ -358,6 +369,7 @@ <configuration> <serverId>ossrh</serverId> <nexusUrl>https://oss.sonatype.org/</nexusUrl> + <!-- Activate in order to directly release to Maven Central after successful staging --> <autoReleaseAfterClose>false</autoReleaseAfterClose> </configuration> </plugin> diff --git a/run-all-junit-tests/pom.xml b/run-all-junit-tests/pom.xml index ff35e03af..5d3d12e93 100644 --- a/run-all-junit-tests/pom.xml +++ b/run-all-junit-tests/pom.xml @@ -191,9 +191,6 @@ have to use Maven and get the test results reported within the IDE's JUnit user interface. --> <id>repeat-all-unit-tests</id> - <activation> - <activeByDefault>false</activeByDefault> - </activation> <build> <plugins> <plugin> diff --git a/runtime/pom.xml b/runtime/pom.xml index ceb3c8462..8ad73f457 100644 --- a/runtime/pom.xml +++ b/runtime/pom.xml @@ -11,27 +11,4 @@ <artifactId>runtime</artifactId> - <build> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-javadoc-plugin</artifactId> - <configuration> - </configuration> - <executions> - <execution> - <id>javadoc</id> - <phase>package</phase> - <goals> - <goal>javadoc</goal> - </goals> - <configuration> - <source>8</source> - </configuration> - </execution> - </executions> - </plugin> - </plugins> - </build> - </project> |