This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch updatesite in repository https://gitbox.apache.org/repos/asf/maven-jlink-plugin.git
commit ea6a65c4b7ebf1ce901e41335242ef28614354cf Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Mon Jan 29 23:01:18 2024 +0100 Migrate site docs to Markdown --- pom.xml | 12 -- src/site/apt/index.apt.vm | 59 ---------- src/site/apt/usage.apt.vm | 267 --------------------------------------------- src/site/markdown/index.md | 42 +++++++ src/site/markdown/usage.md | 231 +++++++++++++++++++++++++++++++++++++++ src/site/site.xml | 13 +-- 6 files changed, 276 insertions(+), 348 deletions(-) diff --git a/pom.xml b/pom.xml index 0913337..ab43704 100644 --- a/pom.xml +++ b/pom.xml @@ -197,18 +197,6 @@ </plugins> </build> - <reporting> - <plugins> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-plugin-plugin</artifactId> - </plugin> - <plugin> - <groupId>org.apache.maven.plugins</groupId> - <artifactId>maven-invoker-plugin</artifactId> - </plugin> - </plugins> - </reporting> <profiles> <profile> <id>run-its</id> diff --git a/src/site/apt/index.apt.vm b/src/site/apt/index.apt.vm deleted file mode 100644 index 2ed3d50..0000000 --- a/src/site/apt/index.apt.vm +++ /dev/null @@ -1,59 +0,0 @@ - ------ - Introduction - ------ - Karl Heinz Marbaise - ------ - 2017-08-17 - ------ - -~~ 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 - -${project.name} - - The JLink Plugin creates {{{https://openjdk.java.net/jeps/220}Modular Java Run-Time Images}} - via {{{https://openjdk.java.net/jeps/282}jlink}}. - -* Goals Overview - - The JLink Plugin has two goals: - - * {{{./jlink-mojo.html}jlink:jlink}} creates a Java Run Time Image from <<jar>>/<<jmod>> files. - - * {{{./help-mojo.html}jlink:help}} displays help information for the maven-jlink-plugin. - - [] - -* Usage - - General instructions on how to use the JLink Plugin can be found on the {{{./usage.html}usage page}}. - - If you 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}}. - - If 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}}. diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm deleted file mode 100644 index be84abe..0000000 --- a/src/site/apt/usage.apt.vm +++ /dev/null @@ -1,267 +0,0 @@ - ------ - Usage - ------ - Karl Heinz Marbaise <[email protected]> - ------ - 2017-09-01 - -~~ Copyright 2006 The Apache Software Foundation. -~~ -~~ Licensed 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 - - -Usage - -* Introduction - - The Maven JLink plugin is used to create {{{https://openjdk.java.net/jeps/220}Modular Run-Time Images}} with - JDK 9. - - The intended artifacts to be linked together into a Modular Run-Time Image - are the <<jmod>> and <<jar>> files. JMod files can be created by using the - {{{../maven-jmod-plugin/}Maven JMod Plugin}} and <<jar>> files can be - created by using the {{{../maven-jar-plugin/}Maven JAR Plugin}}. - -* Configuration of the Maven JLink Plugin - - To use the Maven JLink Plugin you have to configure it as an <<<extensions>>> which means - the configuration in your pom file has to look like this: - -+----- -<project> - [...] - <build> - [...] - <plugins> - [...] - <plugin> - <artifactId>maven-jlink-plugin</artifactId> - <version>${project.version}</version> - <extensions>true</extensions> - <configuration> - <!-- configuration elements goes here --> - </configuration> - </plugin> - [...] -</project> -+----- - - The configuration element contains the configuration for the plugin - {{{https://maven.apache.org/guides/mini/guide-configuring-plugins.html}like any other Maven plugin}}. - The different elements which can be configured for this plugin can identified by the - {{{./plugin-info.html}goals documentation}}. - -* Requirements - - Based on the foundation of the plugin it is required to have JDK 9 installed. This means - either you have it configured via <<JAVA_HOME>> which means to run the whole - Maven build with JDK 9 or via <<Toolchains>>. - - Howto configure Maven related to Toolchains can be read in the - {{{https://maven.apache.org/guides/mini/guide-using-toolchains.html}Toolchains documentation}}. - - -* Usage of the Maven JLink Plugin - - You can use the maven-jlink-plugin the same way you use the maven-jar-plugin, maven-war-plugin, - maven-assembly-plugin or any other artifact-generating plugin. - Create a separate module for the artifact generation and specify - <<< <packaging>jlink</packaging> >>>. - - Another way to use this plugin is to add it to an existing project. - In this case you want to add an explicit execution in the <<<package>>> phase. - - Let’s assume you have a multi module structure that contains two modules <<mod-1>> and <<mod-2>> - which you like to put into the resulting Run Time Image. - - The parent of the multi module looks similar like this: - -+----- -<project ...> - <modelVersion>4.0.0</modelVersion> - <parent> - <groupId>com.corporate.maven</groupId> - <artifactId>maven-parent</artifactId> - <version>2.3.1</version> - </parent> - <groupId>com.corporate.project</groupId> - <artifactId>parent</artifactId> - <version>1.0-SNAPSHOT</version> - <packaging>pom</packaging> - [...] - <modules> - <module>mod-1</module> - <module>mod-2</module> - </modules> - [...] -</project> -+----- - - A directory structure of such a project looks like this: - -+----- -. -├── mod-1 -│ └── src -└── mod-2 - └── src -+----- - - The <<mod-1>> module looks similar like this: - -+----- -<project ...> - <modelVersion>4.0.0</modelVersion> - <parent> - <groupId>com.corporate.project</groupId> - <artifactId>parent</artifactId> - <version>1.0-SNAPSHOT</version> - </parent> - <artifactId>mod-1</artifactId> - [...] -</project> -+----- - - The <<mod-2>> module looks similar like this: - -+----- -<project ...> - <modelVersion>4.0.0</modelVersion> - <parent> - <groupId>com.corporate.project</groupId> - <artifactId>parent</artifactId> - <version>1.0-SNAPSHOT</version> - </parent> - <artifactId>mod-2</artifactId> - [...] -</project> -+----- - - If you like to create a Java Run Time Image of your modules you have to create a - separate module <<mod-jlink>> which contains the configuration to create the Run - Time Image which looks similar like this: - -+----- -<project ...> - <modelVersion>4.0.0</modelVersion> - <parent> - <groupId>com.corporate.project</groupId> - <artifactId>parent</artifactId> - <version>1.0-SNAPSHOT</version> - </parent> - <packaging>jlink</packaging> - <artifactId>mod-jlink</artifactId> - [...] -</project> -+----- - - The directory structure now looks like this: - -+----- -. -├── mod-1 -│ └── src -├── mod-2 -│ └── src -└── mod-jlink - └── src -+----- - - Before you can do this you have to add the configuration to the parent like shown - in {{{Configuration_of_the_Maven_JLink_Plugin}Configuration of the Maven JLink Plugin}}. - - Now you need to define which modules should be linked into the resulting Java Run Time Image which simply - can be done by defining the modules as dependencies to your <<mod-jlink>> module like this: - -+----- -<project ...> - <modelVersion>4.0.0</modelVersion> - <parent> - <groupId>com.corporate.project</groupId> - <artifactId>parent</artifactId> - <version>1.0-SNAPSHOT</version> - </parent> - <packaging>jlink</packaging> - <artifactId>mod-jlink</artifactId> - <dependencies> - <dependency> - <groupId>com.corporate.project</groupId> - <artifactId>mod-1</artifactId> - <version>\${project.version}</version> - </dependency> - <dependency> - <groupId>com.corporate.project</groupId> - <artifactId>mod-2</artifactId> - <version>\${project.version}</version> - </dependency> - </dependencies> - [...] -</project> -+----- - - - After you have added the appropriate configuration you can simply create the Java Run Time Image by - calling from the root of your multi module project like this: - -+---- -mvn clean package -+---- - - There are some output lines similar like this: - -+---- -[INFO] -[INFO] --- maven-jlink-plugin:${project.version}:jlink (default-jlink) @ mod-jlink --- -[INFO] Toolchain in maven-jlink-plugin: jlink [ /.../jdk1.9.0_ea+181.jdk/Contents/Home/bin/jlink ] -[INFO] The following dependencies will be linked into the runtime image: -[INFO] -> module: com.soebes.nine.one.jar ( /.../mod-1/target/mod-1-1.0-SNAPSHOT.jar ) -[INFO] -> module: com.soebes.nine.two.jar ( /.../mod-2/target/mod-2-1.0-SNAPSHOT.jar ) -[INFO] Building zip: /.../mod-jlink/target/mod-jlink-1.0-SNAPSHOT.zip -[INFO] -+---- - - If you like to install the resulting Java Run Time Image files into your local cache - you can achieve this by using: - -+---- -mvn clean install -+---- - - or if you like to deploy the resulting artifacts to a remote repository you have to use: - -+---- -mvn clean deploy -+---- - - At the moment the resulting Java Run Time Image is packaged into a <<zip>> archive which - used to transport the whole structure which is created by <<jlink>> to a repository. - - The resulting - {{{https://docs.oracle.com/javase/9/install/installed-directory-structure-jdk-and-jre.htm}Java Run Time Image directory structure}} - looks like this: - -+--- -jlink/ -├── bin -├── conf -├── include -├── legal -├── lib -└── release -+--- - - - diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md new file mode 100644 index 0000000..260cff9 --- /dev/null +++ b/src/site/markdown/index.md @@ -0,0 +1,42 @@ +<!-- +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. +--> + +# Apache Maven JLink Plugin + +The JLink Plugin is intended to create a [Modular Java Run-Time Images](https://openjdk.java.net/jeps/220) via [jlink](https://openjdk.java.net/jeps/282). + +## Goals Overview + +The JLink Plugin has two goals: + +- [jlink:jlink](./jlink-mojo.html) create a Java Run Time Image from **jar/jmod** files. +- [jlink:help](./help-mojo.html) displays help information on maven-jlink-plugin. + +## Usage + +General instructions on how to use the JLink 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](./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 like the plugin is missing a feature or has a defect, you can fill 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 wel [...] + +## Examples + +To provide you with better understanding on some usages of the Maven JLink Plugin, you can take a look into the following [examples](./usage.html) + diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md new file mode 100644 index 0000000..25005cd --- /dev/null +++ b/src/site/markdown/usage.md @@ -0,0 +1,231 @@ +<!-- +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. +--> +# Usage + +## Introduction + +The Maven JLink plugin is used to create [Modular Run-Time Images](https://openjdk.java.net/jeps/220) with JDK 9. + +The intended artifacts to be linked together into a Modular Run-Time Image are the **jmod** and **jar** files. JMod files can be created by using the [Maven JMod Plugin](../maven-jmod-plugin/) and **jar** files can be created by using the [Maven JAR Plugin](../maven-jar-plugin/). + +## Configuration of the Maven JLink Plugin + +To use the Maven JLink Plugin you have to configure it as an `extensions` which means the configuration in your pom file has to look like this: + +``` +<project> + [...] + <build> + [...] + <plugins> + [...] + <plugin> + <artifactId>maven-jlink-plugin</artifactId> + <version>${project.version}</version> + <extensions>true</extensions> + <configuration> + <!-- configuration elements goes here --> + </configuration> + </plugin> + [...] +</project> +``` + +The configuration element contains the configuration for the plugin [like any other Maven plugin](https://maven.apache.org/guides/mini/guide-configuring-plugins.html). The different elements which can be configured for this plugin can identified by the [goals documentation](./plugin-info.html). + +## Requirements + +Based on the foundation of the plugin it is required to have JDK 11 or newer installed. This means either you have it configured via **JAVA_HOME** which means to run the whole Maven build with JDK 11+ or via **Toolchains**. + +Howto configure Maven related to Toolchains can be read in the [Toolchains documentation](https://maven.apache.org/guides/mini/guide-using-toolchains.html). + +## Usage of the Maven JLink Plugin + +You can use the maven-jlink-plugin the same way you use the maven-jar-plugin, maven-war-plugin, maven-assembly-plugin or any other artifact-generating plugin. Create a separate module for the artifact generation and specify `<packaging>jlink</packaging>`. + +Another way to use this plugin is to add it to an existing project. In this case you want to add an explicit execution in the `package` phase. + +Let’s assume you have a multi module structure that contains two modules **mod-1** and **mod-2** which you like to put into the resulting Run Time Image. + +The parent of the multi module looks similar like this: + +``` +<project ...> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>com.corporate.maven</groupId> + <artifactId>maven-parent</artifactId> + <version>2.3.1</version> + </parent> + <groupId>com.corporate.project</groupId> + <artifactId>parent</artifactId> + <version>1.0-SNAPSHOT</version> + <packaging>pom</packaging> + [...] + <modules> + <module>mod-1</module> + <module>mod-2</module> + </modules> + [...] +</project> +``` + +A directory structure of such a project looks like this: + +``` +. +├── mod-1 +│ └── src +└── mod-2 + └── src +``` + +The **mod-1** module looks similar like this: + +``` +<project ...> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>com.corporate.project</groupId> + <artifactId>parent</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + <artifactId>mod-1</artifactId> + [...] +</project> +``` + +The **mod-2** module looks similar like this: + +``` +<project ...> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>com.corporate.project</groupId> + <artifactId>parent</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + <artifactId>mod-2</artifactId> + [...] +</project> +``` + +If you like to create a Java Run Time Image of your modules you have to create a separate module **mod-jlink** which contains the configuration to create the Run Time Image which looks similar like this: + +``` +<project ...> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>com.corporate.project</groupId> + <artifactId>parent</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + <packaging>jlink</packaging> + <artifactId>mod-jlink</artifactId> + [...] +</project> +``` + +The directory structure now looks like this: + +``` +. +├── mod-1 +│ └── src +├── mod-2 +│ └── src +└── mod-jlink + └── src +``` + +Before you can do this you have to add the configuration to the parent like shown in [Configuration of the Maven JLink Plugin](Configuration\_of\_the\_Maven\_JLink\_Plugin). + +Now you need to define which modules should be linked into the resulting Java Run Time Image which simply can be done by defining the modules as dependencies to your **mod-jlink** module like this: + +``` +<project ...> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>com.corporate.project</groupId> + <artifactId>parent</artifactId> + <version>1.0-SNAPSHOT</version> + </parent> + <packaging>jlink</packaging> + <artifactId>mod-jlink</artifactId> + <dependencies> + <dependency> + <groupId>com.corporate.project</groupId> + <artifactId>mod-1</artifactId> + <version>\${project.version}</version> + </dependency> + <dependency> + <groupId>com.corporate.project</groupId> + <artifactId>mod-2</artifactId> + <version>\${project.version}</version> + </dependency> + </dependencies> + [...] +</project> +``` + +After you have added the appropriate configuration you can simply create the Java Run Time Image by calling from the root of your multi module project like this: + +``` +mvn clean package +``` + +There are some output lines similar like this: + +``` +[INFO] +[INFO] --- maven-jlink-plugin:${project.version}:jlink (default-jlink) @ mod-jlink --- +[INFO] Toolchain in maven-jlink-plugin: jlink [ /.../openjdk/21/libexec/openjdk.jdk/Contents/Home/Contents/Home/bin/jlink ] +[INFO] The following dependencies will be linked into the runtime image: +[INFO] -> module: com.soebes.nine.one.jar ( /.../mod-1/target/mod-1-1.0-SNAPSHOT.jar ) +[INFO] -> module: com.soebes.nine.two.jar ( /.../mod-2/target/mod-2-1.0-SNAPSHOT.jar ) +[INFO] Building zip: /.../mod-jlink/target/mod-jlink-1.0-SNAPSHOT.zip +[INFO] +``` + +If you like to install the resulting Java Run Time Image files into your local cache you can achieve this by using: + +``` +mvn clean install +``` + +or if you like to deploy the resulting artifacts to a remote repository you have to use: + +``` +mvn clean deploy +``` + +At the moment the resulting Java Run Time Image is packaged into a **zip** archive which used to transport the whole structure which is created by **jlink** to a repository. + +The resulting [Installed Directory Structure of JDK](https://docs.oracle.com/en/java/javase/11/install/installed-directory-structure-jdk.html) looks like this: + +``` +jlink/ +├── bin +├── conf +├── include +├── legal +├── lib +└── release +``` + diff --git a/src/site/site.xml b/src/site/site.xml index a03ddff..b3b7991 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -19,20 +19,13 @@ under the License. --> -<project xmlns="http://maven.apache.org/DECORATION/1.8.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 https://maven.apache.org/xsd/decoration-1.8.0.xsd";> - <skin> - <groupId>org.apache.maven.skins</groupId> - <artifactId>maven-fluido-skin</artifactId> - <version>1.9</version> - </skin> +<site xmlns="http://maven.apache.org/SITE/2.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 https://maven.apache.org/xsd/site-2.0.0.xsd";> <body> <menu name="Overview"> <item name="Introduction" href="index.html" /> <item name="Plugin Documentation" href="plugin-info.html" /> <item name="Usage" href="usage.html" /> - <!-- <item name="FAQ" href="faq.html"/> --> - <!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 --> <item name="License" href="https://www.apache.org/licenses/"; /> <item name="Download" href="download.html" /> </menu> @@ -40,4 +33,4 @@ <!-- <item name="Basic multi module setup" href="examples/base-jlink-example.html"/> --> <!-- </menu> --> </body> -</project> +</site>
