From c5b5828ffd0222b15b296190adb5844371d82b49 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Fri, 7 Aug 2026 23:40:42 +0200 Subject: [PATCH 1/2] Rename the site documents ahead of converting them Kept as its own commit so that git log --follow and git blame still reach each page's history once the content changes. --- .../examples/compile-using-different-jdk.md.vm} | 0 .../examples/compile-with-memory-enhancements.md.vm} | 0 .../jpms_args.apt.vm => markdown/examples/jpms_args.md.vm} | 0 .../module-info.apt.vm => markdown/examples/module-info.md.vm} | 0 .../examples/pass-compiler-arguments.md.vm} | 0 .../examples/set-compiler-release.md.vm} | 0 .../examples/set-compiler-source-and-target.md.vm} | 0 src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 src/site/{apt/multirelease.apt => markdown/multirelease.md} | 0 .../non-javac-compilers.md.vm} | 0 src/site/{apt/usage.apt.vm => markdown/usage.md.vm} | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename src/site/{apt/examples/compile-using-different-jdk.apt.vm => markdown/examples/compile-using-different-jdk.md.vm} (100%) rename src/site/{apt/examples/compile-with-memory-enhancements.apt.vm => markdown/examples/compile-with-memory-enhancements.md.vm} (100%) rename src/site/{apt/examples/jpms_args.apt.vm => markdown/examples/jpms_args.md.vm} (100%) rename src/site/{apt/examples/module-info.apt.vm => markdown/examples/module-info.md.vm} (100%) rename src/site/{apt/examples/pass-compiler-arguments.apt.vm => markdown/examples/pass-compiler-arguments.md.vm} (100%) rename src/site/{apt/examples/set-compiler-release.apt.vm => markdown/examples/set-compiler-release.md.vm} (100%) rename src/site/{apt/examples/set-compiler-source-and-target.apt.vm => markdown/examples/set-compiler-source-and-target.md.vm} (100%) rename src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename src/site/{apt/multirelease.apt => markdown/multirelease.md} (100%) rename src/site/{apt/non-javac-compilers.apt.vm => markdown/non-javac-compilers.md.vm} (100%) rename src/site/{apt/usage.apt.vm => markdown/usage.md.vm} (100%) diff --git a/src/site/apt/examples/compile-using-different-jdk.apt.vm b/src/site/markdown/examples/compile-using-different-jdk.md.vm similarity index 100% rename from src/site/apt/examples/compile-using-different-jdk.apt.vm rename to src/site/markdown/examples/compile-using-different-jdk.md.vm diff --git a/src/site/apt/examples/compile-with-memory-enhancements.apt.vm b/src/site/markdown/examples/compile-with-memory-enhancements.md.vm similarity index 100% rename from src/site/apt/examples/compile-with-memory-enhancements.apt.vm rename to src/site/markdown/examples/compile-with-memory-enhancements.md.vm diff --git a/src/site/apt/examples/jpms_args.apt.vm b/src/site/markdown/examples/jpms_args.md.vm similarity index 100% rename from src/site/apt/examples/jpms_args.apt.vm rename to src/site/markdown/examples/jpms_args.md.vm diff --git a/src/site/apt/examples/module-info.apt.vm b/src/site/markdown/examples/module-info.md.vm similarity index 100% rename from src/site/apt/examples/module-info.apt.vm rename to src/site/markdown/examples/module-info.md.vm diff --git a/src/site/apt/examples/pass-compiler-arguments.apt.vm b/src/site/markdown/examples/pass-compiler-arguments.md.vm similarity index 100% rename from src/site/apt/examples/pass-compiler-arguments.apt.vm rename to src/site/markdown/examples/pass-compiler-arguments.md.vm diff --git a/src/site/apt/examples/set-compiler-release.apt.vm b/src/site/markdown/examples/set-compiler-release.md.vm similarity index 100% rename from src/site/apt/examples/set-compiler-release.apt.vm rename to src/site/markdown/examples/set-compiler-release.md.vm diff --git a/src/site/apt/examples/set-compiler-source-and-target.apt.vm b/src/site/markdown/examples/set-compiler-source-and-target.md.vm similarity index 100% rename from src/site/apt/examples/set-compiler-source-and-target.apt.vm rename to src/site/markdown/examples/set-compiler-source-and-target.md.vm diff --git a/src/site/apt/index.apt.vm b/src/site/markdown/index.md.vm similarity index 100% rename from src/site/apt/index.apt.vm rename to src/site/markdown/index.md.vm diff --git a/src/site/apt/multirelease.apt b/src/site/markdown/multirelease.md similarity index 100% rename from src/site/apt/multirelease.apt rename to src/site/markdown/multirelease.md diff --git a/src/site/apt/non-javac-compilers.apt.vm b/src/site/markdown/non-javac-compilers.md.vm similarity index 100% rename from src/site/apt/non-javac-compilers.apt.vm rename to src/site/markdown/non-javac-compilers.md.vm diff --git a/src/site/apt/usage.apt.vm b/src/site/markdown/usage.md.vm similarity index 100% rename from src/site/apt/usage.apt.vm rename to src/site/markdown/usage.md.vm From 286aeb39241f5bc4d9ccf501392c127a771287a8 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Fri, 7 Aug 2026 23:43:06 +0200 Subject: [PATCH 2/2] Port the site documentation from APT to Markdown The maintenance line still carried its site documentation in APT, so a release from it would have published the old pages while the default branch serves Markdown. Four things APT renders literally that Markdown would reinterpret: a double hyphen, which the typographic extension folds into an en dash; an asterisk mid-line, which is emphasis in Markdown but only a list marker in APT; and, in the pages that keep a .vm suffix, ## which Velocity reads as a line comment. Verified by building the site before and after and comparing all 27 generated pages: every one is identical in its title, author and date metadata, its visible text and every link target. --- .../compile-using-different-jdk.md.vm | 123 +++---- .../compile-with-memory-enhancements.md.vm | 59 ++-- src/site/markdown/examples/jpms_args.md.vm | 108 +++--- src/site/markdown/examples/module-info.md.vm | 317 +++++++++--------- .../examples/pass-compiler-arguments.md.vm | 61 ++-- .../examples/set-compiler-release.md.vm | 119 +++---- .../set-compiler-source-and-target.md.vm | 87 ++--- src/site/markdown/index.md.vm | 115 +++---- src/site/markdown/multirelease.md | 313 ++++++++--------- src/site/markdown/non-javac-compilers.md.vm | 88 ++--- src/site/markdown/usage.md.vm | 82 +++-- 11 files changed, 647 insertions(+), 825 deletions(-) diff --git a/src/site/markdown/examples/compile-using-different-jdk.md.vm b/src/site/markdown/examples/compile-using-different-jdk.md.vm index 0cee54aa8..250cab135 100644 --- a/src/site/markdown/examples/compile-using-different-jdk.md.vm +++ b/src/site/markdown/examples/compile-using-different-jdk.md.vm @@ -1,59 +1,48 @@ - ------ - Compiling Sources Using A Different JDK - ------ - Edwin Punzalan - ------ - 2006-07-05 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Compiling Sources Using A Different JDK - -* Using Maven Toolchains - - The preferable way to use a different JDK is to use the toolchains mechanism. During the build of a project, Maven, - without toolchains, will use the JDK to perform various steps, like compiling the Java sources, generate the Javadoc, - run unit tests or sign JARs. Each of those plugins need a tool of the JDK to operate: <<>>, <<>>, - <<>>, etc. A toolchain is a way to specify the path to the JDK to use for all of those plugins in a - centralized manner, independent from the one running Maven itself. - - To set this up, refer to the {{{/guides/mini/guide-using-toolchains.html}Guide to Using Toolchains}}, which makes use - of the {{{/plugins/maven-toolchains-plugin/}Maven Toolchains Plugin}}. - - With the maven-toolchains-plugin you configure 1 default JDK toolchain for all related maven-plugins. - Since maven-compiler-plugin 3.6.0 when using with Maven 3.3.1+ it is also possible to give the plugin its own - toolchain, which can be useful in case of different JDK calls per execution block (e.g. the test sources require a - different compiler compared to the main sources). - -* Configuring the Compiler Plugin - - Outside of a toolchain, it is still possible to tell the Compiler Plugin the specific JDK to use during compilation. - Note that such configuration will be specific to this plugin, and will not affect others. - - The <<>> parameter can be used to specify the version of the - compiler that the plugin will use. However, you also need to set <<>> - to <<>> for this to work. For example: - -+------- +--- +title: Compiling Sources Using A Different JDK +author: + - Edwin Punzalan +date: 2006-07-05 +--- + + + +# Compiling Sources Using A Different JDK + +Using Maven Toolchains +---------------------- + +The preferable way to use a different JDK is to use the toolchains mechanism. During the build of a project, Maven, without toolchains, will use the JDK to perform various steps, like compiling the Java sources, generate the Javadoc, run unit tests or sign JARs. Each of those plugins need a tool of the JDK to operate: `javac`, `javadoc`, `jarsigner`, etc. A toolchain is a way to specify the path to the JDK to use for all of those plugins in a centralized manner, independent from the one running Maven itself. + +To set this up, refer to the [Guide to Using Toolchains](/guides/mini/guide-using-toolchains.html), which makes use of the [Maven Toolchains Plugin](/plugins/maven-toolchains-plugin/). + +With the maven-toolchains-plugin you configure 1 default JDK toolchain for all related maven-plugins. Since maven-compiler-plugin 3.6.0 when using with Maven 3.3.1+ it is also possible to give the plugin its own toolchain, which can be useful in case of different JDK calls per execution block (e.g. the test sources require a different compiler compared to the main sources). + +Configuring the Compiler Plugin +------------------------------- + +Outside of a toolchain, it is still possible to tell the Compiler Plugin the specific JDK to use during compilation. Note that such configuration will be specific to this plugin, and will not affect others. + +The `compilerVersion` parameter can be used to specify the version of the compiler that the plugin will use. However, you also need to set `fork` to `true` for this to work. For example: + +```unknown [...] @@ -75,20 +64,17 @@ Compiling Sources Using A Different JDK [...] -+------- +``` - To avoid hard-coding a filesystem path for the executable, you can use a - property. For example: +To avoid hard-coding a filesystem path for the executable, you can use a property. For example: -+------- +```unknown ${JAVA_1_4_HOME}/bin/javac -+------- +``` - Each developer then defines this property in - {{{http://maven.apache.org/ref/current/maven-settings/settings.html}settings.xml}}, - or sets an environment variable, so that the build remains portable. +Each developer then defines this property in [settings.xml](http://maven.apache.org/ref/current/maven-settings/settings.html), or sets an environment variable, so that the build remains portable. -+------- +```unknown [...] @@ -105,8 +91,7 @@ Compiling Sources Using A Different JDK compiler -+------- +``` + +If you build with a different JDK, you may want to [ customize](http://maven.apache.org/plugins/maven-jar-plugin/examples/manifest-customization.html) the jar file manifest. - If you build with a different JDK, you may want to - {{{http://maven.apache.org/plugins/maven-jar-plugin/examples/manifest-customization.html} - customize}} the jar file manifest. diff --git a/src/site/markdown/examples/compile-with-memory-enhancements.md.vm b/src/site/markdown/examples/compile-with-memory-enhancements.md.vm index a4e6986d7..9fcfdb3e5 100644 --- a/src/site/markdown/examples/compile-with-memory-enhancements.md.vm +++ b/src/site/markdown/examples/compile-with-memory-enhancements.md.vm @@ -1,38 +1,34 @@ - ------ - Compile Using Memory Allocation Enhancements - ------ - Edwin Punzalan - ------ - 2006-07-05 - ------ +--- +title: Compile Using Memory Allocation Enhancements +author: + - Edwin Punzalan +date: 2006-07-05 +--- -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. + - The Compiler Plugin accepts configurations for <<>> and - <<>>. You can follow the example below to set the initial memory - size to 128MB and the maximum memory usage to 512MB: +# Compile Using Memory Allocation Enhancements -+----- +The Compiler Plugin accepts configurations for `meminitial` and `maxmem`. You can follow the example below to set the initial memory size to 128MB and the maximum memory usage to 512MB: + +```unknown [...] @@ -53,4 +49,5 @@ Compile Using Memory Allocation Enhancements [...] -+----- \ No newline at end of file +``` + diff --git a/src/site/markdown/examples/jpms_args.md.vm b/src/site/markdown/examples/jpms_args.md.vm index 723abae00..fde081fbd 100644 --- a/src/site/markdown/examples/jpms_args.md.vm +++ b/src/site/markdown/examples/jpms_args.md.vm @@ -1,62 +1,46 @@ - ------ - jpms.args - ------ - Robert Scholte - ------ - 2017-08-22 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -JPMS.ARGS - - Java 9 comes with a new set of arguments related to the Java Platform Modular System. Besides the module path are - other new arguments which can change the behavior of the application. These can be used during both compile time - and runtime. This information is not stored in any class, but it can be interesting to know at runtime which extra - arguments were used at compile time. - - If any of these arguments is used, the <<>> is created. - Every argument gets its own line. - The following arguments will end up in this file: - - * <<<--upgrade-module-path>>> - - * <<<--add-exports>>> - - * <<<--add-reads>>> - - * <<<--add-modules>>> - - * <<<--limit-modules>>> - - * <<<--patch-module>>> - - [] - - The <<<--patch-module>>> values are different compared to the original values passed to the compiler. According to - the specification it looks like <<<--patch-module \=\(\\)\*>>> - However, files are system specific. For that reason the module names are used. If the jar itself contains the - patchcode, then an <<<_>>> (underscore) is used. As separators a <<<, >>> (comma + space) is used. - -+--- - --patch-module - =(, )* -+--- \ No newline at end of file +--- +title: jpms.args +author: + - Robert Scholte +date: 2017-08-22 +--- + + + +# JPMS.ARGS + +Java 9 comes with a new set of arguments related to the Java Platform Modular System. Besides the module path are other new arguments which can change the behavior of the application. These can be used during both compile time and runtime. This information is not stored in any class, but it can be interesting to know at runtime which extra arguments were used at compile time. + +If any of these arguments is used, the `META-INF/jpms.args` is created. Every argument gets its own line. The following arguments will end up in this file: + +- `--upgrade-module-path` +- `--add-exports` +- `--add-reads` +- `--add-modules` +- `--limit-modules` +- `--patch-module` + +The `--patch-module` values are different compared to the original values passed to the compiler. According to the specification it looks like `--patch-module =()*` However, files are system specific. For that reason the module names are used. If the jar itself contains the patchcode, then an `_` (underscore) is used. As separators a `, ` (comma + space) is used. + +```unknown + --patch-module + =(, )* +``` + diff --git a/src/site/markdown/examples/module-info.md.vm b/src/site/markdown/examples/module-info.md.vm index 09c5f69ca..6a86947cf 100644 --- a/src/site/markdown/examples/module-info.md.vm +++ b/src/site/markdown/examples/module-info.md.vm @@ -1,164 +1,153 @@ - ------ - Older projects with module-info - ------ - Robert Scholte - ------ - 2016-09-27 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Older projects with module-info - - Projects that want to be compatible with older versions of Java (i.e 1.8 or below bytecode and API), but also want to provide a - <<>> for use on Java 9+ runtime, must be aware that they need to call <<>> twice: - - [[1]] the <<>> must be compiled with <<>>, - - [[2]] while the rest of the sources must be compiled with the lower expected compatibility version of <<>>/<<>>. - - [] - - The preferred way to do this is by having 2 execution blocks, as described below: - - [[1]] default <<>> execution with <<>>, - - [[2]] additional custom <<>> execution with expected target compatibility. - - [] - - Notice that, in addition, JDK 9 only supports compilations for Java 6 and above, so projects wanting to be compatible with Java 5 or below need - to use two different JDKs for the 2 executions. With {{{/guides/mini/guide-using-toolchains.html}toolchains}} configuration, it is - quite easy to achieve this, even if a little bit more complex. - -* Java 6 to 8 Compatibility - - In case you want the project to be Java 6, 7 or 8 compatible, you can simply use JDK 9 for both execution blocks. - - The easiest way is to use Java 9 as the runtime for Maven, by setting <<>> before running <<>>. - But if you want to use an older Java runtime for Maven, you can use the maven-toolchain-plugin to specify the shared JDK - or a custom jdkToolchain and refer to the JDK 9 installation on your system. - -+------- - - [...] - - [...] - - - org.apache.maven.plugins - maven-compiler-plugin - ${project.version} - - - default-compile - - 9 - - - - - base-compile - - compile - - - - - module-info.java - - - - - - - 6 - - - 9 - - - - - [...] - - [...] - -+------- - -* Java 5 or below Compatibility - - Given that Maven 3 requires newer Java release at runtime, you'll absolutely need to use Toolchains to use a JDK different from - Maven runtime. - - You could add a jdkToolchain to do base-compile execution-block as well referring to JDK 5. - -+------- - - [...] - - [...] - - - org.apache.maven.plugins - maven-compiler-plugin - ${project.version} - - - default-compile - - 9 - - - - 9 - - - - - base-compile - - compile - - - - - module-info.java - - - - - - - 1.5 - 1.5 - - - [1.5,9) - - - - - [...] - - [...] - -+------- +--- +title: Older projects with module-info +author: + - Robert Scholte +date: 2016-09-27 +--- + + + +# Older projects with module-info + +Projects that want to be compatible with older versions of Java (i.e 1.8 or below bytecode and API), but also want to provide a `module-info.java` for use on Java 9+ runtime, must be aware that they need to call `javac` twice: + +1. the `module-info.java` must be compiled with `release=9`, +1. while the rest of the sources must be compiled with the lower expected compatibility version of `source`/`target`. + +The preferred way to do this is by having 2 execution blocks, as described below: + +1. default `default-compile` execution with `release=9`, +1. additional custom `base-compile` execution with expected target compatibility. + +Notice that, in addition, JDK 9 only supports compilations for Java 6 and above, so projects wanting to be compatible with Java 5 or below need to use two different JDKs for the 2 executions. With [toolchains](/guides/mini/guide-using-toolchains.html) configuration, it is quite easy to achieve this, even if a little bit more complex. + +Java 6 to 8 Compatibility +------------------------- + +In case you want the project to be Java 6, 7 or 8 compatible, you can simply use JDK 9 for both execution blocks. + +The easiest way is to use Java 9 as the runtime for Maven, by setting `JAVA_HOME=/path/to/jdk-9` before running `mvn`. But if you want to use an older Java runtime for Maven, you can use the maven-toolchain-plugin to specify the shared JDK or a custom jdkToolchain and refer to the JDK 9 installation on your system. + +```unknown + + [...] + + [...] + + + org.apache.maven.plugins + maven-compiler-plugin + ${project.version} + + + default-compile + + 9 + + + + + base-compile + + compile + + + + + module-info.java + + + + + + + 6 + + + 9 + + + + + [...] + + [...] + +``` + +Java 5 or below Compatibility +----------------------------- + +Given that Maven 3 requires newer Java release at runtime, you'll absolutely need to use Toolchains to use a JDK different from Maven runtime. + +You could add a jdkToolchain to do base-compile execution-block as well referring to JDK 5. + +```unknown + + [...] + + [...] + + + org.apache.maven.plugins + maven-compiler-plugin + ${project.version} + + + default-compile + + 9 + + + + 9 + + + + + base-compile + + compile + + + + + module-info.java + + + + + + + 1.5 + 1.5 + + + [1.5,9) + + + + + [...] + + [...] + +``` + diff --git a/src/site/markdown/examples/pass-compiler-arguments.md.vm b/src/site/markdown/examples/pass-compiler-arguments.md.vm index 46057ff16..e510cdd03 100644 --- a/src/site/markdown/examples/pass-compiler-arguments.md.vm +++ b/src/site/markdown/examples/pass-compiler-arguments.md.vm @@ -1,40 +1,34 @@ - ------ - Pass Compiler Arguments - ------ - Edwin Punzalan - ------ - 2006-07-05 - ------ +--- +title: Pass Compiler Arguments +author: + - Edwin Punzalan +date: 2006-07-05 +--- -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. + - Sometimes, you need to pass compiler arguments that are not handled by - the Compiler Plugin itself but are supported by the <<>> selected. - For such arguments, use the Compiler Plugin's <<>> parameter - The following example passes compiler arguments to the <<>> - compiler: +# Pass Compiler Arguments -+----- +Sometimes, you need to pass compiler arguments that are not handled by the Compiler Plugin itself but are supported by the `compilerId` selected. For such arguments, use the Compiler Plugin's `compilerArgs` parameter The following example passes compiler arguments to the `javac` compiler: + +```unknown [...] @@ -56,4 +50,5 @@ Pass Compiler Arguments [...] -+----- +``` + diff --git a/src/site/markdown/examples/set-compiler-release.md.vm b/src/site/markdown/examples/set-compiler-release.md.vm index 11e04eee1..aed7fc934 100644 --- a/src/site/markdown/examples/set-compiler-release.md.vm +++ b/src/site/markdown/examples/set-compiler-release.md.vm @@ -1,49 +1,36 @@ - ------ - Setting the --release of the Java Compiler - ------ - Mahmoud Anouti - ------ - 2019-12-20 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Setting the <<<--release>>> of the Java Compiler - - Starting with JDK 9, the <<>> executable can accept the <<<--release>>> - option to specify against which Java SE release you want to build the project. - For example, you have JDK 11 installed and used by Maven, but you want to - build the project against Java 8. - The <<<--release>>> option ensures that the code is compiled following the - rules of the programming language of the specified release, and that generated - classes target the release as well as the public API of that release. This - means that, unlike the old - {{{../examples/set-compiler-source-and-target.html}<<<-source>>> and <<<-target>>> options}}, - the compiler will detect and generate an error when using APIs that don't exist - in previous releases of Java SE. - - Since version 3.6 of the Compiler Plugin, this option can be provided either - via a property: - -+----- +--- +title: Setting the --release of the Java Compiler +author: + - Mahmoud Anouti +date: 2019-12-20 +--- + + + +# Setting the `--release` of the Java Compiler + +Starting with JDK 9, the `javac` executable can accept the `--release` option to specify against which Java SE release you want to build the project. For example, you have JDK 11 installed and used by Maven, but you want to build the project against Java 8. The `--release` option ensures that the code is compiled following the rules of the programming language of the specified release, and that generated classes target the release as well as the public API of that release. This means that, unlike the old [`-source` and `-target` options](../examples/set-compiler-source-and-target.html), the compiler will detect and generate an error when using APIs that don't exist in previous releases of Java SE. + +Since version 3.6 of the Compiler Plugin, this option can be provided either via a property: + +```unknown [...] @@ -51,11 +38,11 @@ Setting the <<<--release>>> of the Java Compiler [...] -+----- +``` - or by configuring the plugin directly: +or by configuring the plugin directly: -+----- +```unknown [...] @@ -74,27 +61,20 @@ Setting the <<<--release>>> of the Java Compiler [...] -+----- +``` - <> The value in the <<>> parameter follows - {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}} adopted since Java 9. - As such, the release number does not start with 1.x anymore. Also note that the - supported <<>> targets include the release of the currently used JDK plus a limited number - of previous releases. +**Note:** The value in the `release` parameter follows [Java's new Version-String Scheme (JEP 223)](https://openjdk.org/jeps/223)} adopted since Java 9. As such, the release number does not start with 1.x anymore. Also note that the supported `release` targets include the release of the currently used JDK plus a limited number of previous releases. -* Usage on JDK 8 +Usage on JDK 8 +-------------- - The <<<--release>>> option is not supported using JDK 8. - However, since Compiler plugin version <<<3.13.0>>> you can use the <<>> property also on JDK 8. - The plugin will convert it to <<>> and <<>> automatically. +The `--release` option is not supported using JDK 8. However, since Compiler plugin version `3.13.0` you can use the `release` property also on JDK 8. The plugin will convert it to `source` and `target` automatically. - To enable a project that targets Java 8 to be built using JDK 8 and also JDK 9 or later requires the conditional - usage of the <<<--release>>> option, when using a plugin version below <<<3.13.0>>> - or compilerId different that <<>>. +To enable a project that targets Java 8 to be built using JDK 8 and also JDK 9 or later requires the conditional usage of the `--release` option, when using a plugin version below `3.13.0` or compilerId different that `javac`. - This may be done through the use of a profile: +This may be done through the use of a profile: -+----- +```unknown [...] @@ -112,14 +92,13 @@ Setting the <<<--release>>> of the Java Compiler [...] -+----- +``` - Since version <<<3.13.0>>> of the Compiler Plugin together with the default <<>> compilerId you don't need conditional parametrisation of <<>>. - The <<>> parameter will only be effective for Java 9 or above, otherwise the <<>> and <<>> will be passed to the compiler. +Since version `3.13.0` of the Compiler Plugin together with the default `javac` compilerId you don't need conditional parametrisation of `release`. The `release` parameter will only be effective for Java 9 or above, otherwise the `source` and `target` will be passed to the compiler. - So you can simply configure as: +So you can simply configure as: -+----- +```unknown [...] @@ -140,5 +119,5 @@ Setting the <<<--release>>> of the Java Compiler [...] -+----- +``` diff --git a/src/site/markdown/examples/set-compiler-source-and-target.md.vm b/src/site/markdown/examples/set-compiler-source-and-target.md.vm index e4e38129a..cd8644a43 100644 --- a/src/site/markdown/examples/set-compiler-source-and-target.md.vm +++ b/src/site/markdown/examples/set-compiler-source-and-target.md.vm @@ -1,47 +1,38 @@ - ------ - Setting the -source and -target of the Java Compiler - ------ - Edwin Punzalan - ------ - 2006-07-05 - ------ +--- +title: Setting the -source and -target of the Java Compiler +author: + - Edwin Punzalan +date: 2006-07-05 +--- -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. + - (If you're are using version <<<3.13.0>>> or newer of the Compiler Plugin, use the recommended - {{{../examples/set-compiler-release.html}<<>> property}}.) +# Setting the `-source` and `-target` of the Java Compiler - Sometimes when you may need to compile a certain project to a different - version than what you are currently using. The <<>> can accept - such command using <<<-source>>> and <<<-target>>>. The Compiler Plugin - can also be configured to provide these options during compilation. - You have to set the version following {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}}. +(If you're are using version `3.13.0` or newer of the Compiler Plugin, use the recommended [`maven.compiler.release` property](../examples/set-compiler-release.html).) - For example, if you want to use the Java 8 language features and also want the compiled classes to be compatible - with JVM 8 (former 1.8) you can either add the two following properties, which are the default property names - for the plugin parameters: +Sometimes when you may need to compile a certain project to a different version than what you are currently using. The `javac` can accept such command using `-source` and `-target`. The Compiler Plugin can also be configured to provide these options during compilation. You have to set the version following [Java's new Version-String Scheme (JEP 223)](https://openjdk.org/jeps/223)}. -+----- +For example, if you want to use the Java 8 language features and also want the compiled classes to be compatible with JVM 8 (former 1.8) you can either add the two following properties, which are the default property names for the plugin parameters: + +```unknown [...] @@ -50,11 +41,11 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler [...] -+----- +``` - or configure the plugin directly: +or configure the plugin directly: -+----- +```unknown [...] @@ -74,19 +65,9 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler [...] -+----- +``` - <> Merely setting the <<>> option does not guarantee that your code actually runs on a JRE with the - specified version. The pitfall is unintended usage of APIs that only exist in later JREs which would make your code - fail at runtime with a linkage error. To avoid this issue, you can either configure the compiler's boot classpath - to match the target JRE, or use the - {{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal Sniffer Maven Plugin}} - to verify your code doesn't use unintended APIs, or better yet use the - {{{../examples/set-compiler-release.html}<<>> option supported since JDK 9}}. - Since plugin version <<<3.13.0>>> you can use the <<>> property also on JDK 8. - The compiler plugin will convert it to <<>> and <<>> automatically. +**Note:** Merely setting the `target` option does not guarantee that your code actually runs on a JRE with the specified version. The pitfall is unintended usage of APIs that only exist in later JREs which would make your code fail at runtime with a linkage error. To avoid this issue, you can either configure the compiler's boot classpath to match the target JRE, or use the [Animal Sniffer Maven Plugin](http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/) to verify your code doesn't use unintended APIs, or better yet use the [`release` option supported since JDK 9](../examples/set-compiler-release.html). Since plugin version `3.13.0` you can use the `release` property also on JDK 8. The compiler plugin will convert it to `source` and `target` automatically. - In the same way, setting the <<>> option does not guarantee that your code actually compiles on a JDK with - the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven, - refer to the {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example. +In the same way, setting the `source` option does not guarantee that your code actually compiles on a JDK with the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven, refer to the [Compile Using A Different JDK](../examples/compile-using-different-jdk.html) example. diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm index 59b089e48..a7e9ba046 100644 --- a/src/site/markdown/index.md.vm +++ b/src/site/markdown/index.md.vm @@ -1,88 +1,61 @@ - ------ - Introduction - ------ - Edwin Punzalan - ------ - 2013-07-22 - ------ +--- +title: Introduction +author: + - Edwin Punzalan +date: 2013-07-22 +--- -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. + - The Compiler Plugin is used to compile the sources of your project. The - default compiler used to compile Java sources is <<>>. - If you want to use another compiler, refer to the {{{./non-javac-compilers} guide: Using Non-Javac Compilers}}. +# ${project.name} - At present the default <<>> and the default <<>> setting are both <<<8>>>, - independently of the JDK you run Maven with. - You are highly encouraged to change these defaults by setting the <<>> option as described in the - {{{./examples/set-compiler-release.html}guide: Compile Using The <<<--release>>> javac Option}}. +The Compiler Plugin is used to compile the sources of your project. The default compiler used to compile Java sources is `javac`. If you want to use another compiler, refer to the [ guide: Using Non-Javac Compilers](./non-javac-compilers). - <> +At present the default `source` and the default `target` setting are both `8`, independently of the JDK you run Maven with. You are highly encouraged to change these defaults by setting the `release` option as described in the [guide: Compile Using The `--release` javac Option](./examples/set-compiler-release.html). -* Goals Overview +**NOTE:** _To know more about the JDK javac, please see: [https://docs.oracle.com/javase/8/docs/technotes/guides/javac/index.html](https://docs.oracle.com/javase/8/docs/technotes/guides/javac/index.html)._ - The Compiler Plugin has two goals. Both are already bound to their proper - phases within the Maven Lifecycle and are therefore, automatically executed - during their respective phases. +Goals Overview +-------------- - * {{{./compile-mojo.html}compiler:compile}} is bound to the compile phase and - is used to compile the main source files. +The Compiler Plugin has two goals. Both are already bound to their proper phases within the Maven Lifecycle and are therefore, automatically executed during their respective phases. - * {{{./testCompile-mojo.html}compiler:testCompile}} is bound to the - test-compile phase and is used to compile the test source files. +- [compiler:compile](./compile-mojo.html) is bound to the compile phase and is used to compile the main source files. +- [compiler:testCompile](./testCompile-mojo.html) is bound to the test-compile phase and is used to compile the test source files. -* Usage +Usage +----- - General instructions on how to use the Compiler Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. +General instructions on how to use the Compiler Plugin can be found on the [usage page](./usage.html). Some more specific use cases are described in the examples given below. - In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. The posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. +In case you still have questions regarding the plugin's usage, please have a look at the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html). The posts to the mailing list are archived and could already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html). - If you feel the plugin is missing a feature or has a defect, you can file a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{http://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. +If you feel the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html). When creating a new issue, please provide a comprehensive description of your concern. Especially for fixing bugs it is crucial that the developers can reproduce your problem. For this reason, entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated. Of course, patches are welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](http://maven.apache.org/guides/development/guide-helping.html). -* Examples +Examples +-------- - To provide you with better understanding on some usages of the Compiler - Plugin, you can take a look into the following examples: +To provide you with better understanding on some usages of the Compiler Plugin, you can take a look into the following examples: - * {{{./examples/compile-using-different-jdk.html}Compile Using A Different JDK}} - - * {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}} - - * {{{./examples/set-compiler-release.html}Compile Using The --release javac Option}} - - * {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory Allocation Enhancement}} - - * {{{./examples/pass-compiler-arguments.html}Pass Compiler Arguments}} - - [] +- [Compile Using A Different JDK](./examples/compile-using-different-jdk.html) +- [Compile Using -source and -target javac Options](./examples/set-compiler-source-and-target.html) +- [Compile Using The \-\-release javac Option](./examples/set-compiler-release.html) +- [Compile Using Memory Allocation Enhancement](./examples/compile-with-memory-enhancements.html) +- [Pass Compiler Arguments](./examples/pass-compiler-arguments.html) diff --git a/src/site/markdown/multirelease.md b/src/site/markdown/multirelease.md index 42aa53da5..12234774e 100644 --- a/src/site/markdown/multirelease.md +++ b/src/site/markdown/multirelease.md @@ -1,79 +1,74 @@ - ------ - Multi Release - ------ - Robert Scholte - ------ - 2018-05-08 - ------ - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Multi Release - - With {{{http://openjdk.java.net/jeps/238}JEP-238}} the support of multirelease jars was introduced. - This means that you can have Java version dependent classes inside one jar. - Based on the runtime it will pick up the best matching version of a class. - -* JEP-238 Introduction - -** The "forward compatibility" problem - - The problem this JEP is trying to solve is to make it possible to use new JDK features even though the codebase must stay compatible with earlier versions. - - Let's try to make this concrete with a real world example: In Java 7 <<>> was added, which was much better in File handling. In those days Maven still required Java 6 to run, however they wanted to make use of these new features when Maven was running on Java 7 or beyond. - - Up until Java 8 there were 2 solutions: - - [[1]] Compile with the targeted JDK (i.e. Java 6) and use reflection. You can ensure that the code is Java 6 compatible, but the reflection-part is hard to verify. - --- - if ( isAtLeastJava7() ) { - Method toPathMethod = f.getClass().getMethod( "toPath" ); - Object toPathInstance = toPathMethod.invoke( f ); - Method isSymbolicLink = Class.forName( "java.nio.file.Files" ).getMethod( "isSymbolicLink" ); - ... - } - else { - // compare absoluteFile with canonicalFile - ... - } +title: Multi Release +author: + - Robert Scholte +date: 2018-05-08 --- - - [[2]] Compile with the required JDK (i.e. Java 7), but use source/target of the lowest version (i.e. 1.6). The danger here is that you cannot ensure that all code is Java 6 compatible. Depending on the code structure {{{https://www.mojohaus.org/animal-sniffer/}Animal Sniffer}} might help. - ---- - if ( isAtLeastJava7() ) { - return Files.isSymbolicLink( f.toPath() ); - } - else { - // compare absoluteFile with canonicalFile - ... - } ---- - - [] - -** The "forward compatibility" solution ---- + + +# Multi Release + +With [JEP-238](http://openjdk.java.net/jeps/238) the support of multirelease jars was introduced. This means that you can have Java version dependent classes inside one jar. Based on the runtime it will pick up the best matching version of a class. + +JEP-238 Introduction +-------------------- + +### The "forward compatibility" problem + +The problem this JEP is trying to solve is to make it possible to use new JDK features even though the codebase must stay compatible with earlier versions. + +Let's try to make this concrete with a real world example: In Java 7 `java.nio` was added, which was much better in File handling. In those days Maven still required Java 6 to run, however they wanted to make use of these new features when Maven was running on Java 7 or beyond. + +Up until Java 8 there were 2 solutions: + +1. Compile with the targeted JDK (i.e. Java 6) and use reflection. You can ensure that the code is Java 6 compatible, but the reflection-part is hard to verify. + + ``` + if ( isAtLeastJava7() ) { + Method toPathMethod = f.getClass().getMethod( "toPath" ); + Object toPathInstance = toPathMethod.invoke( f ); + Method isSymbolicLink = Class.forName( "java.nio.file.Files" ).getMethod( "isSymbolicLink" ); + ... + } + else { + // compare absoluteFile with canonicalFile + ... + } + ``` + +1. Compile with the required JDK (i.e. Java 7), but use source/target of the lowest version (i.e. 1.6). The danger here is that you cannot ensure that all code is Java 6 compatible. Depending on the code structure [Animal Sniffer](https://www.mojohaus.org/animal-sniffer/) might help. + + ``` + if ( isAtLeastJava7() ) { + return Files.isSymbolicLink( f.toPath() ); + } + else { + // compare absoluteFile with canonicalFile + ... + } + ``` + +### The "forward compatibility" solution + +``` A.class B.class C.class @@ -84,137 +79,101 @@ META-INF/MANIFEST.MF { Multi-Release: true } 10/A.class C.class ---- +``` + +With the `Multi-Release: true` flag in the MANIFEST file, the Java runtime will also look inside `META-INF/versions` for version specific classes, otherwise only the base classes are used. + +Challenges +---------- + +The theory behind multi release jars is quite simple, but in practice it can become quite complex. You must ensure that all classes stay in sync; if you add a method to one class, don't forget to add it to the other classes as well. There are some options which should reduce problems at this level: Let all multirelease classes implement an interface and in the basecode instantiate the class but only call the interface methods. The best is to test the \*jar\* with all targeted Java versions. You should think twice before turning your jar into a multi release jar, because such jars can be hard to read, maintain and test. In general applications don't need this, unless it is a widely distributed application and you don't control the targeted Java runtime. Libraries should make a decision based on: do I need this new Java feature? Can I make this Java version the new requirement? Would it be acceptable to solve this with an else/if-statement as mentioned in the first paragraph? + +There are a couple of important facts one should know when creating Multi Release jars. + +- The Java compiler must be called for every different version. The solutions solve this either by having multiple Maven Projects/Modules or by adding extra compiler execution-blocks to the POM (like [older projects with module-info](./examples/module-info.html)). +- The `Multi-Release: true` attribute is only recognized when the classes are in a jar. In other words, you cannot test the classes put in `target/classes/META-INF/versions/${release}/`. +- Up until the moment of writing all IDEs can only have one JDK per Maven Project, whereas with multi release you want to specify it per source folder. +# Pattern 1: [Maven Multimodule](https://github.com/hboutemy/maven-jep238) + +This is the first pattern provided by the Maven team themselves. They had the following requirements: + +- Only one Maven call to compile, test and package the Multi Release jar +- It must work with IDEs +- Developers should not change their way of work / simple configuration + +The only solution to cover the first two bullets was to split the code into a Maven multimodule project. Now every Maven module is just a standard Maven project with close to no specific adjustments in the pom. There are several ways you can run this project: + +- Use the highest required version of the JDK to build the project. You can use `release` to ensure the code only uses matching code and syntax. Since the version-code is isolated you can run surefire with a higher Java runtime. +- Use toolchains if you really want to compile and test with the matching Java version. - With the <<>> flag in the MANIFEST file, the Java runtime will also look inside <<>> for version specific classes, otherwise only the base classes are used. +The downside it that a hierarchical structure is required even though the result is just 1 artifact. -* Challenges - - The theory behind multi release jars is quite simple, but in practice it can become quite complex. You must ensure that all classes stay in sync; if you add a method to one class, don't forget to add it to the other classes as well. - There are some options which should reduce problems at this level: - Let all multirelease classes implement an interface and in the basecode instantiate the class but only call the interface methods. - The best is to test the *jar* with all targeted Java versions. - You should think twice before turning your jar into a multi release jar, because such jars can be hard to read, maintain and test. In general applications don't need this, unless it is a widely distributed application and you don't control the targeted Java runtime. Libraries should make a decision based on: do I need this new Java feature? Can I make this Java version the new requirement? Would it be acceptable to solve this with an else/if-statement as mentioned in the first paragraph? - - There are a couple of important facts one should know when creating Multi Release jars. - - * The Java compiler must be called for every different version. The solutions solve this either by having multiple Maven Projects/Modules or by adding extra compiler execution-blocks to the POM (like {{{./examples/module-info.html}older projects with module-info}}). - - * The <<>> attribute is only recognized when the classes are in a jar. In other words, you cannot test the classes put in <<>>. - - * Up until the moment of writing all IDEs can only have one JDK per Maven Project, whereas with multi release you want to specify it per source folder. - - [] - -Pattern 1: {{{https://github.com/hboutemy/maven-jep238}Maven Multimodule}} - - This is the first pattern provided by the Maven team themselves. They had the following requirements: - - * Only one Maven call to compile, test and package the Multi Release jar +# Pattern 2: [Multi Project](http://word-bits.flurg.com/multrelease-jars/) - * It must work with IDEs +This solution is a response to the previous Maven multimodule setup. The requirements are almost the same - * Developers should not change their way of work / simple configuration - - [] - - The only solution to cover the first two bullets was to split the code into a Maven multimodule project. - Now every Maven module is just a standard Maven project with close to no specific adjustments in the pom. - There are several ways you can run this project: - - * Use the highest required version of the JDK to build the project. You can use <<>> to ensure the code only uses matching code and syntax. Since the version-code is isolated you can run surefire with a higher Java runtime. - - * Use toolchains if you really want to compile and test with the matching Java version. - - [] - - The downside it that a hierarchical structure is required even though the result is just 1 artifact. - -Pattern 2: {{{http://word-bits.flurg.com/multrelease-jars/}Multi Project}} +- Do not require the project to switch to a multi-module format +- Developers should not change their way of work / simple configuration - This solution is a response to the previous Maven multimodule setup. The requirements are almost the same +The first requirements implies that the projects now are separate Maven projects. One Maven project contains the base-code and in the end this will also be the multirelease jar. When building such project for the first time, you'll need to call Maven at least 3 times: first the base needs to be compiled, next all version specific projects must be built and finally the main project needs to be built again, now including the version specific classes extracted from their jars. This setup is compact, but has cyclic dependencies. This requires some tricks and makes releasing a bit more complicated. Another downside is that you must install SNAPSHOTs to your local repository and when doing a release it requires 2 releases of the base project, one to prepare for the multirelease-nine and one with the released multirelease-nine. - * Do not require the project to switch to a multi-module format +# Pattern 3: Single Project - * Developers should not change their way of work / simple configuration - - [] +By now there are 3 solutions, each inspired by their previous version. - The first requirements implies that the projects now are separate Maven projects. - One Maven project contains the base-code and in the end this will also be the multirelease jar. - When building such project for the first time, you'll need to call Maven at least 3 times: first the base needs to be compiled, next all version specific projects must be built and finally the main project needs to be built again, now including the version specific classes extracted from their jars. - This setup is compact, but has cyclic dependencies. This requires some tricks and makes releasing a bit more complicated. - Another downside is that you must install SNAPSHOTs to your local repository and when doing a release it requires 2 releases of the base project, one to prepare for the multirelease-nine and one with the released multirelease-nine. - -Pattern 3: Single Project +Main goal: - By now there are 3 solutions, each inspired by their previous version. +- Do not require the project to switch to a multi-module format +- Only one Maven call to compile and package the Multi Release jar - Main goal: - - * Do not require the project to switch to a multi-module format - - * Only one Maven call to compile and package the Multi Release jar - - [] +[Single Project](http://in.relation.to/2017/02/13/building-multi-release-jars-with-maven/) +------------------------------------------------------------------------------------------ -* {{{http://in.relation.to/2017/02/13/building-multi-release-jars-with-maven/}Single Project}} +In this case everything stays inside one Maven project. Every specific Java version gets its own source folder and output folder, and just before packaging they are combined. What's not covered is how to test every class. - In this case everything stays inside one Maven project. - Every specific Java version gets its own source folder and output folder, and just before packaging they are combined. - What's not covered is how to test every class. +[Multi-Release Parent](http://www.russgold.net/sw/2018/04/easier-than-it-looks/) +-------------------------------------------------------------------------------- -* {{{http://www.russgold.net/sw/2018/04/easier-than-it-looks/}Multi-Release Parent}} +This approach replaces the maven-ant-plugin with extra exucution blocks in the maven-compiler-plugin. It has been setup as a parent, so other projects can use it. It uses toolchains to be able to build all classes with their matching Java version, so you always get the multi release jar. Because of the huge configuration and since Maven doesn't support mixins yet, it makes sense to put it all in a parent. However, at the same time surefire is only called once. - This approach replaces the maven-ant-plugin with extra exucution blocks in the maven-compiler-plugin. It has been setup as a parent, so other projects can use it. It uses toolchains to be able to build all classes with their matching Java version, so you always get the multi release jar. Because of the huge configuration and since Maven doesn't support mixins yet, it makes sense to put it all in a parent. - However, at the same time surefire is only called once. +[CI-server](https://github.com/codehaus-plexus/plexus-languages) +---------------------------------------------------------------- -* {{{https://github.com/codehaus-plexus/plexus-languages}CI-server}} +This approach reduces the previous solution by only specifying execution blocks for sources for a specific Java version. It doesn't use toolchains, but the JDK used to run Maven. This means that only the sources up to the specific Java version are compiled and tested. This solution relies heavily on a CI-server where every targeted Java version is available. If the CI-server succeeds, then all classes are tested with their matching Java version. - This approach reduces the previous solution by only specifying execution blocks for sources for a specific Java version. It doesn't use toolchains, but the JDK used to run Maven. This means that only the sources up to the specific Java version are compiled and tested. - This solution relies heavily on a CI-server where every targeted Java version is available. If the CI-server succeeds, then all classes are tested with their matching Java version. +# Pattern 4: [Maven extension + plugin](https://github.com/metlos/multi-release-jar-maven-plugin) -Pattern 4: {{{https://github.com/metlos/multi-release-jar-maven-plugin}Maven extension + plugin}} +This approach introduces a new packaging type and an extra plugin takes care of the multiple executions of the maven-compiler-plugin, but these are now handled by the `perReleaseConfiguration` of the `multi-release-jar-maven-plugin`. What's not covered is how to test every class. - This approach introduces a new packaging type and an extra plugin takes care of the multiple executions of the maven-compiler-plugin, but these are now - handled by the <<>> of the <<>>. What's not covered is how to test every class. +# Patterns Summary -Patterns Summary +For every pattern there are integration tests created, based on the same set of sourcefiles. See [https://github.com/apache/maven-compiler-plugin/tree/master/src/it/multirelease-patterns](https://github.com/apache/maven-compiler-plugin/tree/master/src/it/multirelease-patterns) - For every pattern there are integration tests created, based on the same set of sourcefiles. See {{https://github.com/apache/maven-compiler-plugin/tree/master/src/it/multirelease-patterns}} +||Maven Multimodule|Multi Project|Single project (runtime)|Single project (toolchains)|Maven extension+plugin| +|:---:|:---:|:---:|:---:|:---:|:---:| +|\# projects|1|1 + #javaVersions|1|1|1| +|\# builds to package|1|2 + #javaVersions|1|1|1| +|\# builds/project to test|1|1|#javaVersions|1|N/A (a)| +|Simple Maven Project Layout|No|Yes|Yes|Yes|Yes| +|Additional POM adjustments(b)|1 (c)|#javaVersions(d)|#javaVersions(e)|??(f)|#javaVersions(g)| +|Include module descriptor|No (h)|No (h)|Yes|Yes|Yes| +|IDE support (i)|Yes|Yes|No|No|No| -*-------------------------------*-----------------------*-------------------------*---------------------------*------------------------------*--------------------------------* -|| || Maven Multimodule || Multi Project || Single project (runtime) || Single project (toolchains) || Maven extension+plugin || -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| # projects | 1 | 1 + #javaVersions | 1 | 1 | 1 | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| # builds to package | 1 | 2 + #javaVersions | 1 | 1 | 1 | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| # builds/project to test | 1 | 1 | #javaVersions | 1 | N/A (a) | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| Simple Maven Project Layout | No | Yes | Yes | Yes | Yes | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| Additional POM adjustments(b) | 1 (c) | #javaVersions(d) | #javaVersions(e) | ??(f) | #javaVersions(g) | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| Include module descriptor | No (h) | No (h) | Yes | Yes | Yes | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ -| IDE support (i) | Yes | Yes | No | No | No | -*-------------------------------+-----------------------+-------------------------+---------------------------+------------------------------*--------------------------------+ +(a) Project can only be executed with highest required JDK, hence you can't test the code for all JDKs - (a) Project can only be executed with highest required JDK, hence you can't test the code for all JDKs +(b) Additional POM adjustments: # of executions added to the default lifecycle. This reflects the complexity of the POM. - (b) Additional POM adjustments: # of executions added to the default lifecycle. This reflects the complexity of the POM. +(c) Maven multimodule uses maven-assembly-plugin to assemble to multirelease jar - (c) Maven multimodule uses maven-assembly-plugin to assemble to multirelease jar +(d) Multi project uses the maven-dependency-plugin to unpack java specific dependency to its matching outputDirectory - (d) Multi project uses the maven-dependency-plugin to unpack java specific dependency to its matching outputDirectory +(e) There's a profile for every Java version required which contains an extra execution-block for that Java version. - (e) There's a profile for every Java version required which contains an extra execution-block for that Java version. +(f) - (f) +(g) Maven extension+plugin hides the multiple executions in the `perReleaseConfiguration` configuration - (g) Maven extension+plugin hides the multiple executions in the <<>> configuration +(h) Requires a \-\-patch-module on a dependency - (h) Requires a --patch-module on a dependency +(i) IDE Support: All classes are recognized and can be tested within the IDE. - (i) IDE Support: All classes are recognized and can be tested within the IDE. diff --git a/src/site/markdown/non-javac-compilers.md.vm b/src/site/markdown/non-javac-compilers.md.vm index 95667bdba..793c9aadc 100644 --- a/src/site/markdown/non-javac-compilers.md.vm +++ b/src/site/markdown/non-javac-compilers.md.vm @@ -1,65 +1,50 @@ - ------ - Using Non-Javac Compilers - ------ - Edwin Punzalan - ------ - 2006-07-19 - ------ +--- +title: Using Non-Javac Compilers +author: + - Edwin Punzalan +date: 2006-07-19 +--- -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. + -Using Non-Javac Compilers +# Using Non-Javac Compilers - Contrary to this plugin's name, the Compiler Plugin does not compile the - sources of your project by itself. To compile, the Compiler Plugin uses - another class to compile them. +Contrary to this plugin's name, the Compiler Plugin does not compile the sources of your project by itself. To compile, the Compiler Plugin uses another class to compile them. - The parameter <<>> determines which class will be used. +The parameter `compilerId` determines which class will be used. - Currently, the Compiler Plugin is bundled with the <<>> compiler - with artifactId <<>> version <<${plexusCompilerVersion}>>, - which can be seen as one of the dependencies declared inside the Compiler Plugin's POM. +Currently, the Compiler Plugin is bundled with the `javac` compiler with artifactId `plexus-compiler-javac` version **${plexusCompilerVersion}**, which can be seen as one of the dependencies declared inside the Compiler Plugin's POM. - {{{https://codehaus-plexus.github.io/plexus-compiler/}Plexus Compiler}} component - has some other compiler Ids available under the groupId <<>>: +[Plexus Compiler](https://codehaus-plexus.github.io/plexus-compiler/) component has some other compiler Ids available under the groupId `org.codehaus.plexus`: - * <<>> with artifactId <<>> - <>: <<>> and <<>> +- `aspectj` with artifactId `plexus-compiler-aspectj` - **requires**: `JDK 17+` and `Maven 3.9.6 +` +- `csharp` with artifactId `plexus-compiler-csharp` - **requires**: `JDK 8+` +- `eclipse` with artifactId `plexus-compiler-eclipse` - **requires**: `JDK 17+` and `Maven 3.9.6 +` +- `javac-with-errorprone` with artifactId `plexus-compiler-javac-errorprone` - **requires**: `JDK 11+` - * <<>> with artifactId <<>> - <>: <<>> +Using The Other Plexus Compilers +-------------------------------- - * <<>> with artifactId <<>> - <>: <<>> and <<>> +To use any of the non-javac compilers, you need to make the artifact available in the classpath when the Compiler Plugin runs. This is possible by adding the dependency when declaring the plugin in your project's `pom.xml`. The example below shows how to use the `csharp` compiler: - * <<>> with artifactId <<>> - <>: <<>> - - [] - -* Using The Other Plexus Compilers - - To use any of the non-javac compilers, you need to make the artifact available - in the classpath when the Compiler Plugin runs. This is possible by adding the - dependency when declaring the plugin in your project's <<>>. The example - below shows how to use the <<>> compiler: - -+----- +```unknown [...] @@ -82,4 +67,5 @@ Using Non-Javac Compilers [...] -+----- +``` + diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm index e038356e6..8511e91df 100644 --- a/src/site/markdown/usage.md.vm +++ b/src/site/markdown/usage.md.vm @@ -1,60 +1,54 @@ - ------ - Usage - ------ - Edwin Punzalan - ------ - 2006-07-05 - ------ +--- +title: Usage +author: + - Edwin Punzalan +date: 2006-07-05 +--- -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you under the Apache License, Version 2.0 (the -~~ "License"); you may not use this file except in compliance -~~ with the License. You may obtain a copy of the License at -~~ -~~ http://www.apache.org/licenses/LICENSE-2.0 -~~ -~~ Unless required by applicable law or agreed to in writing, -~~ software distributed under the License is distributed on an -~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -~~ KIND, either express or implied. See the License for the -~~ specific language governing permissions and limitations -~~ under the License. + -* Compiling Your Java Sources +# Usage - The goals for the Compiler Plugin are bound to their respective phases in the - build lifecycle. So to compile your sources, you need only to tell maven - until which lifecycle to execute. The following will compile your sources: +Compiling Your Java Sources +--------------------------- -+----- +The goals for the Compiler Plugin are bound to their respective phases in the build lifecycle. So to compile your sources, you need only to tell maven until which lifecycle to execute. The following will compile your sources: + +```unknown mvn compile -+----- +``` - To compile your test sources, you'll do: +To compile your test sources, you'll do: -+----- +```unknown mvn test-compile -+----- +``` - The above command will execute both <<>> and - <<>> since the <<>> phase happens a few phases - before the <<>> phase. +The above command will execute both `compiler:compile` and `compiler:testCompile` since the `compile` phase happens a few phases before the `test-compile` phase. -* Configuring Your Compiler Plugin +Configuring Your Compiler Plugin +-------------------------------- - Since the Compiler Plugin executes automatically during their phases, you - don't have to put <<>> unlike many other plugins. However, you - should specify the version of the Compiler Plugin. +Since the Compiler Plugin executes automatically during their phases, you don't have to put `executions` unlike many other plugins. However, you should specify the version of the Compiler Plugin. -+----- +```unknown ... @@ -73,5 +67,5 @@ mvn test-compile ... -+----- +```