mirror of
https://github.com/apache/activemq-artemis.git
synced 2025-02-07 18:49:14 +00:00
3a4b421d2e
Markdown, which is currently used for user-facing documentation, is good for a lot of things. However, it's not great for the kind of complex documentation we have and our need to produce both multi-page HTML and single-page PDF output via Maven. Markdown lacks features which would make the documentation easier to read, easier to navigate, and just look better overall. The current tool-chain uses honkit and a tool called Calibre. Honkit is written in TypeScript and is installed via NPM. Calibre is a native tool so it must be installed via an OS-specific package manager. All this complexity makes building, releasing, uploading, etc. a pain. AsciiDoc is relatively simple like Markdown, but it has more features for presentation and navigation not to mention Java-based Maven tooling to generate both HTML and PDF. Migrating will improve both the appearance of the documentation as well as the processes to generate and upload it. This commit contains the following changes: - Convert all the Markdown for the User Manual, Migration Guide, and Hacking guide to AsciiDoc via kramdown [1]. - Update the `artemis-website` build to use AsciiDoctor Maven tooling. - Update `RELEASING.md` with simplified instructions. - Update Hacking Guide with simplified instructions. - Use AsciiDoc link syntax in Artemis Maven doc plugin. - Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking Guide. All docs will be HTML only except for the User Manual which will have PDF. - Move all docs up out of their respective "en" directory. This was a hold-over from when we had docs in different languages. - Migration & Hacking Guides are now single-page HTML since they are relatively short. - Refactor README.md to simplify and remove redundant content. Benefits of the change: - Much simplified tooling. No more NPM packages or native tools. - Auto-generated table of contents for every chapter. - Auto-generated anchor links for every sub-section. - Overall more appealing presentation. - All docs will use the ActiveMQ favicon. - No more manual line-wrapping! AsciiDoc recommends one sentence per line and paragraphs are separated by a blank line. - AsciiDoctor plugins for IDEA are quite good. - Resulting HTML is less than *half* of the previous size. All previous links/bookmarks should continue to work. [1] https://github.com/asciidoctor/kramdown-asciidoc
73 lines
2.6 KiB
Plaintext
73 lines
2.6 KiB
Plaintext
= Building
|
|
|
|
We use Apache Maven to build the code, distribution, etc. and to manage dependencies.
|
|
|
|
The minimum required Maven version is 3.0.0.
|
|
|
|
Note that there are some https://cwiki.apache.org/confluence/display/MAVEN/Maven+3.x+Compatibility+Notes[compatibility issues with Maven 3.X] still unsolved.
|
|
This is specially true for the https://maven.apache.org/plugins-archives/maven-site-plugin-3.3/maven-3.html['site' plugin].
|
|
|
|
== Full Release
|
|
|
|
To build the full release with the documentation & JavaDocs:
|
|
[,console]
|
|
----
|
|
$ mvn -Prelease package
|
|
----
|
|
To install it to your local maven repo:
|
|
[,console]
|
|
----
|
|
$ mvn -Prelease install
|
|
----
|
|
For any build you can skip the tests using `-DskipTests` which will make the build *much* faster, e.g.
|
|
[,console]
|
|
----
|
|
$ mvn -Prelease package -DskipTests
|
|
----
|
|
|
|
== Full Release without docs
|
|
|
|
It is possible to build a distribution without the manuals and Javadocs.
|
|
simply run
|
|
[,console]
|
|
----
|
|
$ mvn package
|
|
----
|
|
|
|
== Only docs
|
|
|
|
From the `artemis-website` module run:
|
|
[,console]
|
|
----
|
|
$ mvn -Prelease package
|
|
----
|
|
This will build the user manual (both HTML & PDF), migration guide, hacking guide, & JavaDocs.
|
|
Output will be placed in the `target/classes/user-manual`, `target/classes/migration-guide`, `target/classes/hacking-guide`, and `target/apidocs` directories respectively.
|
|
|
|
Generating the user manual's PDF adds almost a minute to the build so this can be skipped using `-DskipWebsitePdfGeneration`.
|
|
|
|
== Offline
|
|
|
|
[,console]
|
|
----
|
|
$ mvn dependency:go-offline
|
|
$ mvn -o ...
|
|
----
|
|
|
|
== Building the ASYNC IO library
|
|
|
|
ActiveMQ Artemis provides the `ASYNCIO` `journal-type` which interacts with the Linux kernel libaio library. The ASYNCIO journal type should be used where possible as it is far superior in terms of performance.
|
|
|
|
ActiveMQ Artemis does not ship with the Artemis Native ASYNCIO library in the _source_ distribution. This need to be built prior to running `mvn install`, to ensure that the ASYNCIO journal type is available in the resulting build. Don't worry if you don't want to use ASYNCIO or your system does not support libaio, ActiveMQ Artemis will check at runtime to see if the required libraries and system dependencies are available, if not it will default to using NIO.
|
|
|
|
To build the ActiveMQ Artemis ASYNCIO native libraries, please follow link:https://github.com/apache/activemq-artemis-native[these instructions].
|
|
|
|
== Open Web Application Security Project (OWASP) Report
|
|
|
|
If you wish to generate a report for dependency CVEs you may build with the `-Powasp` profile, e.g.:
|
|
|
|
[,console]
|
|
----
|
|
$ mvn -Powasp verify -DskipTests
|
|
----
|
|
The output will be under `./target/dependency-check-report.html` for *each* sub-module. |