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>
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>
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>
Remove redundant 'name' and 'packaging' tags from POMs
If 'name' is identical to 'artifactId' and 'packaging' has the default
value 'jar', we can just remove those tags from the POM.
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>
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>
Clean up remaining references to system-scoped dependencies
Now there is no system-scoped dependency left anymore in the Maven
build, i.e. the corresponding warnings are gone and we can focus on the
actual build log.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
In two places, the documentation now contains this text:
"Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no longer
part of AspectJ. JRockit JDK never supported Java versions higher than
1.6. Several JRockit JVM features are now part of HotSpot and tools like
Mission Control available for OpenJDK and Oracle JDK."
The decision to drop JRockit support was made during a discussion
between Alexander Kriegisch and Andy Clement:
Andy Clement wrote on 26 Mar 2021:
> Yes I think so.
>
>
> Alexander Kriegisch wrote on 26 Mar 2021:
>
>> https://en.wikipedia.org/wiki/JRockit
>>
>> Can we get rid of that? AspectJ requires Java 8, JRockit never
>> supported more than Java 6.
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>
Add developer info + sample config about how to work with a RAM disk
There are two files:
- docs/developer/ram-disk/maven.config
- docs/developer/ram-disk/settings-ramdisk.xml
The latter contains info about how to set up a development environment
inside a RAM disk. Both files are to be copied to the project's '.mvn'
folder in the root directory and adjusted according to the description.
Just in case, .gitignore ignores the files if they exist in '.mvn', so
they are not being staged and committed accidentally.
An additional screenshot shows how to configure the Windows Recycle Bin
to immediately delete files in order too save space on the RAM disk.
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>
Move documentation generation into Maven profile 'create-docs'
The profile is active by default, but can be deactivated via
'-P !create-docs' on the Maven command line. This helps to speed up
'mvn install', maybe in combination with skipping tests, if we just want
to create a new set of AspectJ binaries.
Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
Alexander Kriegisch
Andy Clement
Emmanuel Bourg
Jerry James
Lars Grefer