[maven-toolchains-plugin] Build with xmvn
by Mikolaj Izdebski
commit 262d5da6a5803367702ec46d9b06499afaa372c7
Author: Mikolaj Izdebski <mizdebsk(a)redhat.com>
Date: Fri Mar 8 13:46:37 2013 +0100
Build with xmvn
- Add missing LICENSE and NOTICE files
- Drop Plexus container patch; Resolves: rhbz#914176
maven-toolchains-plugin-plexus.patch | 26 -----------------
maven-toolchains-plugin.spec | 52 ++++++++--------------------------
2 files changed, 12 insertions(+), 66 deletions(-)
---
diff --git a/maven-toolchains-plugin.spec b/maven-toolchains-plugin.spec
index efaba2a..d1f4cf5 100644
--- a/maven-toolchains-plugin.spec
+++ b/maven-toolchains-plugin.spec
@@ -1,27 +1,12 @@
Name: maven-toolchains-plugin
Version: 1.0
-Release: 6%{?dist}
+Release: 7%{?dist}
Summary: Maven plugin for sharing configuration across projects
-
-Group: Development/Libraries
License: ASL 2.0
URL: http://maven.apache.org/plugins/maven-toolchains-plugin/
Source0: http://repo1.maven.org/maven2/org/apache/maven/plugins/%{name}/%{version}...
-# Dep on plexus-container-default is needed, otherwise a wrong implementation of
-# PlexusConfiguration class is taken from sisu-inject-plexus.jar
-Patch0: %{name}-plexus.patch
-
BuildArch: noarch
-
-BuildRequires: java
BuildRequires: maven-local
-BuildRequires: jpackage-utils
-BuildRequires: plexus-container-default
-BuildRequires: maven-surefire-provider-junit4
-
-Requires: java
-Requires: maven
-Requires: jpackage-utils
%description
The Toolchains Plugins allows to share configuration across plugins. For
@@ -31,45 +16,32 @@ allows to control environmental constraints in the build.
%package javadoc
Summary: API documentation for %{name}
-Group: Documentation
Requires: jpackage-utils
%description javadoc
The API documentation of %{name}.
-
%prep
%setup -q
-%patch0 -p1
-
-rm -rf bin
%build
-mvn-rpmbuild install javadoc:aggregate
+%mvn_build
%install
-# JAR
-install -Dpm 644 target/%{name}-%{version}.jar %{buildroot}%{_javadir}/%{name}.jar
-
-# POM
-install -Dpm 644 pom.xml %{buildroot}%{_mavenpomdir}/JPP-%{name}.pom
-%add_maven_depmap JPP-%{name}.pom %{name}.jar
-
-# JavaDoc
-install -Ddm 755 %{buildroot}%{_javadocdir}/%{name}
-cp -pr target/site/apidocs/* %{buildroot}%{_javadocdir}/%{name}
+%mvn_install
+%files -f .mfiles
+%doc LICENSE NOTICE
-%files
-%{_javadir}/%{name}.jar
-%{_mavenpomdir}/JPP-%{name}.pom
-%{_mavendepmapfragdir}/%{name}
-
-%files javadoc
-%doc %{_javadocdir}/%{name}
-
+%files javadoc -f .mfiles-javadoc
+%doc LICENSE NOTICE
%changelog
+* Fri Mar 8 2013 Mikolaj Izdebski <mizdebsk(a)redhat.com> - 1.0-7
+- Build with xmvn
+- Add missing LICENSE and NOTICE files
+- Drop Plexus container patch; Resolves: rhbz#914176
+
* Thu Feb 14 2013 Fedora Release Engineering <rel-eng(a)lists.fedoraproject.org> - 1.0-6
- Rebuilt for https://fedoraproject.org/wiki/Fedora_19_Mass_Rebuild
11 years, 3 months
[javapackages] [doc] Add a snippet about virtual packages
by Mikolaj Izdebski
commit 13bc4e17b3d91d904fecb2c80bbcea226c26267a
Author: Mikolaj Izdebski <mizdebsk(a)redhat.com>
Date: Fri Mar 8 13:04:06 2013 +0100
[doc] Add a snippet about virtual packages
doc/ideas/virtual_artifact_packages.md | 20 ++++++++++++++++++++
1 files changed, 20 insertions(+), 0 deletions(-)
---
diff --git a/doc/ideas/virtual_artifact_packages.md b/doc/ideas/virtual_artifact_packages.md
new file mode 100644
index 0000000..a4c4c9f
--- /dev/null
+++ b/doc/ideas/virtual_artifact_packages.md
@@ -0,0 +1,20 @@
+Virtual artifact packages
+-------------------------
+
+Each Maven artifact packaged into an RPM package has corresponding
+virtual package named `mvn(groupId:artifactId)`, created automatically
+by the build system. If more than one artifact is included in a
+physical package then one virtual package is created for each of them.
+Virtual packages are created even for artifact aliases, se below in
+_Aliases_ section.
+
+For example, if package `foo` contains artifacts
+`com.example:foo-artifact` and `bar:baz` then two virtual packages
+will be created for package `foo`: one named
+`mvn(com.example:foo-artifact)` and the other named `mvn(bar:baz)`.
+
+Craeting virtual packages for Maven artifacts has several advantages.
+It makes it easy to search which package provides given artifact, for
+example `repoquery --whatprovides 'mvn(bar:baz)'` in the previous
+example would return `foo`. Virtual packages also make it easier to
+generate automatic dependencies.
11 years, 3 months
[javapackages] [doc] Add example java project
by Stanislav Ochotnicky
commit 534e96beb28fcaaceb6032a9ca9e9be2b2a6fae4
Author: Stanislav Ochotnicky <sochotnicky(a)redhat.com>
Date: Fri Mar 8 12:18:51 2013 +0100
[doc] Add example java project
This should help with explaining classpaths, packages etc from POV of
packagers. Linking to traditional helloworld tutorials probably wouldn't work
because information needed for packaging are mixed with Java language
information.
doc/basics.txt | 75 +++++++++++++++++++-
doc/java_project/Makefile | 14 ++++
.../org/fedoraproject/helloworld/HelloWorld.java | 15 ++++
.../org/fedoraproject/helloworld/input/Input.java | 11 +++
.../fedoraproject/helloworld/output/Output.java | 9 +++
5 files changed, 122 insertions(+), 2 deletions(-)
---
diff --git a/doc/basics.txt b/doc/basics.txt
index 173d3fb..4be89f8 100644
--- a/doc/basics.txt
+++ b/doc/basics.txt
@@ -22,12 +22,83 @@ specified in the
link:http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html[JAR File
Specification].
-Classic compiled applications use linker to find dependencies (linked
+
+==== 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
+link:http://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html[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 $name" where $name is from step one
+
+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
+[source,shell]
+------
+$ 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
+[source,java]
+------
+include::java_project/src/org/fedoraproject/helloworld/HelloWorld.java[]
+------
+
+
+
+.Java Namespaces
+[source,shell]
+------
+org/fedoraproject/helloworld/input/Input.java
+org/fedoraproject/helloworld/output/Output.java
+org/fedoraproject/helloworld/HelloWorld.java
+------
+
+Above example makes use of three separate namespaces:
+
+ - 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()` function
+ - Adding required JAR files on JVM classpath
+
+Classic compiled applications use dynamic linker to find dependencies (linked
libraries), Python interpreter has predefined directories where it searches 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.
+before invoking the JVM and running the application itself. Note that this is
+not necessary for libraries.
+
+
+
// JVM, classpaths, imports, POM files, JAR files
diff --git a/doc/java_project/Makefile b/doc/java_project/Makefile
new file mode 100644
index 0000000..3db1e32
--- /dev/null
+++ b/doc/java_project/Makefile
@@ -0,0 +1,14 @@
+#!/bin/bash
+
+compile:
+ rm -rf compiled/
+ mkdir compiled/
+ javac `find . -name *java` -d compiled -cp src/
+
+jar: compile
+ rm -f helloworld.jar
+ jar cfe helloworld.jar org.fedoraproject.helloworld.HelloWorld -C compiled .
+
+
+clean:
+ rm -rf *jar compiled
diff --git a/doc/java_project/src/org/fedoraproject/helloworld/HelloWorld.java b/doc/java_project/src/org/fedoraproject/helloworld/HelloWorld.java
new file mode 100644
index 0000000..6f6a401
--- /dev/null
+++ b/doc/java_project/src/org/fedoraproject/helloworld/HelloWorld.java
@@ -0,0 +1,15 @@
+
+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);
+ }
+}
diff --git a/doc/java_project/src/org/fedoraproject/helloworld/input/Input.java b/doc/java_project/src/org/fedoraproject/helloworld/input/Input.java
new file mode 100644
index 0000000..4ac348d
--- /dev/null
+++ b/doc/java_project/src/org/fedoraproject/helloworld/input/Input.java
@@ -0,0 +1,11 @@
+
+package org.fedoraproject.helloworld.input;
+
+import java.util.Scanner;
+
+public class Input {
+ public static String getInput() {
+ Scanner s = new Scanner(System.in);
+ return s.next();
+ }
+}
diff --git a/doc/java_project/src/org/fedoraproject/helloworld/output/Output.java b/doc/java_project/src/org/fedoraproject/helloworld/output/Output.java
new file mode 100644
index 0000000..01b9cc6
--- /dev/null
+++ b/doc/java_project/src/org/fedoraproject/helloworld/output/Output.java
@@ -0,0 +1,9 @@
+package org.fedoraproject.helloworld.output;
+
+public class Output {
+ public static void output(String s) {
+ System.out.println("Hello World from " + s);
+ }
+}
+
+
11 years, 3 months
[javapackages] Add effectivePomDir to XMvn configuration
by Mikolaj Izdebski
commit aacf08bd9aa213d3d80268b6a0054573d38ceafb
Author: Mikolaj Izdebski <mizdebsk(a)redhat.com>
Date: Fri Mar 8 12:21:11 2013 +0100
Add effectivePomDir to XMvn configuration
configs/configuration-19.xml | 1 +
1 files changed, 1 insertions(+), 0 deletions(-)
---
diff --git a/configs/configuration-19.xml b/configs/configuration-19.xml
index 2d2b773..d56f58a 100644
--- a/configs/configuration-19.xml
+++ b/configs/configuration-19.xml
@@ -53,6 +53,7 @@
<jarDir>usr/share/java</jarDir>
<jniDir>usr/lib/java</jniDir>
<pomDir>usr/share/maven-poms</pomDir>
+ <effectivePomDir>usr/share/maven-effective-poms</effectivePomDir>
<metadataDir>usr/share/maven-fragments</metadataDir>
<installRoot>.xmvn/root</installRoot>
</installerSettings>
11 years, 3 months
[javapackages] Add configuration options for effective POMs
by Mikolaj Izdebski
commit fa90a63f865c39dd72d949e2ea0dbe36abe0e187
Author: Mikolaj Izdebski <mizdebsk(a)redhat.com>
Date: Fri Mar 8 10:28:39 2013 +0100
Add configuration options for effective POMs
configs/configuration-19.xml | 6 ++++++
1 files changed, 6 insertions(+), 0 deletions(-)
---
diff --git a/configs/configuration-19.xml b/configs/configuration-19.xml
index 603e777..2d2b773 100644
--- a/configs/configuration-19.xml
+++ b/configs/configuration-19.xml
@@ -44,6 +44,12 @@
</blacklist>
</resolverSettings>
<installerSettings>
+ <enableRawPoms>true</enableRawPoms>
+ <enableEffectivePoms>true</enableEffectivePoms>
+ <pomRawModel>true</pomRawModel>
+ <pomEffectiveModel>false</pomEffectiveModel>
+ <jarRawModel>true</jarRawModel>
+ <jarEffectiveModel>true</jarEffectiveModel>
<jarDir>usr/share/java</jarDir>
<jniDir>usr/lib/java</jniDir>
<pomDir>usr/share/maven-poms</pomDir>
11 years, 3 months
[javapackages] [doc] Add a few initial conventions
by Stanislav Ochotnicky
commit 995ab36bce5a399e59072550c60529f00269c60f
Author: Stanislav Ochotnicky <sochotnicky(a)redhat.com>
Date: Thu Mar 7 18:14:52 2013 +0100
[doc] Add a few initial conventions
doc/README | 4 ++++
1 files changed, 4 insertions(+), 0 deletions(-)
---
diff --git a/doc/README b/doc/README
index 644bcae..cdec3a2 100644
--- a/doc/README
+++ b/doc/README
@@ -7,3 +7,7 @@ Fedora right now:
ln -s $(pwd)/asciidoc/asciidoc.py ~/bin/asciidoc
And of course add ~/bin to your PATH before running make
+
+Conventions:
+ JAR - always capital unless mentioning filename
+ POM - always capital unless mentioning filename
11 years, 3 months
[javapackages] [doc] Use JAR consistently
by Stanislav Ochotnicky
commit cc343c291f4545a33709b5357e694a87cd2c87e6
Author: Stanislav Ochotnicky <sochotnicky(a)redhat.com>
Date: Thu Mar 7 18:13:54 2013 +0100
[doc] Use JAR consistently
doc/Makefile | 4 ++--
doc/helper_macros.txt | 36 ++++++++++++++++++------------------
doc/index.txt | 2 +-
3 files changed, 21 insertions(+), 21 deletions(-)
---
diff --git a/doc/Makefile b/doc/Makefile
index 7f3af5d..3d811b6 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,7 +1,7 @@
all: index.html
-index.html: index.txt
- asciidoc -b html5 -a icons -a toc2 -a theme=flask index.txt
+index.html: *.txt
+ asciidoc -b html5 -a icons -a toc2 -a toclevels=3 -a theme=flask index.txt
.images_uploaded: images/* images/icons/*
scp -r images/ fedorapeople.org:public_html/java-packaging-howto/
diff --git a/doc/helper_macros.txt b/doc/helper_macros.txt
index 0b8ab38..960b357 100644
--- a/doc/helper_macros.txt
+++ b/doc/helper_macros.txt
@@ -107,23 +107,23 @@ Using `%pom_*` macros not only increases readability of the spec file, but also
==== add_maven_depmap macro
-Maven identifies jar files by a set of strings: groupId, artifactId and version
+Maven identifies JAR files by a set of strings: groupId, artifactId and version
(mostly). To let mvn-rpmbuild know what groupId:artifactId corresponds to which
-POM or jar file, we use the `%add_maven_depmap`
+POM or JAR file, we use the `%add_maven_depmap`
macro. `%add_maven_depmap` reads the groupId and artifactId from the
POM file and creates a file in `%{_mavendepmapfragdir}` that maps
-groupId:artifactId pairs to jar files under `%{_javadir}`. All
+groupId:artifactId pairs to JAR files under `%{_javadir}`. All
fragments in this directory are read by mvn-rpmbuild during startup, allowing
-the locally installed jar and POM files to be used as a maven repository.
+the locally installed JAR and POM files to be used as a maven repository.
Note that -- unless you use the `-f` option as shown below -- all
depmap fragments for a given package are written to the same file,
`%{_mavendepmapfragdir}/%{name}`. You should be sure to include this
file in the `%files` section of your RPM.
-For the macro to work properly, all jar files must be copied into `%{_javadir}`
+For the macro to work properly, all JAR files must be copied into `%{_javadir}`
and all POM files must be copied into `%{_mavenpomdir}` and given file names of
-the following form, where `jarname` is the name of the jar without the .jar
+the following form, where `jarname` is the name of the JAR without the .jar
suffix:
[source,spec]
@@ -131,20 +131,20 @@ suffix:
%{_mavenpomdir}/JPP[.subdirectory]-jarname.pom
--------
-Note that the subdirectory is only necessary if the jar file is put into a subdirectory of `%{_javadir}`. For example:
+Note that the subdirectory is only necessary if the JAR file is put into a subdirectory of `%{_javadir}`. For example:
-* For junit, the jar is `%{_javadir}/junit.jar`, so the POM would be
+* For junit, the JAR is `%{_javadir}/junit.jar`, so the POM would be
`%{_mavenpomdir}/JPP-junit.pom`.
-* For plexus-ant-factory, the jar is `%{_javadir}/plexus/ant-factory.jar`, so
+* For plexus-ant-factory, the JAR is `%{_javadir}/plexus/ant-factory.jar`, so
the POM would named `%{_mavenpomdir}/JPP.plexus-ant-factory.pom`.
-If a POM is installed with no corresponding jar file -- for example, for parent
+If a POM is installed with no corresponding JAR file -- for example, for parent
POM files -- the same convention should be followed:
* The Apache commons parent POM is installed in
`%{_mavenpomdir}/JPP-commons-parent.pom`.
-In its simplest form (a POM without a jar file), `%add_maven_depmap` looks like this:
+In its simplest form (a POM without a JAR file), `%add_maven_depmap` looks like this:
.Parent POM
[source,spec]
@@ -156,7 +156,7 @@ This will read the POM file in question and provide a mapping between the
groupId and artifactId inside the POM file and the POM file placed into
`%{_mavenpomdir}`.
-For a POM that maps directly to a jar file, the following is the correct form:
+For a POM that maps directly to a JAR file, the following is the correct form:
.Standard invocation
[source,spec]
@@ -165,17 +165,17 @@ For a POM that maps directly to a jar file, the following is the correct form:
--------
In addition to creating the POM mapping, this will also ensure that the correct
-jar is associated with the groupId and artifactId from the POM.
+JAR is associated with the groupId and artifactId from the POM.
.Providing additional artifact mappings
[source,spec]
--------
%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang"
--------
-This form also adds additional mappings for given POM/jar file. For example, if
+This form also adds additional mappings for given POM/JAR file. For example, if
the POM file indicates that it contains groupId commons-lang, artifactId
commons-lang, this form ensures that we also add a mapping between groupId
-org.apache.commons and the installed jar/pom files. This is necessary in cases
+org.apache.commons and the installed POM/JAR files. This is necessary in cases
where the groupId or artifactId may have changed, and other packages might
require different IDs than those reflected in the installed POM.
@@ -186,7 +186,7 @@ require different IDs than those reflected in the installed POM.
--------
This form stores dependency mapping inside `%{_mavendepmapfragdir}/%{name}-XXX`
instead of standard location. This is useful for packages with multiple
-subpackages where each has its own jar files.
+subpackages where each has its own JAR files.
.Multiple artifacts in a subdirectory
[source,spec]
@@ -194,7 +194,7 @@ subpackages where each has its own jar files.
%add_maven_depmap JPP.%{name}-sub.pom %{name}/sub.jar
--------
-This form should be used when a package consists of multiple jar files that are
+This form should be used when a package consists of multiple JAR files that are
installed into a subdirectory of `%{_javadir}`. Note that in this case, the POM
file name includes the optional subdirectory field.
@@ -224,6 +224,6 @@ package) installed.
The previous example installs the "msv" script (5th argument) with main class
being msv.textui.Driver (1st argument). No optional flags (2nd argument) or
options (3rd argument) are used. This script will add several libraries to
-classpath before executing main class (4th argument, jars separated with
+classpath before executing main class (4th argument, JAR files separated with
":"). `build-classpath` is run on every part of 4th argument to create full
classpaths.
diff --git a/doc/index.txt b/doc/index.txt
index 3212e0a..4d0ac2e 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -94,7 +94,7 @@ of AsciiDoc labeled lists.
[glossary]
[[Xdepmap]]depmap::
Depmap is a special file telling Maven relationships between
- groupId,artifactId and jar file on the filesystem
+ groupId,artifactId and JAR file on the filesystem
A second glossary term::
The corresponding (indented) definition.
11 years, 3 months
[javapackages] [doc] Move helper macros to a separate file
by Stanislav Ochotnicky
commit 5066aba6b86beff588455140b5afb50539555cb2
Author: Stanislav Ochotnicky <sochotnicky(a)redhat.com>
Date: Thu Mar 7 18:00:54 2013 +0100
[doc] Move helper macros to a separate file
doc/helper_macros.txt | 229 +++++++++++++++++++++++++++++++++++++++++++++++
doc/index.txt | 234 +------------------------------------------------
2 files changed, 233 insertions(+), 230 deletions(-)
---
diff --git a/doc/helper_macros.txt b/doc/helper_macros.txt
new file mode 100644
index 0000000..0b8ab38
--- /dev/null
+++ b/doc/helper_macros.txt
@@ -0,0 +1,229 @@
+Many repeating tasks when packaging Java software can be automated. Most of the
+time they are RPM macros or shell scripts.
+
+==== Macros for pom.xml modification
+
+Sometimes Maven `pom.xml` files need to be patched before they are used to build
+packages. One could use traditional patches to maintain changes, but package
+maintainers should use `%pom_*` macros developed specially to ease this
+task.
+
+These macros are designed to be called from `%prep` section of spec files. There
+are documented in `/etc/rpm/macros.fjava` configuration file, which is also
+link:http://git.fedorahosted.org/git/?p=javapackages.git;a=blob_plain;f=macros.fjava[available online]. See the documentation for technical details how to use these
+macros. Below are some examples added for convenience.
+
+Often dependencies specified in Maven `pom.xml` files need to be removed because of different reasons. `%pom_remove_dep` macro can be used to ease this task:
+
+.Removing dependencies from pom.xml files
+[source,spec]
+--------
+# Removes dependency on groupId:artifactId from ./pom.xml
+%pom_remove_dep groupId:artifactId
+
+# Removes dependency on groupId:artifactId from ./submodule/pom.xml
+%pom_remove_dep groupId:artifactId submodule
+
+# Removes dependency on groupId:artifactId from ./full/path/to/file.pom
+%pom_remove_dep groupId:artifactId full/path/to/file.pom
+
+# Removes dependency on all artifacts in group groupId from ./pom.xml
+%pom_remove_dep groupId:
+
+# Removes all dependencies from ./pom.xml
+%pom_remove_dep :
+--------
+
+`%pom_remove_plugin` macro works exactly as `%pom_remove_dep`, except it removes Maven plugin invocations. Some examples:
+
+.Removing Maven plugins from pom.xml files
+[source,spec]
+--------
+# 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
+--------
+
+Sometimes some submodules of upstream project cannot be built for various
+reasons and there is a need to disable them. This can be achieved by using
+`%pom_disable_module`, for example:
+
+.Disabling specific project modules
+[source,spec]
+--------
+# 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
+--------
+
+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 two
+generic macros for modifying `pom.xml` files. `%pom_xpath_remove` can be used to
+remove arbitrary XML nodes, described by link:http://www.w3.org/TR/xpath/[XPath]
+expressions. `%pom_xpath_inject` macro is capable of injecting arbitrary
+link:http://www.w3.org/TR/xml/[XML] code to any `pom.xml` file. Below you can find
+some examples for these macros.
+
+.Less common pom.xml modifications
+[source,spec]
+--------
+# Removes parent definition
+%pom_xpath_remove "pom:parent"
+
+# Removes extensions from the build
+%pom_xpath_remove "pom:build/pom:extensions" module/pom.xml
+
+# Adds new dependency
+%pom_xpath_inject "pom:dependencies" "
+ <dependency>
+ <groupId>org.example.project</groupId>
+ <artifactId>awesomeproject</artifactId>
+ <version>1.0.0.GA</version>
+ </dependency>"
+
+# Use a bit more complex XPath to add additional exclusion into
+# maven-wagon dependency
+%pom_xpath_inject "pom:dependency[pom:artifactId[text()='maven-wagon']]/pom:exclusions" "
+ <exclusion>
+ <groupId>antlr</groupId>
+ <artifactId>antlr</artifactId>
+ </exclusion>"
+--------
+
+.Handling XML namespaces
+[NOTE]
+=======
+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 don't belong to any XML namespace.
+=======
+Using `%pom_*` macros not only increases readability of the spec file, but also improves maintainability of the package as there are no patches that would need to be rebased with each upstream release.
+
+==== add_maven_depmap macro
+
+Maven identifies jar files by a set of strings: groupId, artifactId and version
+(mostly). To let mvn-rpmbuild know what groupId:artifactId corresponds to which
+POM or jar file, we use the `%add_maven_depmap`
+macro. `%add_maven_depmap` reads the groupId and artifactId from the
+POM file and creates a file in `%{_mavendepmapfragdir}` that maps
+groupId:artifactId pairs to jar files under `%{_javadir}`. All
+fragments in this directory are read by mvn-rpmbuild during startup, allowing
+the locally installed jar and POM files to be used as a maven repository.
+
+Note that -- unless you use the `-f` option as shown below -- all
+depmap fragments for a given package are written to the same file,
+`%{_mavendepmapfragdir}/%{name}`. You should be sure to include this
+file in the `%files` section of your RPM.
+
+For the macro to work properly, all jar files must be copied into `%{_javadir}`
+and all POM files must be copied into `%{_mavenpomdir}` and given file names of
+the following form, where `jarname` is the name of the jar without the .jar
+suffix:
+
+[source,spec]
+--------
+%{_mavenpomdir}/JPP[.subdirectory]-jarname.pom
+--------
+
+Note that the subdirectory is only necessary if the jar file is put into a subdirectory of `%{_javadir}`. For example:
+
+* For junit, the jar is `%{_javadir}/junit.jar`, so the POM would be
+ `%{_mavenpomdir}/JPP-junit.pom`.
+* For plexus-ant-factory, the jar is `%{_javadir}/plexus/ant-factory.jar`, so
+ the POM would named `%{_mavenpomdir}/JPP.plexus-ant-factory.pom`.
+
+If a POM is installed with no corresponding jar file -- for example, for parent
+POM files -- the same convention should be followed:
+
+* The Apache commons parent POM is installed in
+ `%{_mavenpomdir}/JPP-commons-parent.pom`.
+
+In its simplest form (a POM without a jar file), `%add_maven_depmap` looks like this:
+
+.Parent POM
+[source,spec]
+--------
+%add_maven_depmap JPP-%{name}.pom
+--------
+
+This will read the POM file in question and provide a mapping between the
+groupId and artifactId inside the POM file and the POM file placed into
+`%{_mavenpomdir}`.
+
+For a POM that maps directly to a jar file, the following is the correct form:
+
+.Standard invocation
+[source,spec]
+--------
+%add_maven_depmap JPP-%{name}.pom %{name}.jar
+--------
+
+In addition to creating the POM mapping, this will also ensure that the correct
+jar is associated with the groupId and artifactId from the POM.
+
+.Providing additional artifact mappings
+[source,spec]
+--------
+%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang"
+--------
+This form also adds additional mappings for given POM/jar file. For example, if
+the POM file indicates that it contains groupId commons-lang, artifactId
+commons-lang, this form ensures that we also add a mapping between groupId
+org.apache.commons and the installed jar/pom files. This is necessary in cases
+where the groupId or artifactId may have changed, and other packages might
+require different IDs than those reflected in the installed POM.
+
+.Multiple subpackages
+[source,spec]
+--------
+%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX"
+--------
+This form stores dependency mapping inside `%{_mavendepmapfragdir}/%{name}-XXX`
+instead of standard location. This is useful for packages with multiple
+subpackages where each has its own jar files.
+
+.Multiple artifacts in a subdirectory
+[source,spec]
+--------
+%add_maven_depmap JPP.%{name}-sub.pom %{name}/sub.jar
+--------
+
+This form should be used when a package consists of multiple jar files that are
+installed into a subdirectory of `%{_javadir}`. Note that in this case, the POM
+file name includes the optional subdirectory field.
+
+==== Generating Application Shell Scripts
+As mentioned in section about xref:XFor_Packagers[Java packaging basics], all
+Java applications need wrapper shell scripts to setup the environment before
+running JVM and associated Java code.
+
+
+The jpackage-utils package contains a convenience `%jpackage_script` macro that
+can be used to create scripts that work for the majority of packages. See its
+definition and documentation in `/etc/rpm/macros.jpackage`. One thing to pay
+attention to is the 6th argument to it - whether to prefer a JRE over a full SDK
+when looking up a JVM to invoke - most packages that don't require the full Java
+SDK will want to set that to `true` to avoid unexpected results when looking up
+a JVM when some of the installed JRE's don't have the corresponding SDK (*-devel
+package) installed.
+
+[source,spec]
+--------
+%install
+...
+%jpackage_script msv.textui.Driver "" "" msv-msv:msv-xsdlib:relaxngDatatype:isorelax msv true
+...
+--------
+
+The previous example installs the "msv" script (5th argument) with main class
+being msv.textui.Driver (1st argument). No optional flags (2nd argument) or
+options (3rd argument) are used. This script will add several libraries to
+classpath before executing main class (4th argument, jars separated with
+":"). `build-classpath` is run on every part of 4th argument to create full
+classpaths.
diff --git a/doc/index.txt b/doc/index.txt
index cb7985d..3212e0a 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -28,238 +28,12 @@ will cover basic packaging principles such as:
* Commenting workarounds
* Links to other appropriate documents
+=== Build system identification
+How to determine preferred upstream build system
+
[[helper_macros]]
=== Java helper functions
-
-Many repeating tasks when packaging Java software can be automated. Most of the
-time they are RPM macros or shell scripts.
-
-==== Macros for pom.xml modification
-
-Sometimes Maven `pom.xml` files need to be patched before they are used to build
-packages. One could use traditional patches to maintain changes, but package
-maintainers should use `%pom_*` macros developed specially to ease this
-task.
-
-These macros are designed to be called from `%prep` section of spec files. There
-are documented in `/etc/rpm/macros.fjava` configuration file, which is also
-link:http://git.fedorahosted.org/git/?p=javapackages.git;a=blob_plain;f=macros.fjava[available online]. See the documentation for technical details how to use these
-macros. Below are some examples added for convenience.
-
-Often dependencies specified in Maven `pom.xml` files need to be removed because of different reasons. `%pom_remove_dep` macro can be used to ease this task:
-
-.Removing dependencies from pom.xml files
-[source,spec]
---------
-# Removes dependency on groupId:artifactId from ./pom.xml
-%pom_remove_dep groupId:artifactId
-
-# Removes dependency on groupId:artifactId from ./submodule/pom.xml
-%pom_remove_dep groupId:artifactId submodule
-
-# Removes dependency on groupId:artifactId from ./full/path/to/file.pom
-%pom_remove_dep groupId:artifactId full/path/to/file.pom
-
-# Removes dependency on all artifacts in group groupId from ./pom.xml
-%pom_remove_dep groupId:
-
-# Removes all dependencies from ./pom.xml
-%pom_remove_dep :
---------
-
-`%pom_remove_plugin` macro works exactly as `%pom_remove_dep`, except it removes Maven plugin invocations. Some examples:
-
-.Removing Maven plugins from pom.xml files
-[source,spec]
---------
-# 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
---------
-
-Sometimes some submodules of upstream project cannot be built for various
-reasons and there is a need to disable them. This can be achieved by using
-`%pom_disable_module`, for example:
-
-.Disabling specific project modules
-[source,spec]
---------
-# 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
---------
-
-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 two
-generic macros for modifying `pom.xml` files. `%pom_xpath_remove` can be used to
-remove arbitrary XML nodes, described by link:http://www.w3.org/TR/xpath/[XPath]
-expressions. `%pom_xpath_inject` macro is capable of injecting arbitrary
-link:http://www.w3.org/TR/xml/[XML] code to any `pom.xml` file. Below you can find
-some examples for these macros.
-
-.Less common pom.xml modifications
-[source,spec]
---------
-# Removes parent definition
-%pom_xpath_remove "pom:parent"
-
-# Removes extensions from the build
-%pom_xpath_remove "pom:build/pom:extensions" module/pom.xml
-
-# Adds new dependency
-%pom_xpath_inject "pom:dependencies" "
- <dependency>
- <groupId>org.example.project</groupId>
- <artifactId>awesomeproject</artifactId>
- <version>1.0.0.GA</version>
- </dependency>"
-
-# Use a bit more complex XPath to add additional exclusion into
-# maven-wagon dependency
-%pom_xpath_inject "pom:dependency[pom:artifactId[text()='maven-wagon']]/pom:exclusions" "
- <exclusion>
- <groupId>antlr</groupId>
- <artifactId>antlr</artifactId>
- </exclusion>"
---------
-
-.Handling XML namespaces
-[NOTE]
-=======
-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 don't belong to any XML namespace.
-=======
-Using `%pom_*` macros not only increases readability of the spec file, but also improves maintainability of the package as there are no patches that would need to be rebased with each upstream release.
-
-==== add_maven_depmap macro
-
-Maven identifies jar files by a set of strings: groupId, artifactId and version
-(mostly). To let mvn-rpmbuild know what groupId:artifactId corresponds to which
-POM or jar file, we use the `%add_maven_depmap`
-macro. `%add_maven_depmap` reads the groupId and artifactId from the
-POM file and creates a file in `%{_mavendepmapfragdir}` that maps
-groupId:artifactId pairs to jar files under `%{_javadir}`. All
-fragments in this directory are read by mvn-rpmbuild during startup, allowing
-the locally installed jar and POM files to be used as a maven repository.
-
-Note that -- unless you use the `-f` option as shown below -- all
-depmap fragments for a given package are written to the same file,
-`%{_mavendepmapfragdir}/%{name}`. You should be sure to include this
-file in the `%files` section of your RPM.
-
-For the macro to work properly, all jar files must be copied into `%{_javadir}`
-and all POM files must be copied into `%{_mavenpomdir}` and given file names of
-the following form, where `jarname` is the name of the jar without the .jar
-suffix:
-
-[source,spec]
---------
-%{_mavenpomdir}/JPP[.subdirectory]-jarname.pom
---------
-
-Note that the subdirectory is only necessary if the jar file is put into a subdirectory of `%{_javadir}`. For example:
-
-* For junit, the jar is `%{_javadir}/junit.jar`, so the POM would be
- `%{_mavenpomdir}/JPP-junit.pom`.
-* For plexus-ant-factory, the jar is `%{_javadir}/plexus/ant-factory.jar`, so
- the POM would named `%{_mavenpomdir}/JPP.plexus-ant-factory.pom`.
-
-If a POM is installed with no corresponding jar file -- for example, for parent
-POM files -- the same convention should be followed:
-
-* The Apache commons parent POM is installed in
- `%{_mavenpomdir}/JPP-commons-parent.pom`.
-
-In its simplest form (a POM without a jar file), `%add_maven_depmap` looks like this:
-
-.Parent POM
-[source,spec]
---------
-%add_maven_depmap JPP-%{name}.pom
---------
-
-This will read the POM file in question and provide a mapping between the
-groupId and artifactId inside the POM file and the POM file placed into
-`%{_mavenpomdir}`.
-
-For a POM that maps directly to a jar file, the following is the correct form:
-
-.Standard invocation
-[source,spec]
---------
-%add_maven_depmap JPP-%{name}.pom %{name}.jar
---------
-
-In addition to creating the POM mapping, this will also ensure that the correct
-jar is associated with the groupId and artifactId from the POM.
-
-.Providing additional artifact mappings
-[source,spec]
---------
-%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang"
---------
-This form also adds additional mappings for given POM/jar file. For example, if
-the POM file indicates that it contains groupId commons-lang, artifactId
-commons-lang, this form ensures that we also add a mapping between groupId
-org.apache.commons and the installed jar/pom files. This is necessary in cases
-where the groupId or artifactId may have changed, and other packages might
-require different IDs than those reflected in the installed POM.
-
-.Multiple subpackages
-[source,spec]
---------
-%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX"
---------
-This form stores dependency mapping inside `%{_mavendepmapfragdir}/%{name}-XXX`
-instead of standard location. This is useful for packages with multiple
-subpackages where each has its own jar files.
-
-.Multiple artifacts in a subdirectory
-[source,spec]
---------
-%add_maven_depmap JPP.%{name}-sub.pom %{name}/sub.jar
---------
-
-This form should be used when a package consists of multiple jar files that are
-installed into a subdirectory of `%{_javadir}`. Note that in this case, the POM
-file name includes the optional subdirectory field.
-
-==== Generating Application Shell Scripts
-As mentioned in section about xref:XFor_Packagers[Java packaging basics], all
-Java applications need wrapper shell scripts to setup the environment before
-running JVM and associated Java code.
-
-
-The jpackage-utils package contains a convenience `%jpackage_script` macro that
-can be used to create scripts that work for the majority of packages. See its
-definition and documentation in `/etc/rpm/macros.jpackage`. One thing to pay
-attention to is the 6th argument to it - whether to prefer a JRE over a full SDK
-when looking up a JVM to invoke - most packages that don't require the full Java
-SDK will want to set that to `true` to avoid unexpected results when looking up
-a JVM when some of the installed JRE's don't have the corresponding SDK (*-devel
-package) installed.
-
-[source,spec]
---------
-%install
-...
-%jpackage_script msv.textui.Driver "" "" msv-msv:msv-xsdlib:relaxngDatatype:isorelax msv true
-...
---------
-
-The previous example installs the "msv" script (5th argument) with main class
-being msv.textui.Driver (1st argument). No optional flags (2nd argument) or
-options (3rd argument) are used. This script will add several libraries to
-classpath before executing main class (4th argument, jars separated with
-":"). `build-classpath` is run on every part of 4th argument to create full
-classpaths.
+include::helper_macros.txt[]
== Build systems
11 years, 3 months