This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-rar-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 30e54d1 [MRAR-94] Add documentation and examples for rarResources
configuration
30e54d1 is described below
commit 30e54d1e65d0fb0e0da1b5827cac1e1dda79314a
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 index.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/index.apt.vm | 10 +-
src/site/apt/usage.apt.vm | 34 +++---
src/site/site.xml | 1 +
4 files changed, 207 insertions(+), 21 deletions(-)
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/index.apt.vm b/src/site/apt/index.apt.vm
index 28e58bf..2327f03 100644
--- a/src/site/apt/index.apt.vm
+++ b/src/site/apt/index.apt.vm
@@ -67,13 +67,15 @@ ${project.name}
To provide you with better understanding on some usages of the Plugin Name,
you can take a look into the following examples:
- * {{{./examples/exclude-project-jar.html}Exclude the project jar from the
rar}}
+ * {{{./examples/include-extra-files.html}Including extra files in RAR}} -
Configure the default RAR source directory
- * {{{./examples/ra-custom-location.html}Custom location of Resource Adapter
Descriptor}}
+ * {{{./examples/rar-resources.html}Using rarResources}} - Add resources from
multiple directories with filtering support
- * {{{./examples/include-extra-files.html}Include extra files in RAR}}
+ * {{{./examples/ra-custom-location.html}Custom location of Resource Adapter
Descriptor}} - Specify a custom ra.xml location
- * {{{./examples/manifest.html}Adding Manifest File}}
+ * {{{./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/apt/usage.apt.vm b/src/site/apt/usage.apt.vm
index 1976f12..775514c 100644
--- a/src/site/apt/usage.apt.vm
+++ b/src/site/apt/usage.apt.vm
@@ -6,22 +6,22 @@
July 2006
------
-~~ 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.
+~~ 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
@@ -71,6 +71,6 @@ mvn package
mvn rar:rar
+---+
- By default, the generated archive(RAR) can be located at the project's
target
+ By default, the generated archive(RAR) can be located at the project's target
directory.
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">
