Skip to content

Commit 5449407

Browse files
BukamaBukama
authored
[MCOMPILER-529] Update docs about version schema (Maven 3)
This PR updates several parts of the documentation for Maven 3 based on JDK 8 and aligns the docs to the new Java version schema. In particular on the front page it's mentioned that "8" is the default, where in the code it's actual "1.8" - but I wanted to keep docs consistent here.
1 parent 01d5b88 commit 5449407

4 files changed

Lines changed: 34 additions & 28 deletions

File tree

‎src/site/apt/examples/set-compiler-release.apt.vm‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@
2828

2929
Setting the <<<--release>>> of the Java Compiler
3030

31-
Starting JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
31+
Starting with JDK 9, the <<<javac>>> executable can accept the <<<--release>>>
3232
option to specify against which Java SE release you want to build the project.
3333
For example, you have JDK 11 installed and used by Maven, but you want to
3434
build the project against Java 8.
3535
The <<<--release>>> option ensures that the code is compiled following the
3636
rules of the programming language of the specified release, and that generated
3737
classes target the release as well as the public API of that release. This
38-
means that, unlike the
38+
means that, unlike the old
3939
{{{../examples/set-compiler-source-and-target.html}<<<-source>>> and <<<-target>>> options}},
4040
the compiler will detect and generate an error when using APIs that don't exist
4141
in previous releases of Java SE.
@@ -76,18 +76,20 @@ Setting the <<<--release>>> of the Java Compiler
7676
</project>
7777
+-----
7878

79-
<<Note:>> The value in the <<<release>>> parameter follows the new version naming scheme adopted
80-
since Java 9. As such, the release number does not start with 1.x anymore. Also note that the
79+
<<Note:>> The value in the <<<release>>> parameter follows
80+
{{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}} adopted since Java 9.
81+
As such, the release number does not start with 1.x anymore. Also note that the
8182
supported <<<release>>> targets include the release of the currently used JDK plus a limited number
8283
of previous releases.
8384

8485
* Usage on JDK 8
8586

86-
The <<<--release>>> option is not supported using JDK 8. To enable a project that targets Java 8
87-
to be built using JDK 8 and also JDK 9 or later requires the conditional usage of the
88-
<<<--release>>> option.
87+
The <<<--release>>> option is not supported using JDK 8.
88+
However, since Compiler plugin version <<<3.13.0>>> you can use the <<<release>>> property also on JDK 8.
89+
The plugin will convert it to <<<source>>> and <<<target>>> automatically.
8990

90-
Conditional parametrization is required for the Compiler Plugin version below <<<3.13.0>>>
91+
To enable a project that targets Java 8 to be built using JDK 8 and also JDK 9 or later requires the conditional
92+
usage of the <<<--release>>> option, when using a plugin version below <<<3.13.0>>>
9193
or compilerId different that <<<javac>>>.
9294

9395
This may be done through the use of a profile:

‎src/site/apt/examples/set-compiler-source-and-target.apt.vm‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,21 +28,25 @@
2828

2929
Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
3030

31+
(If you're are using version <<<3.13.0>>> or newer of the Compiler Plugin, use the recommended
32+
{{{../examples/set-compiler-release.html}<<<maven.compiler.release>>> property}}.)
33+
3134
Sometimes when you may need to compile a certain project to a different
3235
version than what you are currently using. The <<<javac>>> can accept
3336
such command using <<<-source>>> and <<<-target>>>. The Compiler Plugin
3437
can also be configured to provide these options during compilation.
38+
You have to set the version following {{{https://openjdk.org/jeps/223}Java's new Version-String Scheme (JEP 223)}}}.
3539

36-
For example, if you want to use the Java 8 language features (<<<-source 1.8>>>)
37-
and also want the compiled classes to be compatible with JVM 1.8 (<<<-target 1.8>>>),
38-
you can either add the two following properties, which are the default property names for the plugin parameters:
40+
For example, if you want to use the Java 8 language features and also want the compiled classes to be compatible
41+
with JVM 8 (former 1.8) you can either add the two following properties, which are the default property names
42+
for the plugin parameters:
3943

4044
+-----
4145
<project>
4246
[...]
4347
<properties>
44-
<maven.compiler.source>1.8</maven.compiler.source>
45-
<maven.compiler.target>1.8</maven.compiler.target>
48+
<maven.compiler.source>8</maven.compiler.source>
49+
<maven.compiler.target>8</maven.compiler.target>
4650
</properties>
4751
[...]
4852
</project>
@@ -61,8 +65,8 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
6165
<artifactId>maven-compiler-plugin</artifactId>
6266
<version>${project.version}</version>
6367
<configuration>
64-
<source>1.8</source>
65-
<target>1.8</target>
68+
<source>8</source>
69+
<target>8</target>
6670
</configuration>
6771
</plugin>
6872
</plugins>
@@ -79,6 +83,10 @@ Setting the <<<-source>>> and <<<-target>>> of the Java Compiler
7983
{{{http://www.mojohaus.org/animal-sniffer/animal-sniffer-maven-plugin/}Animal Sniffer Maven Plugin}}
8084
to verify your code doesn't use unintended APIs, or better yet use the
8185
{{{../examples/set-compiler-release.html}<<<release>>> option supported since JDK 9}}.
86+
Since plugin version <<<3.13.0>>> you can use the <<<release>>> property also on JDK 8.
87+
The compiler plugin will convert it to <<<source>>> and <<<target>>> automatically.
88+
8289
In the same way, setting the <<<source>>> option does not guarantee that your code actually compiles on a JDK with
8390
the specified version. To compile your code with a specific JDK version, different than the one used to launch Maven,
8491
refer to the {{{../examples/compile-using-different-jdk.html}Compile Using A Different JDK}} example.
92+

‎src/site/apt/index.apt.vm‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,16 @@
2929
${project.name}
3030

3131
The Compiler Plugin is used to compile the sources of your project. The
32-
default compiler used to compile Java sources is javax.tools.JavaCompiler.
33-
If you want to force the plugin to use <<<javac>>>, you must configure the plugin option {{{./compile-mojo.html#forceJavacCompilerUse}<<<forceJavacCompilerUse>>>}}.
32+
default compiler used to compile Java sources is <<<javac>>>.
33+
If you want to use another compiler, refer to the {{{./non-javac-compilers} guide: Using Non-Javac Compilers}}.
3434

35-
Also note that at present the default <<<source>>> setting is <<<1.8>>> and the default <<<target>>>
36-
setting is <<<1.8>>>, independently of the JDK you run Maven with.
37-
You are highly encouraged to change these defaults by setting <<<source>>> and <<<target>>>
38-
as described in
39-
{{{./examples/set-compiler-source-and-target.html}Setting the -source and -target of the Java Compiler}}.
40-
41-
Other compilers than <<<javac>>> can be used and work has already started
42-
on AspectJ, .NET, and C#.
35+
At present the default <<<source>>> and the default <<<target>>> setting are both <<<8>>>,
36+
independently of the JDK you run Maven with.
37+
You are highly encouraged to change these defaults by setting the <<<release>>> option as described in the
38+
{{{./examples/set-compiler-release.html}guide: Compile Using The <<<--release>>> javac Option}}.
4339

4440
<<NOTE:>> <To know more about the JDK javac, please see:
45-
{{https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javac.html}}.>
41+
{{https://docs.oracle.com/javase/8/docs/technotes/guides/javac/index.html}}.>
4642

4743
* Goals Overview
4844

@@ -83,7 +79,7 @@ ${project.name}
8379

8480
* {{{./examples/set-compiler-source-and-target.html}Compile Using -source and -target javac Options}}
8581

86-
* {{{./examples/set-compiler-release.html}Compile Using the --release javac Option (supported since JDK 9)}}
82+
* {{{./examples/set-compiler-release.html}Compile Using The --release javac Option}}
8783

8884
* {{{./examples/compile-with-memory-enhancements.html}Compile Using Memory Allocation Enhancement}}
8985

‎src/site/site.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ under the License.
3535
<menu name="Examples">
3636
<item name="Compile Using A Different JDK" href="examples/compile-using-different-jdk.html"/>
3737
<item name="Compile Using -source and -target javac Options" href="examples/set-compiler-source-and-target.html"/>
38-
<item name="Compile Using the --release javac Option (JDK 9+)" href="examples/set-compiler-release.html"/>
38+
<item name="Compile Using the --release javac Option" href="examples/set-compiler-release.html"/>
3939
<item name="Compile Using Memory Allocation Enhancements" href="examples/compile-with-memory-enhancements.html"/>
4040
<item name="Pass Compiler Arguments" href="examples/pass-compiler-arguments.html"/>
4141
<item name="Non-javac compilerIds" href="non-javac-compilers.html"/>

0 commit comments

Comments
 (0)