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>
Detect previously failed downloads by verifying existing file checksums
There was a helpful option hiding in Download Maven plugin, which we use
to download artifacts unavailable on Maven Central, such as the Ant
installer and several source packages: 'checkSignature'. It has the
effect of verifying checksums of existing, i.e. previously downloaded
files too, not only newly downloaded ones. This helps detect interrupted
downloads from previous runs or generally invalid files, whatever the
reason. I was looking for this option before, but did not notice it
because of the name. This is about verifying checksums, not checking
signatures. Anyway, a maintainer just told me about it here:
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>
Revert "Always run javadoc using the ToolProvider API"
This reverts commit f70aeb5e, except for some commented-out parts of
code and an unused method. I also simplified the code, e.g. with regard
to exception handling, and did some more cosmetic stuff, but basically
it is a revert.
In order to make it compile on more recent JDKs which doe not have class
com.sun.tools.javadoc.Main, I used Class.forName in the method being
called on JDK 8 only.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Fix Javadoc generation by also unpacking relocated ASM sources
Suddenly, for AspectJ Weaver + Tools Javadoc generation started to fail.
This might be due to switching from ASM-renamed to dynamically shaded
ASM. Either way, the Javadoc tool complains about the missing source
files. Therefore, we also unpack them from the source uber JAR now via
TrueZIP before generating Javadoc.
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>
In order to keep developers from creating AspectJ releases manually or
using Ant script 'build/build.xml', get rid of all POM templates. This
step does not involve updating any build or release how-to documents or
any other clean-up work under 'build', but it is a first step and a
simple, implicit reminder that now we can build and release using Maven.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
This involves replacing references in weaver application code as well as
a few tests.
In order to make AspectJ weaver + tools contain a relocated ASM version,
I added a Maven Shade relocation step after Maven Assembly created the
uber JARs. Relocation works for both binaries and sources and also
encompasses Class::forName calls like in class AsmDetector.
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>
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>
Add information required by Maven Central to public artifact POMs
This is another step away from manual deployment towards Maven-triggered
deployment for both releases and snapshots. The 5 main POMs (matcher,
runtime, weaver, tools, installer) now contain information required by
Sonatype for Maven Central deployments according to:
https://central.sonatype.org/publish/requirements/
TODO:
- Add corresponding 'distributionManagement' section and necessary
release plugins for Sonatype OSS repositories to parent POM.
- Enable Maven to also use Install plugin in order to automatically
set release versions, commit to Git and tag releases, then upgrade
to a new snapshot afterwards.
- Make sure that Flatten Maven plugin does not strip off the required
tags we just added to the POMs. It looks as if the chosen
flattenMode=oss already retains the exact tags we need, only
slightly reformatting (hence "uglifying") the POM. But an ugly POM
does not block Maven Central deployments, as long as it is complete.
So it looks as if this to-do item is already done.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Replace links to aspectj.org by links to eclipse.org/aspectj
As discussed with Andy Clement, domain aspectj.org seems to still be
owned by Xerox, and currently no website for it is online. Therefore, it
is better to link to the AspectJ Eclipse homepage.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Revert "use the alternate maven settings by default"
This reverts commit @95fc5eec, because that commit was only helpful
before merging branch 'migrate-to-aspectj-dev' with PR #49, but was
actually committed afterwards, making it obsolete.
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>
There is a strange effect in Maven builds: Depending on which profiles
are active when building the project - even seemingly unrelated ones
like 'create-docs' or 'clean-libs' - the execution order of plugins in
the 'process-resources' phase can vary. Specifically, Build Helper vs.
Enforcer in module 'lib', which both were in the same phase, can
sometimes be executed in lexical order, which I expected, or the other
way around, which makes the build fail if the existence of the marker
file is checked by Enforcer before Build Helper even had a chance to
create it. Probably, this is because Build Helper is defined inside a
profile and Enforcer outside of any.
Therefore, the safest way to ensure correct ordering of the two is to
place Enforcer in a later phase, in this case 'compile'.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
I tripped over not finding aspectjtools in my IntelliJ Maven view many
times, because it was listed as "AspectJ Compiler". So I renamed it to
"AspectJ Tools (Compiler)". Now it resembles more the artifact ID and
still retains the information that it is the artifact containing AJC.
For the 'lib' module I removed the 'name' tag again, because it is not
one of the main artifacts we publish. Now the POMs are more like Andy
might have intended them to be, using a human-readable 'name' only for
the main artifacts.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
In the previous GitHub build, there were warnings in the log because of
failed downloads. Actually, the default is to fail the build, but that
did not happen. Let us try a more recent version, maybe it fixes an old
bug, even though in the diff between the versions I did not see anything
obvious here.
Anyway, I created an issue ticket:
https://github.com/maven-download-plugin/maven-download-plugin/issues/185
BTW, our build only failed later during the Maven Enforcer sanity check,
because several files from the check list were missing after a seemingly
successful provisioning. Actually, I am glad I added this "redundant"
double-checking step to the build, otherwise the build would not have
failed in the 'lib' module but much later in a hard to detect spot.
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>
Fix missing dependencies in module 'run-all-junit-tests'
Some runtime dependencies are reported as unused in Maven Dependency
Plugin goal 'dependency:analyze', but actually they are needed. I
noticed by chance when running RunTheseBeforeYouCommitTests in IntelliJ
IDEA for the first time after a while and dependency modules could not
find classes.
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>
Fix: make sure that source assemblies are attached to build
Previously I renamed the source assemblies from the uniform name
'sources' to something more individual like 'aspectjtools-sources', not
realising that the magic name 'sources' in combination with the default
configuration value 'appendAssemblyId=true' results in an artifact
classifier equal to the assembly ID, i.e. 'sources', which is exactly
what we need here, but not quite obvious. Therefore, I documented it
with comments in both the assemblies and the POMs.
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>
Use dependencies instead of copies under 'lib' for assemblies
This is one step to get rid of org.aspectj:org.eclipse.jdt.core and
org.aspectj:asm-renamed in the 'lib' directory.
AspectJ tools + weaver uber JAR builds now use dependencies in the POM
in order to deal with creating binary + source assemblies. They no
longer rely on manually updated copies under 'lib'. Details:
- Binaries are copied via 'dependencySets' in the assembly descriptor.
- Sources are unzipped via Maven Dependency Plugin before including
them into the source uber JAR via assembly descriptor.
- NEW: This also includes ASM-renamed sources which so far were
ignored. It is a positive side-effect from the fact that for
ASM-renamed Maven Shade automatically creates a source JAR.
- Maven Ant Run is no longer used for unzipping binary + source JARs.
- While working in parallel with JDT Core and AspectJ it is now much
easier to produce up to date artifacts, e.g. for consumption by
AJDT, because it does not matter anymore if we forget to run the
build in module 'lib' in order to update the JDT Core copy.
Status quo:
- Folder lib/asm is no longer used and will be removed in a subsequent
commit.
- Folder lib/jdtcore-aj is no longer used by the Maven build, but
still referenced in a few UNIX shell scripts and Ant build files.
TODO: Find out if those are still actively used. If yes, refactor
them to look for the file in the local Mavven repository. Otherwise,
delete the referencing files and also lib/jdtcore-aj.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Remove remaining usage message duplication between ECJ and AJC
The resource key 'misc.usage' is completely gone from
.../jdt/internal/compiler/batch/messages_aspectj.properties. Instead,
JDT Core was adjusted in such a way as to patch the new resource key
'misc.usage.aspectj' into the upstream 'misc.usage' in the right place.
Now finally the properties file is as lean as I envisioned it to be,
without any loss of information and without the need of future manual
synchronisation of duplicate texts for every release.
At the same time, usage text detection in AjdtCommand::inferKind was
improved and also adjusted to the new situation.
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 'tests', our tests need Ant launcher. Hence, dependency
ant:ant-launcher 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>
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>
Fix image formatting glitch in docs/devGuideDB/ajbrowser.xml
An image which should be in its own paragraph was shown inline with the
text, somewhere to the right in the middle of a text paragraph. I
noticed while visually checking if docs generation still works as
expected after the last few commits, so I quickly fixed it.
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>
Remove indentation from <programlisting> blocks in docs
Many dozens (hundreds?) of documentation code blocks were indented to
match the surrounding XML or just arbitrarily. The thing is: Inside
<programlisting> tags, similar to <pre> tags, line feeds and leading
whitespace are being preserved, which looked very awkward in the HTML
documentation. While a few files were mostly correct in this respect,
which shows that it was meant to be like that, many others were not.
This was tedious, stupid work to fix, but it had to be done.
Please note that the documentation was in no way updated content-wise.
This is also overdue, but not my focus here.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Add comments about wrong classpath entries to docs/build.xml
Of 6 classpath entries for Ant taskdef "fop", only 2 are actually
correct. That might mean that the others are not necessary, because docs
generation works correctly anyway.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
projects / aspectj.git / log