Document build profiles and properties in docs/developer/BUILD.md
In doing so, I also noticed a few things in need of improvement. So,
documenting the build also drive those enhancements, such as
- the new 'fast-build' profile skipping test compilation and execution
as well as documentation generation,
- an option to skip generating source assemblies,
- to skip unzipping source assemblies if javadoc generation for them
is to be skipped too,
- activating the 'create-docs' profile by property which is
true by default instead of using 'activeByDefault=true', because the
latter does not work reliably if other profiles are activated
manually according to a Maven bug that was closed as "won't fix",
- no longer generating separate javadocs for the 'runtime' module,
because that module is not deployed and the main artifacts recreate
Javadocs from scratch for all of their constituent sources anyway.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
This is a bugfix release, reverting the essential parts of commit
f70aeb5e, because it causes AspectJ Maven integration tests using
javadoc to fail on JDK 8.
See commit discussion on
https://github.com/eclipse/org.aspectj/commit/f70aeb5e#commitcomment-51417353
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Upgrade Maven Shade Plugin to 3.2.4.MSHADE-252-391
Unfortunately, the issues fixed in the aspectj.dev fork are still not
available upstream (MSHADE-252 is merged, but unreleased, MSHADE-391 is
in review).
Also use Maven Javadoc Plugin version from parent POM.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Before, we used 1.9.7.BUILD-SNAPSHOT, which according to Andy Clement
was originally an intent across a group of Spring projects he was
involved in, to ensure that SNAPSHOTS were sorted alphabetically ahead
of MILESTONEs and ahead of RCs.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Other than Maven Deploy, Nexus Staging plugin cannot just be added to
the 'build/plugins' section of the parent POM once and (de-)activated
with a simple property like 'maven.deploy.skip' on a per-module basis.
See also https://issues.sonatype.org/browse/OSSRH-68966. Consequently,
we do not add it to the parent but separately to each module meant to be
published.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Even with the 'release' profile, it is not necessary to sign each
artifact, because only the ones to be published on Maven Central need
signatures.
Similarly, make Nexus staging deployment to Sonatype OSSRH dependent on
'maven.deploy.skip' and skip staging for non-public artifacts.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Create javadoc for all public artifacts, fix dependencies
Sonatype OSSRH repository rules require source and javadoc JARs in
order to create staging repositories for releases to be promoted to
Maven Central. So I added build steps to unzip the source JARs and then
create Javadocs for them.
FIXME: This configuration works with JDK 16, but throws errors on other
JDK versions, e.g. 14. It looks as if the Maven Javadoc plugin does not
do a particularly good job applying the plugin settings in a way making
it work with different JDK javadoc tool versions. I am saying that,
because when using the tool directly on the console, it works with basic
settings and the correct classpath.
In order to enable creating uber JARs via Maven Shade in the future, I
also added missing dependencies. Maven Assembly descriptors just assume
that all the necessary class files and sources already exist where it
copies them from. But several of the dependency modules were not
explicitly listed as such by the uber JAR modules. I fixed that.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Prepare main artifacts to be deployed via Maven, step 2
This change affects the following modules:
- aspectjmatcher
- aspectjrt
- aspectjtools
- aspectjweaver
- installer
- asm-renamed
Set maven.deploy.skip=false in parent POM, i.e. Maven Deploy by default
will *not deploy anything. Only in the modules above, we change the
value to 'true' in order to deploy those artifacts.
This setting works for both snapshot repositories (GitHub Packages, soon
to be migrated to aspectj.dev in a separate PR) and release
repositories, i.e. in the future also for Maven Central.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Upon special request by Andy Clement, I included 'lib' as a child module
in the parent POM again, making several modules which refer to
downloaded library files dependent the 'lib' module. I am not sure I
caught all of them, but I hope so.
Now after cloning the project and configuring the token for reading from
GitHub Packages (sorry!), you can just run a Maven build for the main
project and no longer need to fail the first build, read the Maven
Enforcer message and run 'cd lib && mvn compile' as a first step. This
convenience comes at the price of a more complex POM and two new
profiles:
- Profile 'provision-libs' is auto-activated by the absence of a
marker file, kicking off the library provisioning process and
creating same marker file at the end, if successful. Therefore,
during subsequent builds libraries will not be re-provisioned,
because the marker file exists and Maven skips all download and
(un)zip steps, which saves build time and bandwidth. Otherwise
offline builds would not work either.
- Profile 'clean-libs' needs to be activated manually, because by
default 'mvn clean' will not erase provisioned libraries. In most
cases, even after a clean a developer does not want to re-provision
all libraries if they have not changed (e.g. new JDT Core build).
But if you do wish too erase the libraries and the marker file, just
call 'cd lib && mvn -P clean-libs clean'.
Please note: The Maven Enforcer build step, which additionally checks
for existence of other files, still exists and was moved from the parent
POM to 'libs'. No matter if provisioning was just done or skipped
because the main marker file exists, a quick heuristic check for that
list of files is done during each build, failing the build with a
comprehensive message if an inconsistency was found. The error message
says which files are missing and tells the user:
"There is an inconsistency in module subdirectory 'lib'. Please run
'mvn --projects lib -P clean-libs clean compile'. This should take
care of cleaning and freshly downloading all necessary libraries to
that directory, where some tests expect them to be."
This should cover the topic.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Prepare main artifacts to be deployed via Maven, step 1
This change affects the following modules:
- aspectjmatcher
- aspectjrt
- aspectjtools
- aspectjweaver
- installer
They have in common that they all use Maven Assembly Plugin in order to
create some kind of uber JARs with constituent modules and/or libraries.
Except for the installer, they are all available on Maven Central today,
but I think it would not hurt to deploy the installer to there, too.
Changes made:
- Use Flatten Maven Plugin in order to create simple POMs with only
basic information and - most importantly - without dependencies.
- The new dependency-reduced POM (DRP) or "flattened POM" gets
attached to the build, i.e. it will be installed and deployed as a
replacement of the original POM.
- Attaching the DRP only works for 'jar' type modules, which is why I
changed the packaging type for each module from 'pom' to 'jar'.
- Deactivate generation of the default JAR for each module. This is
necessary now, since we have the 'jar' packaging type.
- Make sure that assembly descriptors using 'dependencySet' entries
have set option 'useProjectArtifact=false' in order to avoid
warnings about the non-existing main artifact.
TODO:
- Explore option to migrate from Maven Assembly to Maven Shade,
because it does not need descriptor files, can also generate source
JARs and can automatically create and attach a DRP which is less
fragmentary than the one created by Flatten Maven, basically the
original JAR minus the dependencies.
- If in the future we want to make sure to only deploy the modules
listed above, e.g. to Maven Central, if simply calling 'mvn deploy'
for the whole project, we could use 'maven.deploy.skip=true' in the
parent POM and override it by 'maven.deploy.skip=false' just in the
few modules which need to be deployed. See also:
https://stackoverflow.com/a/29574812/1082681
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
The new string AjcTestCase.CLASSPATH_ASM_RENAMED dynamically determines
the 'asm-renamed' location from the classpath, system property
'java.class.path'.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
We are not using Jupiter yet, but this is nice to have for the future.
Thanks to @larsgrefer for his initiative to prepare AspectJ for
JUnit Jupiter and for his other PR which also contains the same change
in the parent POM. :-)
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Fix undetected runtime dependency usage problem from previous commit
In module 'ajdoc', our tests need tools.jar when running on JDK 8 in
order to dynamically compile during runtime. Hence, dependency
com.github.olivergondza:maven-jdk-tools-wrapper was re-added to the POM
(with test scope this time) and Maven Dependency plugin configured to
regard it as a used dependency and not falsely report it as unused.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Clean up Maven dependencies using 'dependency:analyze' goal
Notably, this change involves a partial revert of @4a5660b3, because we
are not using JUnit Jupiter yet but still JUnit 4 tests. See discussion
under commit at https://github.com/eclipse/org.aspectj/commit/4a5660b3.
Many other warnings - concerning both used undeclared and unused
declared dependencies - were eliminated by adding or removing the
corresponding dependencies from the POMs. Furthermore, I tried to make
sure that some clearly test-scoped dependencies are now actually
declared as such, so as to avoid unwanted transitivity bleeding into
compile scope and maybe unwanted classes ending up in uber JARs via
Maven Shade or Maven Assembly.
TODO: I am not so sure why modules other than 'run-all-unit-tests' would
depend on test JARs. I hope I broke nothing essential there. As of
today, the other modules where I found '<type>test-jar</type>'
dependencies are:
- ajde
- testing
- testing-drivers
- tests
- weaver
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Delete all remaining docbook contents, download them instead
Actually, only fop:fop:0.20.5 and batik:batik-1.5-fop:0.20-5 are really
used in addition to lib/saxon/saxon.jar (saxon:saxon:6.5.3). So the rest
does not need to be replaced and can just be wiped.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Delete docbook XSL + DTD directories from libs, download instead
It was kind of difficult to identify and find the vintage versions used
in AspectJ in download archives, but finally I managed to. Docs
generation looks good visually, tests to be run on GitHub CI.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Switch from 'libx' to 'lib', delete all obsolete binaries
Because 'cd lib && mvn compile' can now download and (un)zip many
previously SCM-committed third-party dependencies, the following 'lib'
subdirectories have been deleted:
- ant
- asm
- commons
- jarjar
- junit
- regexp
- saxon
This one is new (but not stored in SCM):
- jdtcore-aj
For each of them, there now is a .gitignore entry, so as to prevent
developers from accidentally committing the downloaded binaries again.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Make sure to clean up temp-dirs in 'weaver' module
Maven Clean now deletes '' directories if it finds any. Furthermore,
AsynchronousFileCacheBackingTestSupport now not just deletes directory
contents but also removes the empty corresponding directories
afterwards.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
There is a warning because 'asm-renamed' uses
<version>${asm.version}</version> in its artifact descriptor instead of
a fixed version. but as long as Maven still permits it, let us use it
this way. Flatten Maven plugin replaces it by a resolved number anyway
for the dependency-reduced POM.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Module 'asm-renamed' now deploys to GitHub Packages
This means that instead of a system-scoped dependency we now have a
regular one.
The 'libx' module also downloads binary and source JARs redundantly into
the libraries directory in order to be found there by other scripts and
tests.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Replace JDT Core system dependency by deployed one
Get rid of system paths. Instead, rely on JDT Core Shadows to deploy
both binary and source JARs to GitHub Packages. The former module
directory was deleted completely. Instead, the JARs are redundantly
copied into 'libs/jdtcore-aj' in order to be found there by tests and
other Ant scripts.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Build libs without additional profiles, add Enforcer rule
Because 'libx' no longer is a submodule of the AspectJ parent POM, it
will not be built automatically each time an AspectJ build runs.
Therefore, is is no longer necessary to shield the zip/unzip steps from
repetitive execution by profiles with auto-activation based on the
(non-)existence of files. An AspectJ developer knows when to build the
module, she does it manually anyway.
A new Enforcer rule makes sure to warn the developer if some files it
expects to exist in the libs folder are not actually present.
Now we also have a Maven Clean rule which wipes away all downloaded and
(un-)zipped files.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Replace system-scoped dependency on commons by granular dependencies
There are only two direct dependencies used in AspectJ code:
- Commons Digester (module 'testing')
- Commons Logging (module 'org.aspectj.matcher')
I declared those two and experimentally removed all the other
system-scoped dependencies, as it should be. Let's see if the build
works with transitive dependencies.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Make all tests run on Java 16 via '-add-opens' JVM option
Due to JEP 260 (Encapsulate Most Internal APIs), aspect weaving on
Java 16 now requires '--add-opens java.base/java.lang=ALL-UNNAMED' on
the command line. Otherwise there will be illegal access exceptions for
some internal API calls AspectJ needs, most prominently when trying to
define classes in other packages or modules.
This had to be done on several levels:
- Maven Surefire: running tests in a JVM directly forked by Surefire.
In order to make this backwards compatible, I added two profiles
with JDK-level-dependent auto-activation, one 8-15 and one 16+. In
the latter a property containing the JVM parameter is defined, in
the former it is empty, i.e. the JVM is started without the
parameter. In Java 8 the parameter did not even exist, in Java 9+ we
could use it, but we need to test how users use AspectJ.
- RunSpec: Whenever an XML test is declared to use '<run>', we need to
determine the current JVM version and again dynamically add the
parameter when forking the target JVM.
- AntSpec: Whenever an XML test is declared to use '<ant>', we need to
determine the current JVM version dynamically add two properties
usable from within Ant scripts: 'aj.addOpensKey' and
'aj.addOpensValue'. Unfortunately, Ant needs to use two '<argLine>'
parameters, because the two parts of the option are separated by a
space character.
- Ant scripts: When triggered by an AntSpec, each Ant target using LTW
needs to manually set
<jvmarg value="${aj.addOpensKey}"/>
<jvmarg value="${aj.addOpensValue}"/>
for each '<java>' task. It was quite tedious to find all(?) of them.
TODO: In the AspectJ 1.9.7 release notes we need to document that this
parameter is now needed for LTW.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Remove module 'run-all-junit-tests' from root POM -> speed up the build
This module must be a relic from a test runner module once existing
during the Ant build era, but transferred and kept alive in the Maven
build. Actually, it almost doubles build time by running virtually all
tests in all modules again when doing 'mvn test' from the project root.
For now I only removed the module from the root POM, leaving behind
comments there, in the module POM and in the now @Deprecated class
RunTheseBeforeYouCommitTests.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Set maven-assembly-plugin version 3.1.1 explicitly for each POM module
Background: There are CI tests failing because the version is not taken
from the parent POM, even if set in the 'pluginManagement' section.
Instead, it is resolved via the Maven Super POM, e.g. 2.2-beta-5, see:
https://maven.apache.org/ref/3.6.3/maven-model-builder/super-pom.html
That assembly plugin version in turn requires plexus-archiver
1.0-alpha-12. The latter cannot be downloaded from Maven Central,
leading to the problems seen during builds.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Andy Clement
Alexander Kriegisch
Lars Grefer