Java Packaging HOWTO

1.1. Basic introduction to packaging, reasons, problems, rationale

1.2. For Packagers

1.2.1. Example Java Project

To better illustrate various parts of Java packaging we will dissect simple Java Hello world application. Java sources are usually organized using directory hierarchies. Shared directory hierarchy creates a namespace called package in Java terminology. To understand naming mechanisms of Java packages see Java package naming conventions.

Let’s create a simple hello world application that will execute following steps when run:

1. Ask for a name.

2. Print out Hello World from and the name from previous step.

To illustrate certain points we artificially complicate things by creating:

• Input class used only for input of text from terminal.

• Output class used only for output on terminal.

• HelloWorldApp class used as main application.

Directory listing of example project

$ find .
.
./Makefile
./src
./src/org
./src/org/fedoraproject
./src/org/fedoraproject/helloworld
./src/org/fedoraproject/helloworld/output
./src/org/fedoraproject/helloworld/output/Output.java
./src/org/fedoraproject/helloworld/input
./src/org/fedoraproject/helloworld/input/Input.java
./src/org/fedoraproject/helloworld/HelloWorld.java

In this project all packages are under src/ directory hierarchy.

HelloWorld.java listing

package org.fedoraproject.helloworld;

// import Input class from org.fedoraproject.helloworld.input package
import org.fedoraproject.helloworld.input.Input;
// import Output class from org.fedoraproject.helloworld.output package
import org.fedoraproject.helloworld.output.Output;

class HelloWorld {
    public static void main(String[] args) {
        System.out.print("What is your name?: ");
        String reply = Input.getInput();
        Output.output(reply);
    }
}

Java packages

org/fedoraproject/helloworld/input/Input.java
org/fedoraproject/helloworld/output/Output.java
org/fedoraproject/helloworld/HelloWorld.java

Although the directory structure of our package is hierarchical, there is no real parent-child relationship between packages. Each package is therefore seen as independent. The above example makes use of three separate packages:

• org.fedoraproject.helloworld.input

• org.fedoraproject.helloworld.output

• org.fedoraproject.helloworld

Environment setup consists of two main parts:

• Telling JVM which Java class contains main() method.

• Adding required JAR files on JVM classpath.

Compiling our project

The sample project can be compiled to a bytecode by Java compiler. Java compiler can be typically invoked from command line by command javac.

javac $(find -name '*.java')

For every .java file corresponding .class file will be created. The .class files contain Java bytecode which is meant to be executed on JVM.

One could put invocation of javac to Makefile and simplify the compilation a bit. It might be sufficient for such a simple project, but it would quickly become hard to build more complex projects with this approach. Java world knows several high-level build systems which can highly simplify building of Java projects. Among others, probably the most known are Apache Maven and Apache Ant.

See also Maven and Ant sections.

JAR files

Having our application split across many .class files would not be very practical, so those .class files are assembled into ZIP files with specific layout and called JAR files. Most commonly these special ZIP files have .jar suffix, but other variations exist (.war, .ear). They contain:

• Compiled bytecode of our project.

• Additional metadata stored in META-INF/MANIFEST.MF file.

• Resource files such as images or localisation data.

• Optionaly the source code of our project (called source JAR then).

They can also contain additional bundled software which is something we do not want to have in packages. You can inspect the contents of given JAR file by extracting it. That can be done with following command:

jar -xf something.jar

The detailed description of JAR file format is in the JAR File Specification.

Classpath

The classpath is a way of telling JVM where to look for user classes and 3rd party libraries. By default, only current directory is searched, all other locations need to be specified explicitly by setting up CLASSPATH environment variable, or via -cp (-classpath) option of the Java Virtual Machine.

Setting the classpath

java -cp /usr/share/java/log4j.jar:/usr/share/java/junit.jar mypackage/MyClass.class
CLASSPATH=/usr/share/java/log4j.jar:/usr/share/java/junit.jar java mypackage/MyClass.class

Please note that two JAR files are separated by colon in a classpath definition.

See official documentation for more information about classpath.

Wrapper scripts

Classic compiled applications use dynamic linker to find dependencies (linked libraries), whereas dynamic languages such as Python, Ruby, Lua have predefined directories where they search for imported modules. JVM itself has no embedded knowledge of installation paths and thus no automatic way to resolve dependencies of Java projects. This means that all Java applications have to use wrapper shell scripts to setup the environment before invoking the JVM and running the application itself. Note that this is not necessary for libraries.

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example.myproject</groupId>
  <artifactId>myproject</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>myproject</name>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

<project name="MyProject" default="dist" basedir=".">
  <property name="src" location="src"/>
  <property name="build" location="build"/>
  <property name="dist" location="dist"/>

  <target name="init" description="Create build directory">
    <mkdir dir="${build}"/>
  </target>

  <target name="compile" depends="init"
        description="Compile the source">
    <javac srcdir="${src}" destdir="${build}"/>
  </target>

  <target name="dist" depends="compile"
        description="Generate jar">
    <mkdir dir="${dist}/lib"/>

    <jar jarfile="${dist}/myproject.jar" basedir="${build}"/>
  </target>

  <target name="clean" description="Clean build files">
    <delete dir="${build}"/>
    <delete dir="${dist}"/>
  </target>
</project>

1.3. For Java Developers

1.3.1. Example RPM Project

RPM uses spec files as recipes for building software packages. We will use it to package example project created in previous section. If you did not read it you do not need to; the file listing is available here and the rest is not necessary for this section.

Directory listing

Makefile
src
src/org
src/org/fedoraproject
src/org/fedoraproject/helloworld
src/org/fedoraproject/helloworld/output
src/org/fedoraproject/helloworld/output/Output.java
src/org/fedoraproject/helloworld/input
src/org/fedoraproject/helloworld/input/Input.java
src/org/fedoraproject/helloworld/HelloWorld.java

We packed the project directory into file helloworld.tar.gz.

Example spec file

# Comments start with hash sign. Caution: macros in comments are still
# expanded, which can lead to unexpected results. To stop macro from expanding,
# double its percent sign (e.g. %%mvn_install)

# First part usually consists of metadata such as package name, version, and
# much more
Name:		helloworld
Version:	1.0
Release:	1%{?dist}
Summary:	This is a minimal spec file example

License:	GPLv2+
# Homepage URL of the project
URL:		http://www.fedoraproject.org

# Our source archive. %{name} expands to 'helloworld' so the resulting
# tarball name would be 'helloworld.tar.gz'.
Source0:    %{name}.tar.gz

# Packages that contain only architecture independent files, such as shell
# scripts or regular Java programs (not JNI libraries), should be marked as 'noarch'
BuildArch:  noarch

# Project's build time dependency. We don't really need JUnit, it just
# serves as and example
BuildRequires: junit

%description
Very short description since we have nothing to say.

%prep
# section for preparation of sources, applying patches
# or other things which can be done before running the build
# The macro setup is used to unpack sources
%setup -q

%build
# Section for compiling and generally assembling the final pieces.
# Our Makefile builds the project JAR file
%make_build

%install
# Installation into directory prepared by RPM expressed as %{buildroot}
install -p -m 644 helloworld.jar %{buildroot}%{_javadir}/helloworld.jar

# We use macro %jpackage_script to generate wrapper script for our JAR
# Will be explained in later sections
%jpackage_script org.fedoraproject.helloworld.HelloWorld "" "" %{name} helloworld true

# List of files that this package installs on the system
%files
%{_javadir}/helloworld.jar
%{_bindir}/helloworld

%changelog
* Tue Mar 19 2013 Stanislav Ochotnicky <sochotnicky@redhat.com> - 1.0-1
- This is first version

RPM spec files contain several basic sections:

Header, which contains:

• Package metadata such as its name, version, release, license, …​

• A Summary with basic one-line summary of package contents.

• Package source URLs denoted with Source0 to SourceN directives.

  • Source files can then be referenced by %SOURCE0 to %SOURCEn, which expand to actual paths to given files.

  • In practice, the source URL shouldn’t point to a file in our filesystem, but to an upstream release on the web.

• Patches - using Patch0 to PatchN.

• Project dependencies.

  • Build dependencies specified by BuildRequires, which need to be determined manually.

  • Run time dependencies will be detected automatically. If it fails, you have to specify them with Requires.

  • More information on this topic can be found in the dependency handling section.

%description

• Few sentences about the project and its uses. It will be displayed by package management software.

%prep section

• Unpacks the sources using setup -q or manually if needed.

• If a source file doesn’t need to be extracted, it can be copied to build directory by cp -p %SOURCE0 ..

• Apply patches with %patch X, where X is the number of patch you want to apply. (You usually need the patch index, so it would be: %patch 0 -p1).

%build section

• Contains project compilation instructions. Usually consists of calling the projects build system such as Ant, Maven or Make.

Optional %check section

• Runs projects integration tests. Unit test are usually run in %build section, so if there are no integration tests available, this section is omitted.

%install section

• Copies built files that are supposed to be installed into %{buildroot} directory, which represents target filesystem’s root.

%files section

• Lists all files, that should be installed from %{buildroot} to target system.

• Documentation files are prefixed by %doc and are taken from build directory instead of buildroot.

• Directories that this package should own are prefixed with %dir.

%changelog

• Contains changes to this spec file (not upstream).

• Has prescribed format. To prevent mistakes in format, it is advised to use tool such as rpmdev-bumpspec from package rpmdevtools to append new changelog entries instead of editing it by hand.

To build RPM from this spec file save it in your current directory and run rpmbuild:

$ rpmbuild -bb helloworld.spec

If everything worked OK, this should produce RPM file ~/rpmbuild/RPMS/x86_64/helloworld-1.0-1.fc18.x86_64.rpm. You can use rpm -i or dnf install commands to install this package and it will add /usr/share/java/helloworld.jar and /usr/bin/helloworld wrapper script to your system. Please note that this specfile is simplified and lacks some additional parts, such as license installation.

Paths and filenames might be slightly different depending on your architecture and distribution. Output of the commands will tell you exact paths.

As you can see to build RPM files you can use rpmbuild command. It has several other options, which we will cover later on.

Other than building binary RPMs (-bb), rpmbuild can also be used to:

• build only source RPMs (SRPMs), the packages containing source files which can be later build to RPMs (option -bs)

• build all, both binary and source RPMs (option -ba)

See rpmbuild 's manual page for all available options.

$ dnf repoquery --whatprovides 'mvn(commons-io:commons-io)'
apache-commons-io-1:2.4-9.fc19.noarch

$ dnf repoquery --available --disablerepo \* --enablerepo rawhide --whatprovides 'mvn(commons-io:commons-io)'
apache-commons-io-1:2.4-10.fc20.noarch

$ dnf repoquery --provides apache-commons-io
apache-commons-io = 1:2.4-9.fc19
jakarta-commons-io = 1:2.4-9.fc19
mvn(commons-io:commons-io) = 2.4
mvn(org.apache.commons:commons-io) = 2.4
osgi(org.apache.commons.io) = 2.4.0

$ rpm -qp --provides simplemaven-1.0-2.fc21.noarch.rpm
mvn(com.example:simplemaven) = 1.0
mvn(simplemaven:simplemaven) = 1.0
simplemaven = 1.0-2.fc21

2.1. Java implementation in Fedora

$ java org/fedoraproject/helloworld/HelloWorld.class

2.1.1. Switching between different Java implementations

Users and developers may want to have multiple Java environments installed at the same time. It is possible in Fedora, but only one of them can be default Java environment in system. Fedora uses alternatives for switching between different installed JREs/JDKs.

# alternatives --config java

There are 3 programs which provide 'java'.

  Selection    Command
  -----------------------------------------------
   1           java-17-openjdk.x86_64 (/usr/lib/jvm/java-17-openjdk-17.0.2.0.8-1.fc35.x86_64/bin/java)
*+ 2           java-11-openjdk.x86_64 (/usr/lib/jvm/java-11-openjdk-11.0.14.1.1-5.fc35.x86_64/bin/java)
   3           java-latest-openjdk.x86_64 (/usr/lib/jvm/java-18-openjdk-18.0.1.0.10-1.rolling.fc35.x86_64/bin/java)

Enter to keep the current selection[+], or type selection number:

Example above shows how to chose default Java environment. java command will then point to the Java implementation provided by given JRE.

See man alternatives for more information on how to use alternatives.

Developers may want to use Java compiler from different JDK. This can be achieved with alternatives --config javac.

2.2. Building classpath with build-classpath

$ build-classpath log4j junit org.ow2.asm:asm
/usr/share/java/log4j.jar:/usr/share/java/junit.jar:/usr/share/java/objectweb-asm4/asm.jar

$ build-classpath httpcomponents/httpclient.jar
/usr/share/java/httpcomponents/httpclient.jar

2.3. Building JAR repository with build-jar-repository

$ build-jar-repository my-repo log4j httpcomponents/httpclient junit:junit
$ ls -l my-repo/
total 0
lrwxrwxrwx. 1 msrb msrb 45 Oct 29 10:39 [httpcomponents][httpclient].jar -> /usr/share/java/httpcomponents/httpclient.jar
lrwxrwxrwx. 1 msrb msrb 25 Oct 29 10:39 [junit:junit].jar -> /usr/share/java/junit.jar
lrwxrwxrwx. 1 msrb msrb 25 Oct 29 10:39 [log4j].jar -> /usr/share/java/log4j.jar

$ build-classpath-directory /usr/share/java/xstream
/usr/share/java/xstream/xstream-benchmark.jar:/usr/share/java/xstream/xstream.jar
:/usr/share/java/xstream/xstream-hibernate.jar

3.1. Directory Layout

3.2. JAR File Identification

# com.example.foo:bar (the actual artifact existing in the project) will also
# be available as com.example.foo:bar-all
%mvn_alias com.example.foo:bar com.example.foo:bar-all

# You don't need to repeat the part of coordinates that stays the same
# (groupID in this case)
%mvn_alias com.example.foo:bar :bar-all

# You can specify multiple aliases at once
%mvn_alias com.example.foo:bar :bar-all :bar-lib

# The macro supports several shortcuts to generate multiple alisaes.
# Braces - {} - capture their content, which can then be referenced in the
# alias part with @N, where N is the index of the capture group.
# * acts as a wildcard (matching anything)
# The following generates aliases ending with shaded for all artifacts in the
# project
%mvn_alias 'com.example.foo:{*}' :@1-shaded

3.2.4. Compatibility versions

Handling of compatibility packages, versioned jars etc.

In Fedora we prefer to always have only the latest version of a given project. Unfortunately, this is not always possible as some projects change too much and it would be too hard to port dependent packages to the current version. It is not possible to just update the package and keep the old version around as the names, file paths and dependency provides would clash. The recommended practice is to update the current package to the new version and create new package representing the old version (called compat package). The compat package needs to have the version number (usually only the major number, unless further distinction is necessary) appended to the name, thus effectivelly having different name from RPM’s point of view. Such compat package needs to perform some additional steps to ensure that it can be installed and used along the non-compat one.

You should always evaluate whether creating a compat package is really necessary. Porting dependent projects to new versions of dependencies may be a complicated task, but your effort would be appreciated and it is likely that the patch will be accepted upstream at some point in time. If the upstream is already inactive and the package is not required by anything, you should also consider retiring it.

Maven Compat Versions

XMvn supports marking particular artifact as compat, performing the necessary steps to avoid clashes with the non-compat version. An artifact can be marked as compat by %mvn_compat_version. It accepts an artifact argument which will determine which artifact will be compat. The format for specifying artifact coordinates is the same as with %mvn_alias. In the common case you will want to mark all artifacts as compat. You can specify multiple compat versions at a time.

Dependency resolution of compat artifacts

When XMvn performs dependency resolution for a dependency artifact in a project, it checks the dependency version and compares it against all versions of the artifact installed in the buildroot. If none of the compat artifacts matches it will resolve the artifact to the non-compat one. This has a few implications:

• The versions are compared for exact match. The compat package should provide all applicable versions that are present in packages that are supposed to be used with this version.

• The dependent packages need to have correct BuildRequires on the compat package as the virtual provides is also different (see below).

File names and virtual provides

In order to prevent file name clashes, compat artifacts have the first specified compat version appended to the filename. Virtual provides for compat artifacts also contain the version as the last part of the coordinates. There are multiple provides for each specified compat version. Non-compat artifact do not have any version in the virtual provides.

Example invocation of %mvn_compat_version

# Assuming the package has name bar and version 3
# Sets the compat version of foo:bar artifact to 3
%mvn_compat_version foo:bar 3
# The installed artifact file (assuming it's jar and there were no
# %mvn_file calls) will be at %{_javadir}/bar/bar-3.jar
# The generated provides for foo:bar will be
# mvn(foo:bar:3) = 3
# mvn(foo:bar:pom:3) = 3

# Sets the compat versions of all artifacts in the build to 3 and 3.2
%mvn_compat_version : 3 3.2

3.3. Dependency Handling

# Example provide for Jar artifact
mvn(org.eclipse.jetty:jetty-server)
# Example provide for POM artifact
mvn(org.eclipse.jetty:jetty-parent:pom:)
# Example provide for Jar artifact with classifier
mvn(org.sonatype.sisu:sisu-guice::no_aop:)

rpm -qp --provides path/to/example-1.0.noarch.rpm
rpm -qp --requires path/to/example-1.0.noarch.rpm

See also Querying Fedora repositories

3.4. Javadoc packages

You can learn more about javadoc from official documentation.

3.5. Core Java packages

3.5.1. JVM

Fedora allows multiple Java Virtual Machines (JVMs) to be packaged independently. Java packages should not directly depend on any particulat JVM, but instead require one of three virtual JVM packages depending of what Java funtionality is required.

java-headless

This package provides a working Java Runtime Environment (JRE) with some functionality disabled. Graphics and audio support may be unavailable in this case. java-headless provides functionality that is enough for most of packages and avoids pulling in a number of graphics and audio libraries as dependencies. Requirement on java-headless is appropriate for most of Java packages.

java

Includes the same base functionality as java-headless, but also implements audio and graphics subsystems. Packages should require java if they need some functionality from these subsystems, for example creating GUI using AWT library.

java-devel

Provides full Java Development Kit (JDK). In most cases only packages related to Java development should have runtime dependencies on java-devel. Runtime packages should require java-headless or java. Some packages not strictly related to java development need access to libraries included with JDK, but not with JRE (for example tools.jar). That is one of few cases where requiring java-devel may be necessary.

Packages that require minimal Java standard version can add versioned dependencies on one of virtual packages providing Java environment. For example if packages depending on functionality of JDK 8 can require java-headless >= 1:1.8.0.

Epoch in versions of JVM packages For compatibility with JPackage project packages providing Java 1.6.0 or later use epoch equal to 1. This was necessary because package java-1.5.0-ibm from JPackage project had epoch 1 for some reason. Therefore packages providing other implementations of JVM also had to use non-zero epoch in order to keep version ordering correct.

5.1. Generating Application Shell Scripts

%install
...
%jpackage_script msv.textui.Driver "" "" msv-msv:msv-xsdlib:relaxngDatatype:isorelax msv true
...

5.2. Replacing JARs with symlinks using xmvn-subst

$ ls -l
-rw-r--r--. 1 msrb msrb  40817 Oct 22 09:16 cli.jar
-rw-r--r--. 1 msrb msrb 289983 Oct 22 09:17 junit4.jar
-rw-r--r--. 1 msrb msrb 474276 Oct 22 09:14 log4j.jar
$ xmvn-subst .
[INFO] Linked ./cli.jar to /usr/share/java/commons-cli.jar
[INFO] Linked ./log4j.jar to /usr/share/java/log4j.jar
[INFO] Linked ./junit4.jar to /usr/share/java/junit.jar
$ ls -la
lrwxrwxrwx. 1 msrb msrb   22 Oct 22 10:08 cli.jar -> /usr/share/java/commons-cli.jar
lrwxrwxrwx. 1 msrb msrb   22 Oct 22 10:08 junit4.jar -> /usr/share/java/junit.jar
lrwxrwxrwx. 1 msrb msrb   22 Oct 22 10:08 log4j.jar -> /usr/share/java/log4j.jar

See xmvn-subst -h for all available options.

6.1. Apache Ivy

BuildRequires: ivy-local
...
%build
ant -Divy.mode=local test

%install
%mvn_artifact ivy.xml lib/sample.jar

%mvn_install -J api/

%files -f .mfiles
%files -javadoc -f .mfiles-javadoc

# Remove dependency on artifact with org="com.example" and
# name="java-project" from ivy.xml file in current directory
%pom_remove_dep com.example:java-project

# Add dependency on artifact with org="com.example" and
# name="foobar" to ./submodule/ivy.xml
%pom_add_dep com.example:foobar submodule

BuildRequires: ivy-local
...
%prep
%pom_xpath_set ivy:publish/@resolver xmvn build.xml

%build
ant -Divy.mode=local test publish-local

%install
%mvn_install -J api/

%files -f .mfiles
%files -javadoc -f .mfiles-javadoc

7.1. Packaging Maven project

Name:           simplemaven
Version:        1.0
Release:        1%{?dist}
Summary:        Simple Maven project
License:        BSD
URL:            https://www.example.com
Source0:        https://www.example.com/simplemaven-1.0.tar.gz
BuildArch:      noarch

BuildRequires:  maven-local

%description
This is simple Maven project.

%package        javadoc
Summary:        Javadoc for %{name}

%description javadoc
This package contains the API documentation for %{name}.

%prep
%setup -q

%build
%mvn_build

%install
%mvn_install

%files -f .mfiles
%files javadoc -f .mfiles-javadoc

%changelog
* Mon Oct 14 2013 Michal Srb <msrb@redhat.com> - 1.0-1
- Initial packaging

10: BuildRequires:  maven-local

31: %dir %{_javadir}/%{name}

...
%prep
%setup -q

# Add following lines to %prep section of a spec file
%pom_remove_dep :commons-io
%pom_remove_dep :junit

Another reason to disable the test phase is to speed up the local build process. This can also be achieved by specifying an additional switch --without=tests to the fedpkg or the mock tool instead of adding a switch to %mvn_build. Another switch --without=javadoc causes the build to skip Javadoc generation.

It is always recommended to run all available test suites during build. It greatly improves quality of the package.

BuildRequires:  maven-local
BuildRequires:  apache-commons-io
...
%prep
%setup -q

# Comment out following lines in %prep section
#%%pom_remove_dep :commons-io
#%%pom_remove_dep :junit

%build
# Skip tests for now, missing dependency junit:junit:4.11
%mvn_build -f

One can easily search for package which provides the desired artifact. Try dnf repoquery --whatprovides 'mvn(commons-io:commons-io)', or see how to query repositories.

%prep
%setup -q

%mvn_file : %{name}/%{name} %{name}

$ rpm -qp --provides simplemaven-1.0-1.fc21.noarch.rpm
mvn(com.example:simplemaven) = 1.0
simplemaven = 1.0-1.fc21

%mvn_alias org.example:simplemaven simplemaven:simplemaven

$ rpm -qp --provides simplemaven-1.0-2.fc21.noarch.rpm
mvn(com.example:simplemaven) = 1.0
mvn(simplemaven:simplemaven) = 1.0
simplemaven = 1.0-2.fc21

One could try to fix dependencies in all the dependent packages instead of adding an alias to single package. It is almost always wrong thing to do.

7.2. Macros for Maven build configuration

%prep
...
# Request installation of POM and JAR file
%mvn_artifact subpackage/pom.xml target/artifact.jar
# Request installation of POM artifact (no JAR file)
%mvn_artifact pom.xml
# Request installation for JAR file specified by artifact coordinates
%mvn_artifact webapp:webapp:war:3.1 webapp.war

%prep
...
%mvn_alias "commons-lang:commons-lang" "org.apache.commons:commons-lang"

%prep
...
%mvn_file :guice google/guice guice

...
%description
The Maven Plugin Tools contains...

%package -n maven-plugin-annotations
Summary:        Maven Plugin Java 5 Annotations

%description -n maven-plugin-annotations
This package contains Java 5 annotations to use in Mojos.

%package -n maven-plugin-plugin
Summary:        Maven Plugin Plugin

%description -n maven-plugin-plugin
The Plugin Plugin is used to...
...

%build
%mvn_build -s

%install
%mvn_install

%files -f .mfiles-maven-plugin-tools
%doc LICENSE NOTICE
%files -n maven-plugin-annotations -f .mfiles-maven-plugin-annotations
%files -n maven-plugin-plugin      -f .mfiles-maven-plugin-plugin
%files -f .mfiles-javadoc
...

7.2.5. Assignment of the Maven Artifacts to the Subpackages

The macro %mvn_package allows maintainer to specify in which exact package the selected artifact will end up. It is something between singleton packaging, when each artifact has its own subpackage and default packaging, when all artifacts end up in the same package.

Assigning multiple artifacts to single subpackage

...
%prep
%mvn_package ":plexus-compiler-jikes"   plexus-compiler-extras
%mvn_package ":plexus-compiler-eclipse" plexus-compiler-extras
%mvn_package ":plexus-compiler-csharp"  plexus-compiler-extras

%build
%mvn_build

%install
%mvn_install

%files -f .mfiles
%files -f .mfiles-plexus-compiler-extras
%files -f .mfiles-javadoc

In above example, the artifacts plexus-compiler-jikes, plexus-compiler-eclipse, plexus-compiler-csharp will end up in package named plexus-compiler-extras. If there are some other artifacts beside these three mentioned (e.g. some parent POMs), then these will all end up in package named %{name}.

%mvn_package macro supports wildcards and brace expansions, so whole %prep section from previous example can be replaced with single line: %mvn_package ":plexus-compiler-{jikes,eclipse,csharp}" plexus-compiler-extras.

It is possible to assign artifacts into a package called __noinstall. This package name has a special meaning. And as you can guess, artifacts assigned into this package will not be installed anywhere and the package itself will not be created.

Skipping installation of an artifact

%prep
...
%mvn_package groupId:artifactId __noinstall

7.2.6. Modifying XMvn configuration from within spec file

Some packages might need to modify XMvn’s configuration in order to build successfully or from other reasons. This can be achieved with mvn_config macro. For example, some old package can use enum as an identifier, but it is also keyword since Java 1.5. Such package will probably fail to build on current systems. This problem can be easily solved by passing -source 1.4 to the compiler, so one could add following line to the spec file:

Overriding default XMvn configuration

%prep
...
%mvn_config buildSettings/compilerSource 1.4

XMvn’s configuration is quite complex, but well documented at the project’s official website. The website should always be used as a primary source of information about XMvn configuration.

Read about XMvn’s configuration basics and see the full configuration reference.

All %mvn_ macros have their own manual page which contains details on how to use them. All possible options should be documented there. These manual pages should be considered most up to date documentation right after source code. Try for example man mvn_file. These pages are also included in the Appendix.

7.3. Macros for POM modification

# The following works on pom.xml file in the current directory
%pom_remove_parent

# The following works on submodule/pom.xml
%pom_remove_parent submodule

# The following works on submodule/pom.xml as well
%pom_remove_parent submodule/pom.xml

# The following works on submodule2/pom.xml and submodule2/pom.xml
%pom_remove_parent submodule1 submodule2

# Removes dependency with groupId "foo" and artifactId "bar" from pom.xml
%pom_remove_dep foo:bar

# Removes dependency on all artifacts with groupId "foo" from pom.xml
%pom_remove_dep foo:

# Removes dependency on all artifacts with artifactId "bar" from pom.xml
%pom_remove_dep :bar

# Removes dependency on all artifacts with artifactId "bar" from submodule1/pom.xml
%pom_remove_dep :bar submodule1

# Removes dependency on all artifacts with artifactId "bar" from pom.xml
# and all its submodules
%pom_remove_dep -r :bar

# Removes all dependencies from pom.xml
%pom_remove_dep :

# For all artifacts in pom.xml that have groupId 'example' change it to
# 'com.example' while leaving artifactId and other parts intact
%pom_change_dep example: com.example:

# Disables maven-jar-plugin so that classpath isn't included in manifests
%pom_remove_plugin :maven-jar-plugin

# Disable a proprietary plugin that isn't packaged for Fedora
%pom_remove_plugin com.example.mammon:useless-proprietary-plugin submodule

# Disables child-module-1, a submodule of the main pom.xml file
%pom_disable_module child-module-1

# Disables grandchild-module, a submodule of child-module-2/pom.xml
%pom_disable_module grandchild-module child-module-2

# Remove reference to a parent POM from ./pom.xml
%pom_remove_parent

# Remove reference to a parent POM from ./submodule/pom.xml
%pom_remove_parent submodule

# Add parent POM reference to ./pom.xml
%pom_add_parent groupId:artifactId

# Replace existing parent POM reference in ./pom.xml
%pom_set_parent groupId:artifactId:version

7.3.5. Macros for performing generic modifications

The above macros cover the most common cases of modifying pom.xml files, however if there is a need to apply some less-common patches there are also three generic macros for modifying pom.xml files. These generic macros can also be applied to other XML files, such as Ant’s build.xml files.

They all take a XPath 1.0 expression that selects XML nodes to be acted on (removed, replaced, etc.).

Handling XML namespaces POM files use a specific namespace - http://maven.apache.org/POM/4.0.0. The easiest way to respect this namespace in XPath expressions is prefixing all node names with pom:. For example, pom:environment/pom:os will work because it selects nodes from pom namespace, but environment/os won’t find anything because it looks for nodes that do not belong to any XML namespace. It is needed even if the original POM file didn’t contain proper POM namespace, since it will be added automatically. Note that this requirement is due to limitation of XPath 1.0 and we cannot work it around.

Removing nodes

%pom_xpath_remove can be used to remove arbitrary XML nodes.

# Removes extensions from the build
%pom_xpath_remove "pom:build/pom:extensions" module/pom.xml

Injecting nodes

%pom_xpath_inject macro is capable of injecting arbitrary XML code to any pom.xml file. The injected code is the last argument - optional file paths go before it (unlike most other macros). To pass a multiline snippet, quote the argument as in the following example.

# Add additional exclusion into maven-wagon dependency
%pom_xpath_inject "pom:dependency[pom:artifactId='maven-wagon']/pom:exclusions" "
<exclusion>
  <groupId>antlr</groupId>
  <artifactId>antlr</artifactId>
</exclusion>"
# The same thing, but with explicit file path
%pom_xpath_inject "pom:dependency[pom:artifactId='maven-wagon']/pom:exclusions" pom.xml "
<exclusion>
  <groupId>antlr</groupId>
  <artifactId>antlr</artifactId>
</exclusion>"

Changing nodes' content

%pom_xpath_set replaces content of the arbitrary XML nodes with specified value (can contain XML nodes).

# Change groupId of a parent
%pom_xpath_set "pom:parent/pom:groupId" "org.apache"

Replacing nodes

%pom_xpath_replace replaces a XML node with specified XML code.

# Change groupId of a parent (note the difference from %pom_xpath_set)
%pom_xpath_replace "pom:parent/pom:groupId" "<groupId>org.apache</groupId>"

8.1. Missing dependency

[ERROR] Failed to execute goal on project simplemaven:
Could not resolve dependencies for project com.example:simplemaven:jar:1.0:
The following artifacts could not be resolved: commons-io:commons-io:jar:2.4, junit:junit:jar:4.11:
Cannot access central (http://repo.maven.apache.org/maven2) in offline mode and the artifact commons-io:commons-io:jar:2.4 has not been downloaded from it before. -> [Help 1]

BuildRequires:  mvn(commons-io:commons-io)
BuildRequires:  mvn(junit:junit)

8.2. Compilation failure

[ERROR] Failed to execute goal
        org.apache.maven.plugins:maven-compiler-plugin:3.1:compile (default-compile)
        on project simplemaven: Compilation failure: Compilation failure:
[ERROR] /builddir/build/BUILD/simplemaven-1.0/src/main/java/com/example/Main.java:[3,29] package org.apache.commons.io does not exist
[ERROR] /builddir/build/BUILD/simplemaven-1.0/src/main/java/com/example/Main.java:[8,9] cannot find symbol
[ERROR] symbol:   class FileUtils
[ERROR] location: class com.example.Main
[ERROR] -> [Help 1]

8.3. Requires cannot be generated

Following dependencies were not resolved and requires cannot be generated.
Either remove the dependency from pom.xml or add proper packages to
BuildRequires: org.apache.maven.doxia:doxia-core::tests:UNKNOWN

%mvn_package :::tests: %{name}-tests

8.4. Dependencies with scope system

[ERROR] Failed to execute goal org.fedoraproject.xmvn:xmvn-mojo:1.2.0:install (default-cli) on project pom: Some reactor artifacts have dependencies with scope "system".
Such dependencies are not supported by XMvn installer.
You should either remove any dependencies with scope "system" before the build or not run XMvn instaler. -> [Help 1]

%pom_remove_dep com.sun:tools
%pom_add_dep com.sun:tools

9.1. %add_maven_depmap macro

BuildRequires:  javapackages-tools

Requires:       some-library
...

%build
ant test

%install
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -m 644 target/%{name}.jar $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -m 644 %{name}.pom $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom

# Note that the following call is equivalent to invoking the macro
# without any parameters
%add_maven_depmap JPP-%{name}.pom %{name}.jar

# javadoc
install -d -m 755 $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -pr api/* $RPM_BUILD_ROOT%{_javadocdir}/%{name}

%files
%{_javadir}/*
%{_mavenpomdir}/*
%{_mavendepmapfragdir}/*

%files javadoc
%doc %{_javadocdir}/%{name}

# mvn_* macros are located in javapackages-local package
BuildRequires:  javapackages-local

# Since XMvn generates requires automatically, it is no longer needed
# nor recommended to specify manual Requires tags, unless the dependency
# information in the POM is incomplete or you need to depend on non-java
# packages
...

%prep
# The default location for installing JAR files is %{_javadir}/%{name}/
# Because our original specfile put the JAR directly to %{_javadir}, we
# want to override this behavior. The folowing call tells XMvn to
# install the groupId:artifactId artifact as %{_javadir}/%{name}.jar
%mvn_file groupId:artifactId %{name}

%build
ant test

# Tell XMvn which artifact belongs to which POM
%mvn_artifact %{name}.pom target/%{name}.jar

%install
# It is not necessary to install directories and artifacts manually,
# mvn_install will take care of it

# Optionally use -J parameter to specify path to directory with built
# javadoc
%mvn_install -J api

# Use autogenerated .mfiles file instead of specifying individual files
%files -f .mfiles
%files javadoc -f .mfiles-javadoc

If the project consists of multiple artifacts and parent POMs are among them, call %mvn_artifact on these parent POMs first.

A.1. mvn_alias

MVN_ALIAS(7)                   Java Packages Tools                  MVN_ALIAS(7)

NAME
     mvn_alias - add alias(es) for Maven artifact(s)

SYNOPSIS
     %mvn_alias artifact-coordinates alias [alias ...]

DESCRIPTION
     mvn_alias  macro  causes instructions for artifact installation to be added
     to XMvn reactor configuration. It is  used  to  specify  alternative  names
     (aliases) for Maven artifacts.

     Specified  artifact  coordinates  must  match at least one artifact. If not
     then behavior is unspecified. It is possible to  specify  artifact  coordi‐
     nates  matching multiple artifacts, so one call to mvn_alias can affect in‐
     stallation of more than one artifact.

OPERANDS
     artifact-coordinates
         Artifact coordinates specify artifact(s) that this rule applies to. Co‐
         ordinates   are   in   format    groupId:artifactId[:extension[:classi‐
         fier]][:version]. If extension is specified then version must be speci‐
         fied  too.  If  any  part  is  omitted or equal to empty string then it
         matches any string. Wildcards and brace  expansions  are  supported  in
         each part. For more information see XMvn Configuration Reference.

     alias
         Coordinates  specifying  artifact  alias  (alternative name under which
         matching artifacts  will  be  available).  Coordinates  are  in  format
         groupId:artifactId[:extension[:classifier]][:version].  If extension is
         specified then version must be specified too. If any part is omitted or
         equal to empty string then corresponding part from artifact-coordinates
         will be substituted. Backreferences are supported in form @n,  where  n
         is an integer corresponding to brace in artifact-coordinates.

AUTHOR
     Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were writ‐
     ten by Stanislav Ochotnicky.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7),   mvn_build(7),   mvn_compat_version(7),    mvn_config(7),
     mvn_file(7), mvn_package(7), xmvn(1).

JAVAPACKAGES                       2026-06-03                       MVN_ALIAS(7)

A.2. mvn_artifact

MVN_ARTIFACT(7)                Java Packages Tools               MVN_ARTIFACT(7)

NAME
     mvn_artifact - request installation of Maven artifact

SYNOPSIS
     %mvn_artifact [options] model [artifact-file]

     %mvn_artifact [options] artifact-coordinates artifact-file

DESCRIPTION
     mvn_artifact  macro  marks specified Maven artifact to be installed by fur‐
     ther call to mvn_install. Multiple calls to mvn_artifact  and/or  mvn_build
     can be made to request installation of multiple artifacts.

OPTIONS
     --skip-dependencies
         Do not try to gather list of dependencies for given Maven artifact.

     -Dproperty=value
         Add artifact property

OPERANDS
     model
         Path  to  raw  project object model (POM) file to be associated and in‐
         stalled with artifact.

     artifact-file
         Path to file to be used as artifact file. If omitted then  no  artifact
         file is installed.

     artifact-coordinates
         Artifact  coordinates  specify  artifact  to be installed. If specified
         then no model file is installed with artifact. Coordinates are in  for‐
         mat  groupId:artifactId[:extension[:classifier]]:version.  If extension
         is omitted then "jar" is used. If  classifier  is  omitted  then  empty
         classifier  is used. For more information see XMvn Configuration Refer‐
         ence.

AUTHOR
     Written by Michal Srb.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7), mvn_build(7), mvn_install(7).

JAVAPACKAGES                       2026-06-03                    MVN_ARTIFACT(7)

A.3. mvn_build

MVN_BUILD(7)                   Java Packages Tools                  MVN_BUILD(7)

NAME
     mvn_build - build Maven project with XMvn

SYNOPSIS
     %mvn_build [options] [-- Maven-arguments]

DESCRIPTION
     mvn_build  macro builds Maven project by calling XMvn and generates reactor
     structure information to be used by mvn_install.

     By default Maven phase verify and goal javadoc:aggregate are  executed,  as
     well  as  some additional XMvn-specific goals or phases. If -f is specified
     then phase package is executed instead of verify. If -j is given then  goal
     javadoc:aggregate is skipped.

     Any  arguments  after  -- are passed directly to XMvn. See xmvn(1) for more
     information on availability of XMvn options.

OPTIONS
     -d, --xmvn-debug
         Enable XMvn debugging output. This option causes XMvn to write  verbose
         debugging  information  to  standard  output. Debugging information in‐
         cludes at least details about artifact resolution from system reposito‐
         ries.

     -f, --force
         Skip compilation and execution of unit and integration tests,  as  well
         as resolution of build dependencies with scope test. This option causes
         Maven phase package to be executed instead of default phase verify, de‐
         fines property maven.test.skip=true which disables compilation and exe‐
         cution of tests and causes XMvn to remove any project dependencies with
         scope test.

     -i, --skip-install
         Skip  artifact installation. This option disables generation of reactor
         structure information so that future calls to mvn_install will not  re‐
         sult in installation of artifacts produced in current Maven reactor.

     -j, --skip-javadoc
         Skip  javadoc  generation. This option skips running Maven Javadoc Plu‐
         gin. Useful for packages which don’t want to produce Java API  documen‐
         tation.

     -s, --singleton
         Enable  singleton  packaging  (one  artifact  per package). This option
         causes artifacts with identical artifactId to be installed as  part  of
         the  same subpackage. This behavior can be further customized by adding
         more specific packaging rules with mvn_package.

     -X, --debug
         Enable Maven debugging output. Implies -d. This option causes Maven  to
         write verbose debugging information to standard output.

ENVIRONMENT
     xmvn_bootstrap
         Run  XMvn in online mode. If xmvn_bootstrap RPM macro is defined to any
         value then XMvn is ran in online mode. Otherwise XMvn is ran in offline
         mode. Online mode of XMvn allows missing  dependency  artifacts  to  be
         fetched  from  remote repositories. This behavior is mostly useful when
         bootstrapping new packages, which dependecies have not yet  been  pack‐
         aged.

     _without_tests
         Defining this macro to any value is equivalent to -f option.

     _without_javadoc
         Defining this macro to any value is equivalent to -j option.

AUTHOR
     Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were writ‐
     ten by Stanislav Ochotnicky.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     mvn_alias(7), mvn_compat_version(7), mvn_config(7), mvn_file(7),  mvn_pack‐
     age(7), xmvn(1).

JAVAPACKAGES                       2026-06-03                       MVN_BUILD(7)

A.4. mvn_compat_version

MVN_COMPAT_VERSION(7)          Java Packages Tools         MVN_COMPAT_VERSION(7)

NAME
     mvn_compat_version - set version(s) for Maven artifact(s)

SYNOPSIS
     %mvn_compat_version artifact-coordinates version [version ...]

DESCRIPTION
     mvn_compat_version  macro  causes instructions for artifact installation to
     be added to XMvn reactor configuration. It is used to specify versions  for
     Maven artifacts.

     Specified  artifact  coordinates  must  match at least one artifact. If not
     then behavior is unspecified. It is possible to  specify  artifact  coordi‐
     nates  matching  multiple  artifacts, so one call to mvn_compat_version can
     affect installation of more than one artifact.

OPERANDS
     artifact-coordinates
         Artifact coordinates specify artifact(s) that this rule applies to. Co‐
         ordinates   are   in   format    groupId:artifactId[:extension[:classi‐
         fier]][:version]. If extension is specified then version must be speci‐
         fied  too.  If  any  part  is  omitted or equal to empty string then it
         matches any string. Wildcards and brace  expansions  are  supported  in
         each part. For more information see XMvn Configuration Reference.

     version
         Strings  specifying  artifact  version. Backreferences are supported in
         form @n, where n is an integer corresponding to brace in artifact-coor‐
         dinates.

AUTHOR
     Written by Stanislav Ochotnicky.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7),  mvn_alias(7),  mvn_build(7),  mvn_config(7), mvn_file(7),
     mvn_package(7), xmvn(1).

JAVAPACKAGES                       2026-06-03              MVN_COMPAT_VERSION(7)

A.5. mvn_config

MVN_CONFIG(7)                  Java Packages Tools                 MVN_CONFIG(7)

NAME
     mvn_config - specify custom XMvn configuration option

SYNOPSIS
     %mvn_config key value

DESCRIPTION
     mvn_config  macro  causes  custom configuration options to be added to XMvn
     reactor configuration.

OPERANDS
     key
         Configuration option key (unique name). This is XPath-like  address  of
         XML  configuration  node - list of XML nodes delimited by /. If unknown
         key is given, behavior is unspecified. For list of available  keys  see
         XMvn Configuration Reference.

     value
         Value of specified option. Must be either plain text or XML content. If
         value  format  is  inappropriate for particular option, behavior is un‐
         specified.

AUTHOR
     Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were writ‐
     ten by Stanislav Ochotnicky.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7),    mvn_alias(7),    mvn_build(7),   mvn_compat_version(7),
     mvn_file(7), mvn_package(7), xmvn(1).

JAVAPACKAGES                       2026-06-03                      MVN_CONFIG(7)

A.6. mvn_file

MVN_FILE(7)                    Java Packages Tools                   MVN_FILE(7)

NAME
     mvn_file - set installation location(s) for Maven artifact(s)

SYNOPSIS
     %mvn_file artifact-coordinates primary-file [secondary-file ...]

DESCRIPTION
     mvn_file macro causes instructions for artifact installation to be added to
     XMvn  reactor  configuration.  It  is used to control locations of artifact
     files in file system. (The exact meaning of artifact location is  dependant
     on  particular  implementation of XMvn repository into which artifacts will
     be installed.)

     Specified artifact coordinates must match at least  one  artifact.  If  not
     then  behavior  is  unspecified. It is possible to specify artifact coordi‐
     nates matching multiple artifacts, so one call to mvn_file can  affect  in‐
     stallation of more than one artifact.

OPERANDS
     artifact-coordinates
         Artifact coordinates specify artifact(s) that this rule applies to. Co‐
         ordinates    are   in   format   groupId:artifactId[:extension[:classi‐
         fier]][:version]. If extension is specified then version must be speci‐
         fied too. If any part is omitted or  equal  to  empty  string  then  it
         matches  any  string.  Wildcards  and brace expansions are supported in
         each part. For more information see XMvn Configuration Reference.

     primary-file
         Primary location of artifact file. This operand is passed  directly  to
         XMvn  installer. Its exact meaning is specific to particular repository
         implementation used to install given artifact. Backreferences are  sup‐
         ported  in form @n, where n is an integer corresponding to brace in ar‐
         tifact-coordinates.

     secondary-file
         Secondary location of artifact file. There can be any number  (zero  or
         more)  of  secondary artifact files. These operands are passed directly
         to XMvn installer. Their exact meaning is specific to particular repos‐
         itory implementation used to install given artifact. Backreferences are
         supported in form @n, where n is an integer corresponding to  brace  in
         artifact-coordinates.

AUTHOR
     Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were writ‐
     ten by Stanislav Ochotnicky.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7),   mvn_alias(7),    mvn_build(7),    mvn_compat_version(7),
     mvn_config(7), mvn_package(7), xmvn(1).

JAVAPACKAGES                       2026-06-03                        MVN_FILE(7)

A.7. mvn_install

MVN_INSTALL(7)                 Java Packages Tools                MVN_INSTALL(7)

NAME
     mvn_install - install Maven artifacts

SYNOPSIS
     %mvn_install [-X] [-J directory]

DESCRIPTION
     mvn_install macro installs Maven artifacts into %buildroot.

     Specification  of  artifacts  to  be  installed is taken from .xmvn-reactor
     file. This file  can  be  populated  using  mvn_build  and/or  mvn_artifact
     macros.

     Specification  how  artifacts  should  be installed is taken from installer
     settings section in XMvn configuration. See  XMvn  Configuration  Reference
     for  more  information.  Macros mvn_alias(7), mvn_build(7), mvn_compat_ver‐
     sion(7), mvn_config(7), mvn_file(7) and mvn_package(7) are capable of writ‐
     ing configuration that can affect behavior of mvn_install.

OPTIONS
     -X
         Enable debugging output. This option causes  XMvn  installer  to  write
         verbose debugging information to standard output.

     -J directory
         Specify  alternative  API documentation directory. By default API docu‐
         mentation is searched for in target/site/apidocs directory. The -J  op‐
         tion allows to override this default location.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7),  mvn_alias(7),  mvn_artifact(7),  mvn_build(7),   mvn_com‐
     pat_version(7), mvn_config(7), mvn_file(7), mvn_package(7), xmvn(1).

JAVAPACKAGES                       2026-06-03                     MVN_INSTALL(7)

A.8. mvn_package

MVN_PACKAGE(7)                 Java Packages Tools                MVN_PACKAGE(7)

NAME
     mvn_package - specify target package for Maven artifact(s)

SYNOPSIS
     %mvn_package artifact-coordinates [target-package]

DESCRIPTION
     mvn_package macro causes instructions for artifact installation to be added
     to  XMvn  reactor  configuration.  It  is used to specify target package to
     which Maven artifacts should be installed.

     Specified artifact coordinates must match at least  one  artifact.  If  not
     then  behavior  is  unspecified. It is possible to specify artifact coordi‐
     nates matching multiple artifacts, so one call to  mvn_package  can  affect
     installation of more than one artifact.

OPERANDS
     artifact-coordinates
         Artifact coordinates specify artifact(s) that this rule applies to. Co‐
         ordinates    are   in   format   groupId:artifactId[:extension[:classi‐
         fier]][:version]. If extension is specified then version must be speci‐
         fied too. If any part is omitted or  equal  to  empty  string  then  it
         matches  any  string.  Wildcards  and brace expansions are supported in
         each part. For more information see XMvn Configuration Reference.

     target-package
         Name of target (sub-)package to which matching artifacts  will  be  in‐
         stalled. Backreferences are supported in form @n, where n is an integer
         corresponding  to  brace  in  artifact-coordinates.  A special value of
         noinstall means that matching artifact(s) should not  be  installed  to
         any  package.  Special value of default means that matching artifact(s)
         should be installed into main package.  If  target-package  is  omitted
         value of __default is assumed.

AUTHOR
     Originally written by Mikolaj Izdebski. Versions 3.0.0 and later were writ‐
     ten by Stanislav Ochotnicky.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     gradle_build(7),   mvn_alias(7),    mvn_build(7),    mvn_compat_version(7),
     mvn_config(7), mvn_file(7), xmvn(1).

JAVAPACKAGES                       2026-06-03                     MVN_PACKAGE(7)

A.9. pom_add_dep

POM_ADD_DEP(7)                 Java Packages Tools                POM_ADD_DEP(7)

NAME
     pom_add_dep - add dependency to Maven POM file or Ivy module

SYNOPSIS
     %pom_add_dep  groupId:artifactId[:version[:scope]]  [POM-location]...  [ex‐
     tra-XML]

     %pom_add_dep  org:name[:rev[:conf[:transitive]]]   [Ivy-module-location]...
     [extra-XML]

     %pom_add_dep_mgmt  groupId:articId[:version[:scope]] [POM-location]... [ex‐
     tra-XML]

DESCRIPTION
     These macros patch specified POM or Ivy file adding a dependency  on  given
     Maven  artifact specified by artifact coordinates. pom_add_dep adds the de‐
     pendency to <dependencies> XML node, while pom_add_dep_mgmt adds it to <de‐
     pendencyManagement>.

     groupId and artifactId are identifiers of Maven artifact  on  which  depen‐
     dency  is  to be added. They must be specified. If version is not specified
     then default value of "any" is used. If scope  is  not  specified  then  no
     scope is defined (Maven defaults to "compile" in this case).

     When  modifying  Ivy modules, the org, name and rev correspond to the Maven
     groupId and artifactId and version. Org and name must be  specified,  other
     attributes  use defaults. The conf attribute specifies the configuration in
     which the dependency  should  apply.  The  transitive  attribute  specifies
     whether  the  dependency  should also pull in it’s dependencies. It accepts
     boolean values - true or false. When unspecified Ivy defaults to true.

     POM location can be either a full path to the POM or Ivy file, or a path to
     the directory containing pom.xml or ivy.xml. If POM location is  not  given
     then  pom.xml  or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations which will be processed.

     Extra XML is additional XML code to be added into  the  <dependency>  node.
     This parameter can be ommited, in which case no extra XML is appended.

EXAMPLES
     %pom_add_dep foo:bar baz - this call adds dependency on artifact foo:bar to
     baz/pom.xml file.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_parent(7),   pom_add_plugin(7),   pom_disable_module(7),    pom_re‐
     move_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7),
     pom_set_parent(7),  pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                     POM_ADD_DEP(7)

A.10. pom_add_parent

POM_ADD_PARENT(7)              Java Packages Tools             POM_ADD_PARENT(7)

NAME
     pom_add_parent - add parent POM reference to POM file

SYNOPSIS
     %pom_add_parent groupId:artifactId[:version] [POM-location]...

DESCRIPTION
     This macro patches specified POM file adding a reference to parent POM with
     specified groupId, artifactId and version.

     groupId  and  artifactId are identifiers of Maven group and artifact of the
     POM to be referenced as parent POM. They must be specified. If  version  is
     not specified then default value of "any" is used.

     POM  location  can  be either a full path to the POM file, or a path to the
     directory containing pom.xml. If POM location is  not  given  then  pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed.

EXAMPLES
     %pom_add_parent  foo:bar baz - this call adds reference to parent POM arti‐
     fact foo:bar to baz/pom.xml file.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),     pom_add_plugin(7),    pom_disable_module(7),    pom_re‐
     move_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7),
     pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7),  pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                  POM_ADD_PARENT(7)

A.11. pom_add_plugin

POM_ADD_PLUGIN(7)              Java Packages Tools             POM_ADD_PLUGIN(7)

NAME
     pom_add_plugin - add plugin invocation to POM file

SYNOPSIS
     %pom_add_plugin groupId:artifactId[:version] [POM-location]... [extra-XML]

DESCRIPTION
     This  macro  patches  specified  POM file adding plugin invocation of given
     groupId and artifactId.

     groupId and artifactId are identifiers of Maven plugin  artifact  of  which
     invocation  is  to be added. groupId may be ommited, in which case value of
     "org.apache.maven.plugins" is used as default. artifactId  must  be  speci‐
     fied. If version is not specified then default value of "any" is used.

     POM  location  can  be either a full path to the POM file, or a path to the
     directory containing pom.xml. If POM location is  not  given  then  pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed.

     Extra  XML  is additional XML code to be added into the <plugin> node. This
     parameter can be ommited, in which case no extra XML is appended.

EXAMPLES
     %pom_add_plugin com.example:plugin foo - this call adds invocation of  plu‐
     gin com.example:plugin to foo/pom.xml.

     %pom_add_plugin :maven-compiler-plugin . "<target>1.5</target>" - this call
     adds invocation of Maven Compiler Plugin with target configured to 1.5.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),    pom_add_parent(7),    pom_disable_module(7),     pom_re‐
     move_dep(7), pom_remove_parent(7), pom_remove_plugin(7), pom_set_parent(7),
     pom_xpath_inject(7),       pom_xpath_remove(7),       pom_xpath_replace(7),
     pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                  POM_ADD_PLUGIN(7)

A.12. pom_change_dep

POM_CHANGE_DEP(7)              Java Packages Tools             POM_CHANGE_DEP(7)

NAME
     pom_change_dep - change dependency in Maven POM file or Ivy module

SYNOPSIS
     %pom_change_dep   [OPTIONS]   SOURCE_ARTIFACT  CHANGED_ARTIFACT  [POM-loca‐
     tion]... [extra-XML]

     %pom_change_dep [OPTIONS] SOURCE_ARTIFACT CHANGED_ARTIFACT  [Ivy-module-lo‐
     cation]... [extra-XML]

OPTIONS
     -r
         Work  in  recursive  mode.  That  means  that  given dependency is also
         changed in all enabled submodules of given POM file(s). Has  no  effect
         if the file is not Maven POM.

     -f
         Do  not  throw an error when one of the specified files doesn’t contain
         given dependency.

DESCRIPTION
     These macros patch specified POM or Ivy file changing a dependency on given
     Maven artifact specified by artifact coordinates to artifact  specified  by
     second set of Maven coordinates. The artifact specification has same format
     as  %pom_add_dep.  The omitted or empty parts in second artifact specifica‐
     tion cause the original value to be left unmodified.  Supplying  a  special
     value  of - for given part causes that part of artifact specification to be
     deleted.

     POM location can be either a full path to the POM or Ivy file, or a path to
     the directory containing pom.xml or ivy.xml. If POM location is  not  given
     then  pom.xml  or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations which will be processed.

     Extra XML is additional XML code to be added into  the  <dependency>  node.
     This parameter can be ommited, in which case no extra XML is appended.

EXAMPLES
     pom_change_dep foo: com.example.foo: - this call changes groupId of all de‐
     pendencies  which  have  groupId  foo to com.example.foo. Their artifactId,
     versions and other possible parts are left unmodified.

AUTHOR
     Written by Michael Simacek.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),   pom_add_parent(7),   pom_add_plugin(7),  pom_disable_mod‐
     ule(7),  pom_remove_dep(7),   pom_remove_parent(7),   pom_remove_plugin(7),
     pom_set_parent(7),  pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                  POM_CHANGE_DEP(7)

A.13. pom_disable_module

POM_DISABLE_MODULE(7)          Java Packages Tools         POM_DISABLE_MODULE(7)

NAME
     pom_disable_module - disable given project module in POM file

SYNOPSIS
     %pom_disable_module module-name [POM-location]...

DESCRIPTION
     This  macro  patches  specified  POM file not to contain reference to given
     project module.

     Module name is the exact name of the module to be disabled. It must not  be
     ommited.

     POM  location  can  be either a full path to the POM file, or a path to the
     directory containing pom.xml. If POM location is  not  given  then  pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed.

EXAMPLES
     %pom_disable_module  nonfree  - this call removes aggregated module nonfree
     from POM file in current working directory.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),  pom_add_plugin(7),  pom_remove_dep(7),
     pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_par‐
     ent(7),  pom_xpath_inject(7),  pom_xpath_remove(7),   pom_xpath_replace(7),
     pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03              POM_DISABLE_MODULE(7)

A.14. pom_remove_dep

POM_REMOVE_DEP(7)              Java Packages Tools             POM_REMOVE_DEP(7)

NAME
     pom_remove_dep - remove dependency on Maven artifact from POM file

SYNOPSIS
     %pom_remove_dep   [OPTIONS]   *:*[artifactId][:version[:scope]]  [POM-loca‐
     tion]...

     %pom_remove_dep  [OPTIONS]  *:*[name][:rev[:conf[:transitive]]]   [Ivy-mod‐
     ule-location]...

OPTIONS
     -r
         Work in recursive mode. That means that dependency is also removed from
         all enabled submodules of given POM file(s).

     -f
         Do  not  throw an error when one of the specified files doesn’t contain
         given dependency.

DESCRIPTION
     This macro patches specified POM file not to contain dependencies on  given
     Maven artifact.

     groupId  and  artifactId are identifiers of Maven group and artifact of the
     module on which dependency is to be removed. If they are ommited  then  all
     identifiers are matched.

     When  modifying  Ivy  modules,  the  org  and  name correspond to the Maven
     groupId and artifactId.

     POM location can be either a full path to the POM or Ivy file, or a path to
     the directory containing pom.xml or ivy.xml. If POM location is  not  given
     then  pom.xml  or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations. If the dependency is not found in all of given  files,  the
     command raises an error. This can be overriden with the -f option.

EXAMPLES
     %pom_remove_dep  com.example:  -  this call removes dependency on all arti‐
     facts with groupId com.example from POM in current working directory.

     %pom_remove_dep boo:bar target/location - this call removes  dependency  on
     artifacts with groupId foo and artifactId bar from target/location/pom.xml.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),   pom_add_plugin(7),   pom_disable_mod‐
     ule(7),   pom_remove_parent(7),   pom_remove_plugin(7),  pom_change_dep(7),
     pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7),  pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                  POM_REMOVE_DEP(7)

A.15. pom_remove_parent

POM_REMOVE_PARENT(7)           Java Packages Tools          POM_REMOVE_PARENT(7)

NAME
     pom_remove_parent - remove parent POM reference from POM file

SYNOPSIS
     %pom_remove_parent [POM-location]...

DESCRIPTION
     This macro patches specified POM file removing reference to parent POM.

     POM  location  can  be either a full path to the POM file, or a path to the
     directory containing pom.xml. If POM location is  not  given  then  pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed.

EXAMPLES
     %pom_remove_parent target/location - this call removes parent POM reference
     from target/location/pom.xml.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),   pom_add_plugin(7),   pom_disable_mod‐
     ule(7),    pom_remove_dep(7),    pom_remove_plugin(7),   pom_change_dep(7),
     pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7),  pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03               POM_REMOVE_PARENT(7)

A.16. pom_remove_plugin

POM_REMOVE_PLUGIN(7)           Java Packages Tools          POM_REMOVE_PLUGIN(7)

NAME
     pom_remove_plugin - remove Maven plugin invocation from POM file

SYNOPSIS
     %pom_remove_plugin  [OPTIONS]  *:*[artifactId][:version[:scope]] [POM-loca‐
     tion]...

OPTIONS
     -r
         Work in recursive mode. That means that plugin is also removed from all
         enabled submodules of given POM file(s).

     -f
         Do not throw an error when one of the specified files  doesn’t  contain
         given dependency.

DESCRIPTION
     This  macro  patches specified POM file not to contain invocations of given
     Maven plugin.

     groupId and artifactId are identifiers of Maven group and artifact  of  the
     plugin  which  invocation  is  to  be removed. If they are ommited then all
     identifiers are matched.

     POM location can be either a full path to the POM file, or a  path  to  the
     directory  containing  pom.xml.  If  POM location is not given then pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed. You can specify more file locations.

EXAMPLES
     %pom_remove_plugin :maven-shade-plugin - this call  removes  invocation  of
     Maven Shade Plugin from POM in current working directory.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),   pom_add_plugin(7),   pom_disable_mod‐
     ule(7),    pom_remove_dep(7),    pom_remove_parent(7),   pom_change_dep(7),
     pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7),  pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03               POM_REMOVE_PLUGIN(7)

A.17. pom_set_parent

POM_SET_PARENT(7)              Java Packages Tools             POM_SET_PARENT(7)

NAME
     pom_set_parent - set parent POM reference in POM file

SYNOPSIS
     %pom_set_parent groupId:artifactId[:version] [POM-location]...

DESCRIPTION
     This  macro  patches  specified POM file setting reference to parent POM to
     specified groupId, artifactId and version.

     This macros first removes parent POM reference and then  adds  a  new  one.
     It’s  (more  or  less) equivalent to call to %pom_remove_parent followed by
     invocation of %pom_add_parent. See  pom_remove_parent(7)  and  pom_add_par‐
     ent(7) for more information about parameters.

     POM  location  can  be either a full path to the POM file, or a path to the
     directory containing pom.xml. If POM location is  not  given  then  pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed.

EXAMPLES
     %pom_set_parent  com.example:example-parent  module - this call sets parent
     POM of module/pom.xml to com.example:example-parent.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),   pom_add_parent(7),   pom_add_plugin(7),  pom_disable_mod‐
     ule(7),  pom_remove_dep(7),   pom_remove_parent(7),   pom_remove_plugin(7),
     pom_change_dep(7),  pom_xpath_inject(7), pom_xpath_remove(7), pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                  POM_SET_PARENT(7)

A.18. pom_xpath_disable

POM_XPATH_DISABLE(7)           Java Packages Tools          POM_XPATH_DISABLE(7)

NAME
     pom_xpath_disable - Disable all modules whose POM files satisfy given XPath
     condition

SYNOPSIS
     %pom_xpath_disable XPath-expression [POM-location]...

DESCRIPTION
     This macro recursively walks all enabled submodules of given POM and evalu‐
     ates  given  XPath  expression  on  them.  If the expression returns a true
     value, matching submodule is disabled. Values considered true  are  defined
     by  XPath specification as either true boolean value (i.e. returned by com‐
     parisons), non-empty node set, non-empty string or non-zero number.

     If the main module (specified by POM-location or pom.xml by  default)  also
     satisfies  the condition, processing is aborted prior to making any changes
     and an error is raised. When none of the modules satisfy it,  an  error  is
     also raised.

     POM  location  can  be either a full path to the POM file, or a path to the
     directory containing pom.xml. If POM location is  not  given  then  pom.xml
     from current working directory is used. You can specify more file locations
     which will be processed.

EXAMPLES
     %pom_xpath_disable  "/pom:project/pom:classifier = 'test'" - this call dis‐
     ables all modules with classifier test

     %pom_xpath_disable /pom:project/pom:packaging - this call disables all sum‐
     bodules that explicitly specify packaging

AUTHOR
     Written by Michael Simacek.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),  pom_add_plugin(7),  pom_remove_dep(7),
     pom_remove_parent(7), pom_remove_plugin(7), pom_change_dep(7), pom_set_par‐
     ent(7),  pom_xpath_inject(7),  pom_xpath_remove(7),   pom_xpath_replace(7),
     pom_xpath_set(7). pom_disable_module(7).

JAVAPACKAGES                       2026-06-03               POM_XPATH_DISABLE(7)

A.19. pom_xpath_inject

POM_XPATH_INJECT(7)            Java Packages Tools           POM_XPATH_INJECT(7)

NAME
     pom_xpath_inject - inject code into XML file

SYNOPSIS
     %pom_xpath_inject XPath XML-code [XML-file-location]...

DESCRIPTION
     This  macro  patches specified XML file appending given code as children of
     all XML nodes described by the XPath expression.

     XPath is an expression describing a set of XML nodes in  the  XML  file  to
     which  child  code  is to be appended. It must be a properly formated XPath
     1.0 expression, as described in http://www.w3.org/TR/xpath/.

     Maven POM files use specific XML namespace
     http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be
     explicitly specified in XPath expressions by prefixing all node names with
     pom: (i.e. pom:modelVersion).

     Many other XML formats also use namespaces which you have to explicitly
     specify. This script will use the namespace prefix names from the xmlns de‐
     clarations in the document’s root element. So if the document begins with
     <root xmlns:my="myurl.com"> you would select the root node with XPath ex‐
     pression /my:root. If the document specifies a default namespace (e.g.
     xmlns="myurl.com") use the prefix named default to acces elements in that
     namespace.

     XML location can be either a full path to the XML, or a path to the direc‐
     tory containing pom.xml or ivy.xml. If XML location is not given then
     pom.xml or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations.

EXAMPLES
     %pom_xpath_inject pom:project "<packaging>war</packaging>" - this call sets
     packaging of POM in current working directory to war.

     %pom_xpath inject configurations '<conf name="test"/>' - this  adds  a  new
     configuration to the Ivy file in current working directory.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),   pom_add_plugin(7),   pom_disable_mod‐
     ule(7),   pom_remove_dep(7),   pom_remove_parent(7),  pom_remove_plugin(7),
     pom_change_dep(7),  pom_set_parent(7),  pom_xpath_remove(7),  pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                POM_XPATH_INJECT(7)

A.20. pom_xpath_remove

POM_XPATH_REMOVE(7)            Java Packages Tools           POM_XPATH_REMOVE(7)

NAME
     pom_xpath_remove - remove a node from XML file

SYNOPSIS
     %pom_xpath_remove [OPTIONS] XPath [XML-file-location]...

OPTIONS
     -r
         Work in recursive mode. That means that given node is also removed from
         all  enabled submodules of given POM file(s). Has no effect if the file
         is not Maven POM.

     -f
         Do not throw an error when one of the specified files  doesn’t  contain
         given node.

DESCRIPTION
     This  macro  patches specified POM file removing all XML nodes described by
     the XPath expression. This also works on attributes and text nodes.

     XPath is an expression describing a set of XML nodes to be removed from the
     POM file. It must be a properly formated XPath 1.0 expression, as described
     in http://www.w3.org/TR/xpath/.

     Maven POM files use specific XML namespace
     http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be
     explicitly specified in XPath expressions by prefixing all node names with
     pom (i.e. pom:modelVersion).

     Many other XML formats also use namespaces which you have to explicitly
     specify. This script will use the namespace prefix names from the xmlns de‐
     clarations in the document’s root element. So if the document begins with
     <root xmlns:my="myurl.com"> you would select the root node with XPath ex‐
     pression /my:root. If the document specifies a default namespace (eg
     xmlns="myurl.com") use the prefix named default to acces elements in that
     namespace.

     XML location can be either a full path to the XML, or a path to the direc‐
     tory containing pom.xml or ivy.xml. If XML location is not given then
     pom.xml or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations.

EXAMPLES
     %pom_xpath_remove pom:project/pom:reporting - this call  removes  reporting
     section from POM in current working directory.

     %pom_xpath_remove 'ivy:configure' build.xml - this call disables loading of
     ivy  configuration  in  build.xml file. Note the use of ivy namespace which
     was declared in the document as xmlns:ivy="antlib:org.apache.ivy.ant".

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs should be reported  through  Java  Packages  Tools  issue  tracker  at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),   pom_add_parent(7),   pom_add_plugin(7),  pom_disable_mod‐
     ule(7),  pom_remove_dep(7),   pom_remove_parent(7),   pom_remove_plugin(7),
     pom_change_dep(7),  pom_set_parent(7),  pom_xpath_inject(7),  pom_xpath_re‐
     place(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03                POM_XPATH_REMOVE(7)

A.21. pom_xpath_replace

POM_XPATH_REPLACE(7)           Java Packages Tools          POM_XPATH_REPLACE(7)

NAME
     pom_xpath_replace - replace XML node from XML file with given code

SYNOPSIS
     %pom_xpath_replace XPath XML-code [XML-file-location]...

OPTIONS
     -r
         Work  in recursive mode. That means that given node is also replaced in
         all enabled submodules of given POM file(s). Has no effect if the  file
         is not Maven POM.

     -f
         Do  not  throw an error when one of the specified files doesn’t contain
         given node.

DESCRIPTION
     This macro patches specified POM file removing all XML nodes  described  by
     the XPath expression and injecting given XML code in their place.

     XPath is an expression describing a set of XML nodes to be removed from the
     POM file. It must be a properly formated XPath 1.0 expression, as described
     in http://www.w3.org/TR/xpath/.

     Maven POM files use specific XML namespace
     http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be
     explicitly specified in XPath expressions by prefixing all node names with
     pom (i.e. pom:modelVersion).

     Many other XML formats also use namespaces which you have to explicitly
     specify. This script will use the namespace prefix names from the xmlns de‐
     clarations in the document’s root element. So if the document begins with
     <root xmlns:my="myurl.com"> you would select the root node with XPath ex‐
     pression /my:root. If the document specifies a default namespace (eg
     xmlns="myurl.com") use the prefix named default to acces elements in that
     namespace.

     XML location can be either a full path to the XML, or a path to the direc‐
     tory containing pom.xml or ivy.xml. If XML location is not given then
     pom.xml or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),   pom_add_plugin(7),   pom_disable_mod‐
     ule(7),   pom_remove_dep(7),   pom_remove_parent(7),  pom_remove_plugin(7),
     pom_change_dep(7),  pom_set_parent(7),  pom_xpath_inject(7),  pom_xpath_re‐
     move(7), pom_xpath_set(7).

JAVAPACKAGES                       2026-06-03               POM_XPATH_REPLACE(7)

A.22. pom_xpath_set

POM_XPATH_SET(7)               Java Packages Tools              POM_XPATH_SET(7)

NAME
     pom_xpath_set - set contents of XML node from XML file

SYNOPSIS
     %pom_xpath_set XPath new-contents [XML-file-location]

DESCRIPTION
     This  macro  patches specified POM file replacing contents of all XML nodes
     described by the XPath expression with given new text content.  This  works
     on both elements and attributes.

     XPath is an expression describing a set of XML nodes to be removed from the
     POM file. It must be a properly formated XPath 1.0 expression, as described
     in http://www.w3.org/TR/xpath/.

     Maven POM files use specific XML namespace
     http://maven.apache.org/POM/4.0.0 as default. This namespace needs to be
     explicitly specified in XPath expressions by prefixing all node names with
     pom (i.e. pom:modelVersion).

     Many other XML formats also use namespaces which you have to explicitly
     specify. This script will use the namespace prefix names from the xmlns de‐
     clarations in the document’s root element. So if the document begins with
     <root xmlns:my="myurl.com"> you would select the root node with XPath ex‐
     pression /my:root. If the document specifies a default namespace (eg
     xmlns="myurl.com") use the prefix named default to acces elements in that
     namespace.

     XML location can be either a full path to the XML, or a path to the direc‐
     tory containing pom.xml or ivy.xml. If XML location is not given then
     pom.xml or ivy.xml from current working directory is used. When both
     pom.xml and ivy.xml are present, pom.xml is processed. You can specify more
     file locations.

AUTHOR
     Written by Mikolaj Izdebski.

REPORTING BUGS
     Bugs  should  be  reported  through  Java  Packages  Tools issue tracker at
     Github: https://github.com/fedora-java/javapackages/issues.

SEE ALSO
     pom_add_dep(7),  pom_add_parent(7),   pom_add_plugin(7),   pom_disable_mod‐
     ule(7),   pom_remove_dep(7),   pom_remove_parent(7),  pom_remove_plugin(7),
     pom_set_parent(7), pom_xpath_inject(7), pom_xpath_remove(7),  pom_xpath_re‐
     place(7).

JAVAPACKAGES                       2026-06-03                   POM_XPATH_SET(7)