This is an automated email from the ASF dual-hosted git repository. slachiewicz pushed a commit to branch MRAR-94-rarResources-documentation in repository https://gitbox.apache.org/repos/asf/maven-rar-plugin.git
commit 085b8733998af1eecf75ae61ccdbf39918bcba6f Author: Sylwester Lachiewicz <[email protected]> AuthorDate: Sun Nov 9 12:52:52 2025 +0000 [MRAR-94] Add documentation and examples for rarResources configuration - Created new example documentation (rar-resources.apt.vm) showing how to use rarResources - Documented all configuration options: directory, targetPath, filtering, includes, excludes - Added examples for basic usage, multiple resources, filtering, and includes/excludes - Updated site.xml to add the new example to the Examples menu - Enhanced usage.apt.vm with Additional Resources section linking to all examples This addresses the issue where users were unclear about how to use the rarResources parameter, particularly that it expects rarResource elements with specific options. --- src/site/apt/examples/rar-resources.apt.vm | 183 +++++++++++++++++++++++++++++ src/site/apt/usage.apt.vm | 14 +++ src/site/site.xml | 1 + 3 files changed, 198 insertions(+) diff --git a/src/site/apt/examples/rar-resources.apt.vm b/src/site/apt/examples/rar-resources.apt.vm new file mode 100644 index 0000000..9fe37ac --- /dev/null +++ b/src/site/apt/examples/rar-resources.apt.vm @@ -0,0 +1,183 @@ + ------ + Using rarResources + ------ + ------ + 2025 + ------ + +~~ 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 + +Using rarResources + + The <<<rarResources>>> parameter allows you to include additional resources + from custom directories into your RAR archive. Each resource can be configured + with a source directory, target path within the RAR, and optional filtering. + +* Basic Configuration + + To add extra resources to your RAR, configure the <<<rarResources>>> parameter + with one or more <<<rarResource>>> elements. Each <<<rarResource>>> element + supports the following options: + + * <<<directory>>> - The source directory containing the files to include + + * <<<targetPath>>> - The destination path within the RAR archive + + * <<<filtering>>> - Whether to apply Maven filtering to the files (default: false) + + * <<<includes>>> - File patterns to include (optional) + + * <<<excludes>>> - File patterns to exclude (optional) + ++---+ +<project> + [...] + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-rar-plugin</artifactId> + <version>${project.version}</version> + <configuration> + <rarResources> + <rarResource> + <directory>${basedir}/src/main/ext</directory> + <targetPath>ext</targetPath> + </rarResource> + </rarResources> + </configuration> + </plugin> + </plugins> + </build> + [...] +</project> ++---+ + +* Using Multiple Resource Directories + + You can configure multiple <<<rarResource>>> elements to include files from + different source directories into different locations within the RAR archive: + ++---+ +<project> + [...] + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-rar-plugin</artifactId> + <version>${project.version}</version> + <configuration> + <rarResources> + <rarResource> + <directory>${basedir}/src/main/ext</directory> + <targetPath>ext</targetPath> + </rarResource> + <rarResource> + <directory>${basedir}/src/main/config</directory> + <targetPath>config</targetPath> + </rarResource> + </rarResources> + </configuration> + </plugin> + </plugins> + </build> + [...] +</project> ++---+ + +* Applying Maven Filtering + + To enable Maven property filtering for specific resources, set the + <<<filtering>>> option to <<<true>>>. This will replace Maven properties + (like <<<$\{project.version\}>>>) with their actual values during the build: + ++---+ +<project> + [...] + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-rar-plugin</artifactId> + <version>${project.version}</version> + <configuration> + <rarResources> + <rarResource> + <directory>${basedir}/src/main/ext</directory> + <targetPath>ext</targetPath> + </rarResource> + <rarResource> + <directory>${basedir}/src/main/ext-filtered</directory> + <targetPath>ext-filtered</targetPath> + <filtering>true</filtering> + </rarResource> + </rarResources> + </configuration> + </plugin> + </plugins> + </build> + [...] +</project> ++---+ + +* Using Includes and Excludes + + You can filter which files to include from a directory using the <<<includes>>> + and <<<excludes>>> options: + ++---+ +<project> + [...] + <build> + <plugins> + <plugin> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-rar-plugin</artifactId> + <version>${project.version}</version> + <configuration> + <rarResources> + <rarResource> + <directory>${basedir}/src/main/resources</directory> + <targetPath>lib</targetPath> + <includes> + <include>**/*.properties</include> + <include>**/*.xml</include> + </includes> + <excludes> + <exclude>**/test/**</exclude> + </excludes> + </rarResource> + </rarResources> + </configuration> + </plugin> + </plugins> + </build> + [...] +</project> ++---+ + + Then execute the plugin by invoking the <<<rar:rar>>> goal. + ++---+ +mvn rar:rar ++---+ + diff --git a/src/site/apt/usage.apt.vm b/src/site/apt/usage.apt.vm index 1976f12..aa63a38 100644 --- a/src/site/apt/usage.apt.vm +++ b/src/site/apt/usage.apt.vm @@ -74,3 +74,17 @@ mvn rar:rar By default, the generated archive(RAR) can be located at the project's target directory. +* Additional Resources + + The plugin provides several configuration options to customize the RAR archive: + + * {{{./examples/include-extra-files.html}Including extra files in RAR}} - Configure the default RAR source directory + + * {{{./examples/rar-resources.html}Using rarResources}} - Add resources from multiple directories with filtering support + + * {{{./examples/ra-custom-location.html}Custom location of Resource Adapter Descriptor}} - Specify a custom ra.xml location + + * {{{./examples/manifest.html}Adding Manifest File}} - Include a custom MANIFEST.MF + + * {{{./examples/exclude-project-jar.html}Exclude the project jar from the rar}} - Control whether the project's JAR is included + diff --git a/src/site/site.xml b/src/site/site.xml index 460c400..6ee1bc2 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -36,6 +36,7 @@ under the License. <item name="Exclude the project jar from the rar" href="examples/exclude-project-jar.html"/> <item name="Custom location of Resource Adapter Descriptor" href="examples/ra-custom-location.html" /> <item name="Include extra files in RAR" href="examples/include-extra-files.html" /> + <item name="Using rarResources" href="examples/rar-resources.html" /> <item name="Adding Manifest File" href="examples/manifest.html" /> </menu> <menu name="Resources">
