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 was required by the Eclipse team as one precondition for the next
release.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

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>

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

Also depend on JDT Core 1.9.7.M2

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

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>

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>

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>

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>

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>

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>

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>

No more manual version setting everywhere.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

This is not strictly necessary, but probably does not hurt either. While
upgrading, '<tasks>' tags have been renamed to the new standard
'<target>'.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

Before it was phase 'validate', which was way too early and somewhat
annoying and time-consuming when during development we just call
validate in order to check if the POMs are valid, as the name implies.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

This is a follow-up on commit @0b182d60. I have just received
confirmation from Oracle that my issue was accepted:

https://bugs.java.com/bugdatabase/view_bug.do?bug_id=JDK-8263924
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

WARNING: Please avoid line breaks in manifest values! They are passed on
like this: Assembly Plugin -> Plexus Archiver -> JRE java.util.jar
.Manifest.write(OutputStream).

The JRE Manifest class inserts hard line breaks always after 72
characters, no matter if those 72 characters contain line feeds, tabs or
spaces. Hence, it can happen that unwanted blank lines end up in the
middle of a manifest section, making the manifest invalid. Calls like
e.g. 'java -cp aspectjtools.jar org.aspectj.tools.ajc.Main' can then
fail with the absolutely unexpected error 'Could not find or load main
class org.aspectj.tools.ajc.Main'.

In IntelliJ IDEA you can deactivate wrapping text inside XML tags like
this: "File | Settings | Editor | Code Style | XML | Wrap text -> off"

The problem occurs in Maven Assembly in versions higher than 2.2. More
exactly, it occurs in Plexus Archiver after in more recent versions it
switched to using the JRE Manifest class.

TODO 1: Either add a test step in phase 'verify' doing something like
this:

new Manifest(new FileInputStream("MANIFEST.MF"));

This would lead to "IOException: invalid header field (line xy)" in case
of an invalid manifest file.

TODO 2: Or file a JRE bug at Oracle or OpenJDK, wherever appropriate.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

Keep only ASM 2.0 binary because it is still used in UnweavableTest
which uses an old ASM API, e.g. with a ClassWriter constructor which no
longer exists.

Also add JarJar 1.3 library because it is needed by an Ant task in
lib/asm/build.xml.

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

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>

Signed-off-by: Lars Grefer <eclipse@larsgrefer.de>