Packaging:Java

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
m (Jar file naming)
(maven3)
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<!-- page was renamed from PackagingDrafts/Java
 
-->
 
= Java Packaging Guidelines =
 
 
These guidelines are laid out in order of relevance to packaging.
 
These guidelines are laid out in order of relevance to packaging.
 
 
  
 
== Introduction ==
 
== Introduction ==
 
=== Background ===
 
Traditionally, Java implementations have been available under a non-free license.  Free software clean room implementations of the class library largely centred around GNU Classpath.  GCJ, a Java frontend for GCC, allowed for native compilation of Java software.  In 2007, Sun released its reference implementation of Java under the GPL+Classpath exception as OpenJDK.  This included the bytecode interpreter, just-in-time (JIT) compiler (Hotspot), and the majority of its class library.  Due to the remaining small proprietary encumbrances, a project known as IcedTea was formed to build OpenJDK with entirely free tools, and provides Free software plugs for the encumbered pieces of the class libraries.  Recent (early 2008) developments have enabled Fedora to ship a package under the OpenJDK name.
 
  
 
=== The Basics ===
 
=== The Basics ===
The term Java means many things to many people:  a class library, a bytecode interpreter, a JIT compiler, a language specification, etc.  For the vast majority of users and developers, Java is a programming language and runtime environment that is architecture- and OS-agnostic.  The normal flow of code is <code>.java</code> (source file) ’ <code>.class</code> (Java bytecode) ’ <code>.jar</code> (a zip archive).  In the majority of cases, a user executes a Java program by specifying a class name containing a main method (just like C and C++).  Often, this is done by invoking the <code>java</code> binary with a list of JAR files specifying the classpath like so:
+
The term Java means many things to many people:  a class library, a bytecode interpreter, a JIT compiler, a language specification, etc.  For the vast majority of users and developers, Java is a programming language and runtime environment that is architecture- and OS-agnostic.  The normal flow of code is <code>.java</code> (source file) <code>.class</code> (Java bytecode) <code>.jar</code> (a zip archive).  In the majority of cases, a user executes a Java program by specifying a class name containing a main method (just like C and C++).  Often, this is done by invoking the <code>java</code> binary with a list of JAR files specifying the classpath like so:
  
 
<code>java [-cp <jar1:jar2:jar3>]  <main-class> [<args>] </code>
 
<code>java [-cp <jar1:jar2:jar3>]  <main-class> [<args>] </code>
Line 18: Line 10:
 
== Java Packaging ==
 
== Java Packaging ==
 
The [http://www.jpackage.org JPackage Project]  has defined standard file system locations and conventions for use in Java packages.  Many distributions have inherited these conventions and in the vast majority of cases, Fedora follows them verbatim.  We include relevant sections of the JPackage guidelines here but caution that the canonical document will always reside upstream:  [http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?revision=HEAD&root=jpackage JPackage Guidelines]  .  Over time, we would like to remove any divergences in these documents, but where they are different, these Fedora guidelines will take precedence for Fedora packages.
 
The [http://www.jpackage.org JPackage Project]  has defined standard file system locations and conventions for use in Java packages.  Many distributions have inherited these conventions and in the vast majority of cases, Fedora follows them verbatim.  We include relevant sections of the JPackage guidelines here but caution that the canonical document will always reside upstream:  [http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?revision=HEAD&root=jpackage JPackage Guidelines]  .  Over time, we would like to remove any divergences in these documents, but where they are different, these Fedora guidelines will take precedence for Fedora packages.
 +
 +
TODO: Find the proper jpackage link and fix it.
  
 
=== Package naming ===
 
=== Package naming ===
  
Packages '''MUST''' follow the standard Fedora ["Packaging/NamingGuidelines"] . Java API documentation '''MUST''' be placed into a sub-package called <code>%{name}-javadoc</code>.
+
Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines]].
 +
 
 +
Java API documentation '''MUST''' be placed into a sub-package called <code>%{name}-javadoc</code>.
  
 
==== Release tags ====
 
==== Release tags ====
For now, refer to the ["Packaging/JPackagePolicy"] for release tags.  That document should eventually be folded into this one.
+
Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines#Package_Version | Package versioning guidelines]] .
 
+
=== Jar file naming ===
+
  
# If a package provides a single JAR file it must have the same name as the package itself.
+
=== JAR file installation ===
  
ex. <code>jaf.jar</code>
+
The following applies to all JAR files except [[#JNI|JNI-using JAR files]], [[#GCJ|GCJ files]] and application-specific JAR files (ie. JAR files that can only reasonably be used as part of an application and therefore constitute application-private data).
  
# If the project name and the commonly used JAR filename differ, a symbolic link with the usual name must also be provided.
+
==== Split JAR files ====
  
ex. Single JAR complete naming.  Project name is <code>jaf</code>, common name is <code>activation</code>.
+
If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging '''should''' be preferred.
  
<code>activation.jar ’ jaf.jar</code>
+
==== Filenames ====
  
# If the package provides several JAR files, the filenames assigned by the build must be used. Above symlinking rules apply.
+
* If the package provides a '''single''' JAR and the filename provided by the build is <code>%{name}.jar</code> or <code>%{name}-%{version}.jar</code> then filename <code>%{name}.jar</code> '''MUST''' be used.
 +
* If the package provides a '''single''' JAR and the filename provided by the build is neither <code>%{name}-%{version}.jar</code> nor <code>%{name}.jar</code> then this file '''MUST''' be installed as <code>%{name}.jar</code> and a symbolic link with the usual name must be provided.
 +
* If the package provides more than '''one''' JAR file, the filenames assigned by the build '''MUST''' be used (without versions).
 +
* If the project usually provides alternative JAR file names by installing symbolic links then such symlinks '''MAY''' be installed in the same directory as the JAR files.
  
ex.  <pre>ant-1.5.3.jar
+
==== Installation directory ====
ant-optional-1.5.3.jar</pre>
+
  
# If the number of provided JAR files exceeds '''two''', you must place them into a sub-directory.
+
* All JAR files '''MUST''' go into <code>%{_javadir}</code> or a Java-version specific directory <code>%{_javadir}-<i>*</i></code> as appropriate[http://lists.fedoraproject.org/pipermail/packaging/2010-January/006792.html].
  
# If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging should be preferred.
+
* If the number of provided JAR files exceeds '''two''', you '''MUST''' place them into a sub-directory named <code>%{name}</code>.
  
=== Directory structure ===
+
=== Javadoc installation ===
All JAR files '''MUST''' go into <code>%{_javadir}</code>.  Exceptions include [[JNI|  JNI-using JAR files]] , and application-specific JAR files (ie. JAR files that can only reasonably be used as part of an application and therefore constitute application-private data).
+
  
Java API documentation uses a system known as javadoc.  All javadocs '''MUST''' be installed into <code>%{_javadocdir</code>}.
+
* Java API documentation uses a system known as javadoc.  All javadocs '''MUST''' be created and installed into a directory of <code>%{_javadocdir}/%{name}</code>.
 +
* Directory or symlink <code>%{_javadocdir}/%{name}-%{version}</code> '''SHOULD NOT''' exist.
 +
* The javadoc subpackage '''MUST''' be declared <code>noarch</code> even if main package is architecture specific.
  
 
=== BuildRequires and Requires ===
 
=== BuildRequires and Requires ===
Line 69: Line 66:
 
<code>build-classpath</code> is a script that can be used to generate classpaths from generic names of JAR files.  Example:
 
<code>build-classpath</code> is a script that can be used to generate classpaths from generic names of JAR files.  Example:
  
<pre>export CLASSPATH=$(build-classpath commons-logging commons-net)
+
<pre>export CLASSPATH=$(build-classpath commons-logging commons-net xbean/xbean-reflect)
 
</pre>
 
</pre>
 +
{{admon/note|Additional information|You can use either package names (all jar files will be included) or jar filenames with path prefix to select only some jar files from whole package.}}
  
 
=== build-jar-repository ===
 
=== build-jar-repository ===
Line 91: Line 89:
 
</pre>
 
</pre>
  
=== maven ===
+
=== maven2 ===
<code>maven</code> is a tool used by many Java packages.  In Fedora, the package is called <code>maven2</code>.  Packages built using <code>maven</code> ship with <code>pom.xml</code> files.  They '''MUST''':
+
In Fedora 14 and older (including EPEL), the package is called <code>maven2</code>.  Packages built using <code>maven</code> ship with <code>pom.xml</code> files.  They '''MUST''':
  
 
<pre>Requires(post): jpackage-utils
 
<pre>Requires(post): jpackage-utils
Line 109: Line 107:
 
install javadoc:javadoc
 
install javadoc:javadoc
 
...
 
...
 +
 
%install
 
%install
rm -rf $RPM_BUILD_ROOT
 
 
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
 
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -d -m 755 $RPM_BUILD_ROOT%{_datadir}/maven2/poms
+
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_datadir}/maven2/poms/JPP-maven-archiver.pom
+
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
%add_to_maven_depmap org.apache.maven maven-archiver %{version} JPP maven-archiver
+
# artifactId and jarName are usually %{name} for single module projects
 +
%add_to_maven_depmap [groupId] [artifactId] %{version} JPP[/optional_subDir] [jarName]
 +
 
 
...
 
...
 
%post
 
%post
Line 124: Line 124:
 
</pre>
 
</pre>
  
=== Wrapper Scripts ===
+
{{admon/note|Note:|Multimodule Maven projects should use javadoc:aggregate instead of javadoc:javadoc.}}
Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in <code>%{_bindir</code>}.  These can be as simple as this example:
+
  
<pre>#!/bin/bash
+
{{admon/important|Important|Please read [[Java/JPPMavenReadme]] for details about mvn-jpp and %add_to_maven_depmap usage. }}
. /usr/share/java-utils/java-functions
+
  
MAIN_CLASS=MyCoolApp
+
=== maven3 ===
 +
In Fedora 15 and newer, maven 3 is used and the package is called <code>maven</code>.  Packages built using <code>maven</code> ship with <code>pom.xml</code> files.  They '''SHOULD''' contain common sections such as the following:
  
set_classpath "mycoolapp"
+
<pre>
 +
...
 +
%build
 +
mvn-rpmbuild install javadoc:aggregate
 +
...
  
run "$@"
+
%install
 +
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
 +
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
 +
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
 +
install -pm 644 target/%{name}-%{version}.jar $RPM_BUILD_ROOT/%{_javadir}/%{name}.jar
 +
 
 +
# second argument is optional (parent poms have no jars)
 +
%add_maven_depmap JPP-%{name}.pom %{name}.jar
 +
...
 +
%files
 +
%{_mavendepmapfragdir}/%{name}
 +
%{_mavenpomdir}/JPP-%{name}.pom
 
</pre>
 
</pre>
 +
 +
Useful mvn-rpmbuild customisations:
 +
* -Dmaven.local.depmap.file=FILE.xml - xml file that defines alternative dependency maps
 +
* -Dmaven.local.debug=true makes custom resolver output more debugging information
 +
 +
{{admon/important|Important|Fedora 15+ have both Maven 3.X and Maven 2.2.1 (packages maven and maven2 respectively). Only maven package contains mvn-rpmbuild. Maven 2 is considered deprecated and is included to ensure backward compatibility. Use of maven2 is strongly discouraged in Fedora 15 and newer.}}
 +
 +
{{admon/important|Important|For detailed instructions on use of add_maven_depmap macro see [[#depmap_macro|macro documentation]]}}
 +
 +
=== add_maven_depmap macro ===
 +
{{Anchor|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 %add_maven_depmap macro. In its simplest form add_maven_depmap looks like this:
 +
<pre>%add_maven_depmap JPP-%{name}.pom</pre>
 +
This will read pom file in question and provide mapping between groupId,artifactId inside pom file and pom file placed into %{_mavenpomdir}. Given pom file already has to exist inside %{_mavenpomdir}. Mapping is stored inside %{_mavendepmapfragdir}/%{name} file. All mappings (fragments) are read by mvn-rpmbuild during startup. This form should only be used for pom-only artifacts (i.e. parent poms).
 +
 +
<pre>%add_maven_depmap JPP-%{name}.pom %{name}.jar</pre>
 +
In addition to creating mapping, this will also ensure that jar and pom files are named correctly and placed in correct subdirectories.
 +
 +
<pre>%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang"</pre>
 +
This form also adds additional mappings for given pom/jar file. I.e. if pom file stated it contains groupId commons-lang, artifactId commons-lang, by using this form we also added mapping between groupId org.apache.commons and jar/pom files.
 +
 +
<pre>%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX"</pre>
 +
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.
 +
 +
=== Wrapper Scripts ===
 +
Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in <code>%{_bindir}</code>. 
 +
 +
The jpackage-utils package contains a convenience <code>%jpackage_script</code> macro that can be used to create scripts that work for the majority of packages.  See its definition and documentation in <code>/etc/rpm/macros.jpackage</code>.  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 <code>true</code> 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.
 +
 +
<pre>
 +
%install
 +
...
 +
%jpackage_script com.sun.msv.driver.textui.Driver "" "" msv-msv:msv-xsdlib:relaxngDatatype:isorelax msv true
 +
...
 +
</pre>
 +
The previous example installs the "msv" script (5th argument) with main class being com.sun.msv.driver.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 ":"). <code>build-classpath</code> is run on every part of 4th argument to create full classpaths.
  
 
=== GCJ ===
 
=== GCJ ===
 +
Building GCJ AOT bits is discouraged unless you have a very strong reason to include them in the packages.
 +
Even when AOT bits are built and included in packages it is recommended to not require java-1.5.0-gcj because this will force every single user to install it even if one wants to use another JVM.
 +
 
Please refer to [[Packaging/GCJGuidelines]]  for GCJ-specific guidelines.
 
Please refer to [[Packaging/GCJGuidelines]]  for GCJ-specific guidelines.
  
 
=== -devel packages ===
 
=== -devel packages ===
 
<code>-devel</code> packages don't really make sense for Java packages.  Header files do not exist for Java packages.
 
<code>-devel</code> packages don't really make sense for Java packages.  Header files do not exist for Java packages.
 +
 +
 +
=== Maven pom.xml files and depmaps ===
 +
If upstream project is shipping Maven pom.xml files, these '''MUST''' be installed with the corresponding %add_maven_depmap calls.
 +
 +
If upstream project does not ship pom.xml file [[http://repo1.maven.org/maven2/ official maven repo]] should be checked and if there are pom.xml files they '''SHOULD''' be installed.
 +
 +
{{admon/tip|Tip|[http://mvnrepository.com/ Mvnrepository site] can be used to ease}}
  
 
== Specfile Template ==
 
== Specfile Template ==
 
=== ant ===
 
=== ant ===
 +
 
<pre>
 
<pre>
 
Name:          # see normal package guidelines
 
Name:          # see normal package guidelines
 
Version:        # see normal package guidelines
 
Version:        # see normal package guidelines
 
Release:        1%{?dist}
 
Release:        1%{?dist}
Summary:        # see normal package guidelines (SNPG)
+
Summary:        # see normal package guidelines
  
Group:          # SNPG
+
Group:          # see normal package guidelines
License:        # SNPG
+
License:        # see normal package guidelines
URL:            # SNPG
+
URL:            # see normal package guidelines
Source0:        # SNPG
+
Source0:        # see normal package guidelines
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
+
BuildArch:      noarch
  
 
BuildRequires:  jpackage-utils
 
BuildRequires:  jpackage-utils
Line 171: Line 234:
 
%package javadoc
 
%package javadoc
 
Summary:        Javadocs for %{name}
 
Summary:        Javadocs for %{name}
Group:          Development Documentation
+
Group:          Documentation
Requires:      %{name} = %{version}-%{release}
+
 
Requires:      jpackage-utils
 
Requires:      jpackage-utils
  
 
%description javadoc
 
%description javadoc
 
This package contains the API documentation for %{name}.
 
This package contains the API documentation for %{name}.
 
%package manual
 
Summary:        Manual for %{name}
 
Group:          Development Documentation
 
Requires:      jpackage-utils
 
Requires:      %{name} = %{version}-%{release}
 
 
%description manual
 
The manual for %{name}.
 
  
 
%prep
 
%prep
 
%setup -q
 
%setup -q
  
 
+
find -name '*.class' -exec rm -f '{}' \;
find -name '*.jar' -o -name '*.class' -exec rm -f '{}' \;
+
find -name '*.jar' -exec rm -f '{}' \;
 
+
  
 
%build
 
%build
Line 198: Line 250:
  
 
%install
 
%install
rm -rf $RPM_BUILD_ROOT
 
  
 
mkdir -p $RPM_BUILD_ROOT%{_javadir}
 
mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar]   \
+
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar
$RPM_BUILD_ROOT%{_javadir}/%{name}-%{version}.jar
+
 
+
  
 
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
 
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] \
+
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}
$RPM_BUILD_ROOT%{_javadocdir}/%{name}
+
 
+
%clean
+
rm -rf $RPM_BUILD_ROOT
+
  
 
%files
 
%files
%defattr(-,root,root,-)
 
 
%{_javadir}/*
 
%{_javadir}/*
 
%doc
 
%doc
  
 
%files javadoc
 
%files javadoc
%defattr(-,root,root,-)
 
 
%{_javadocdir}/%{name}
 
%{_javadocdir}/%{name}
  
%files manual
 
%defattr(-,root,root,-)
 
%doc [manual directory] /*
 
  
 
%changelog
 
%changelog
 
</pre>
 
</pre>
  
=== maven ===
+
 
 +
 
 +
=== maven 2 ===
 +
{{admon/important|Important|Fedora 15+ have both Maven 3.X and Maven 2.2.1 packaged (packages maven and maven2 respectively). Maven 2 is considered deprecated and is included to ensure backward compatibility. Use of maven2 is strongly discouraged, however, older Fedora releases (and EPEL) still require its use.}}
 +
 
 
<pre>
 
<pre>
 
Name:          # see normal package guidelines
 
Name:          # see normal package guidelines
 
Version:        # see normal package guidelines
 
Version:        # see normal package guidelines
 
Release:        1%{?dist}
 
Release:        1%{?dist}
Summary:        # see normal package guidelines (SNPG)
+
Summary:        # see normal package guidelines
 +
 
 +
Group:          # see normal package guidelines
 +
License:        # see normal package guidelines
 +
URL:            # see normal package guidelines
 +
Source0:        # see normal package guidelines
  
Group:          # SNPG
+
BuildArch:      noarch
License:        # SNPG
+
URL:            # SNPG
+
Source0:        # SNPG
+
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
+
  
 
BuildRequires:  jpackage-utils
 
BuildRequires:  jpackage-utils
Line 247: Line 292:
 
BuildRequires:  maven2
 
BuildRequires:  maven2
  
BuildRequires:    maven2-plugin-compiler
+
BuildRequires:    maven-compiler-plugin
BuildRequires:    maven2-plugin-install
+
BuildRequires:    maven-install-plugin
BuildRequires:    maven2-plugin-jar
+
BuildRequires:    maven-jar-plugin
BuildRequires:    maven2-plugin-javadoc
+
BuildRequires:    maven-javadoc-plugin
BuildRequires:    maven2-plugin-release
+
BuildRequires:    maven-release-plugin
BuildRequires:    maven2-plugin-resources
+
BuildRequires:    maven-resources-plugin
BuildRequires:    maven2-plugin-surefire
+
BuildRequires:    maven-surefire-plugin
  
 
Requires:      jpackage-utils
 
Requires:      jpackage-utils
Line 263: Line 308:
  
 
%description
 
%description
 +
some smart and long description.
  
 
%package javadoc
 
%package javadoc
 
Summary:        Javadocs for %{name}
 
Summary:        Javadocs for %{name}
Group:          Development/Documentation
+
Group:          Documentation
Requires:      %{name}-%{version}-%{release}
+
 
Requires:      jpackage-utils
 
Requires:      jpackage-utils
  
 
%description javadoc
 
%description javadoc
 
This package contains the API documentation for %{name}.
 
This package contains the API documentation for %{name}.
 
%package manual
 
Summary:        Manual for %{name}
 
Group:          Development/Documentation
 
Requires:      jpackage-utils
 
Requires:      %{name}-%{version}-%{release}
 
 
%description manual
 
The manual for %{name}.
 
  
 
%prep
 
%prep
Line 290: Line 326:
 
mkdir -p $MAVEN_REPO_LOCAL
 
mkdir -p $MAVEN_REPO_LOCAL
  
mvn-jpp \
+
mvn-jpp -Dmaven.repo.local=$MAVEN_REPO_LOCAL \
-Dmaven.repo.local=$MAVEN_REPO_LOCAL \
+
        install javadoc:javadoc # or javadoc:aggregate
install javadoc:javadoc
+
  
 
%install
 
%install
rm -rf $RPM_BUILD_ROOT
 
  
 
mkdir -p $RPM_BUILD_ROOT%{_javadir}
 
mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar]   \
+
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar
$RPM_BUILD_ROOT%{_javadir}/%{name}-%{version}.jar
+
 
+
  
 
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
 
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] \
+
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}
$RPM_BUILD_ROOT%{_javadocdir}/%{name}
+
  
install -d -m 755 $RPM_BUILD_ROOT%{_datadir}/maven2/poms
+
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
 
install -pm 644 [path to pom]  \
 
install -pm 644 [path to pom]  \
$RPM_BUILD_ROOT%{_datadir}/maven2/poms/JPP-%{name}.pom
+
        $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom
  
%add_to_maven_depmap org.apache.maven %{name} %{version} JPP %{name}
+
%add_to_maven_depmap project_group_id project_artifact_id %{version} JPP %{name}
  
%clean
 
rm -rf $RPM_BUILD_ROOT
 
  
 
%post
 
%post
Line 320: Line 349:
 
%postun
 
%postun
 
%update_maven_depmap
 
%update_maven_depmap
 +
  
 
%files
 
%files
%defattr(-,root,root,-)
+
%{_mavenpomdir}/*
%{_datadir}/maven2/poms
+
%{_mavendepmapfragdir}/*
%{_mavendepmapfragdir}
+
 
%{_javadir}/*
 
%{_javadir}/*
 
%doc
 
%doc
  
 
%files javadoc
 
%files javadoc
%defattr(-,root,root,-)
 
 
%{_javadocdir}/%{name}
 
%{_javadocdir}/%{name}
 
%files manual
 
%defattr(-,root,root,-)
 
%doc [manual directory] /*
 
  
 
%changelog
 
%changelog
Line 340: Line 364:
 
</pre>
 
</pre>
  
 +
{{admon/important|Depmap information|Last two arguments to %add_to_maven_depmap macro represent location of installed jar file. Using ".. jpp/foo bar" as last two arguments will mean that groupId/artifactId of package will resolve to jar file %{_javadir}/foo/bar.jar.}}
 
For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located [http://fedoraproject.org/wiki/Java/JPPMavenReadme here] .
 
For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located [http://fedoraproject.org/wiki/Java/JPPMavenReadme here] .
  
{{Anchor|JNI}}
+
=== maven 3 ===
== Packaging JAR files that use JNI ==
+
{{admon/important|Important|Only Fedora 15 and newer releases have Maven 3. For older releases and EPEL, refer to the maven 2 template.}}  
  
 +
<pre>
 +
Name:          # see normal package guidelines
 +
Version:        # see normal package guidelines
 +
Release:        1%{?dist}
 +
Summary:        # see normal package guidelines
 +
 +
Group:          # see normal package guidelines
 +
License:        # see normal package guidelines
 +
URL:            # see normal package guidelines
 +
Source0:        # see normal package guidelines
 +
 +
BuildArch:      noarch
 +
 +
BuildRequires:  jpackage-utils
 +
 +
BuildRequires:  java-devel
 +
 +
BuildRequires:  maven
 +
 +
BuildRequires:    maven-compiler-plugin
 +
BuildRequires:    maven-install-plugin
 +
BuildRequires:    maven-jar-plugin
 +
BuildRequires:    maven-javadoc-plugin
 +
BuildRequires:    maven-release-plugin
 +
BuildRequires:    maven-resources-plugin
 +
BuildRequires:    maven-surefire-plugin
 +
 +
Requires:      jpackage-utils
 +
Requires:      java
 +
 +
%description
 +
some smart and long description.
 +
 +
%package javadoc
 +
Summary:        Javadocs for %{name}
 +
Group:          Documentation
 +
Requires:      jpackage-utils
 +
 +
%description javadoc
 +
This package contains the API documentation for %{name}.
 +
 +
%prep
 +
%setup -q
 +
 +
%build
 +
mvn-rpmbuild install javadoc:aggregate
 +
 +
%install
 +
 +
mkdir -p $RPM_BUILD_ROOT%{_javadir}
 +
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar
 +
 +
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
 +
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}
 +
 +
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
 +
install -pm 644 [path to pom]  \
 +
        $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom
 +
 +
%add_maven_depmap JPP-%{name}.pom %{name}.jar
 +
 +
 +
%files
 +
%{_mavenpomdir}/JPP-%{name}.pom
 +
%{_mavendepmapfragdir}/%{name}
 +
%{_javadir}/%{name}.jar
 +
%doc
 +
 +
%files javadoc
 +
%{_javadocdir}/%{name}
 +
 +
%changelog
 +
 +
</pre>
 +
 +
{{admon/important|Important|For detailed instructions on use of add_maven_depmap macro see [[#depmap_macro|macro documentation]]}}
 +
 +
== Packaging JAR files that use JNI ==
 +
{{Anchor|JNI}}
 
=== Applicability ===
 
=== Applicability ===
  
 
Java programs that wish to make calls into native libraries do so via the Java Native Interface (JNI).  A Java package uses JNI if it contains a .so
 
Java programs that wish to make calls into native libraries do so via the Java Native Interface (JNI).  A Java package uses JNI if it contains a .so
  
{{Template:Warning}} Note that GCJ packages contain <code>.so</code>s in <code>%{_libdir}/gcj/%{name</code>} but they are not JNI .sos.
+
{{Template:Warning}} Note that GCJ packages contain <code>.so</code>s in <code>%{_libdir}/gcj/%{name}</code> but they are not JNI .sos.
  
 
=== Guideline ===
 
=== Guideline ===
  
JAR files that require JNI shared objects '''MUST''' be installed in <code>%{_libdir}/%{name</code>}.  The JNI shared objects themselves must also be installed in <code>%{_libdir}/%{name}</code>.  If the JNI-using code calls <code>System.loadLibrary</code> you'll have to patch it to use <code>System.load</code>, passing it the full path to the dynamic shared object.  If the package installs a wrapper script you'll need to manually add <code>%{_libdir}/%{name}/<jar filename></code> to <code>CLASSPATH</code>.  If you are depending on a JNI-using JAR file, you'll need to add it manually -- <code>build-classpath</code> will not find it.
+
JAR files that require JNI shared objects '''MUST''' be installed in <code>%{_libdir}/%{name}</code>.  The JNI shared objects themselves must also be installed in <code>%{_libdir}/%{name}</code>.  If the JNI-using code calls <code>System.loadLibrary</code> you'll have to patch it to use <code>System.load</code>, passing it the full path to the dynamic shared object.  If the package installs a wrapper script you'll need to manually add <code>%{_libdir}/%{name}/<jar filename></code> to <code>CLASSPATH</code>.  If you are depending on a JNI-using JAR file, you'll need to add it manually -- <code>build-classpath</code> will not find it.
  
 
=== Rationale ===
 
=== Rationale ===
  
This is less convenient, but cleaner from a packaging point-of-view, than putting the JAR file in <code>%{_javadir</code>}, and putting the JNI shared object in  <code>%{_libdir</code>} to be loaded from the default library path.  First, JNI shared objects are <code>dlopen</code>'d, and <code>dlopen</code>'d shared objects should not be placed directly in <code>%{_libdir</code>} since they are application-private data, and not libraries meant to be linked to directly -- that is, not meant to be shared. Second, placing the JAR file in <code>%{_javadir</code>} causes the build-classpath script to always load it, even when running on a runtime environment of the wrong arch, meaning that the <code>System.loadLibrary</code> line would fail.
+
This is less convenient, but cleaner from a packaging point-of-view, than putting the JAR file in <code>%{_javadir}</code>, and putting the JNI shared object in  <code>%{_libdir}</code> to be loaded from the default library path.  First, JNI shared objects are <code>dlopen</code>'d, and <code>dlopen</code>'d shared objects should not be placed directly in <code>%{_libdir}</code> since they are application-private data, and not libraries meant to be linked to directly -- that is, not meant to be shared. Second, placing the JAR file in <code>%{_javadir}</code> causes the build-classpath script to always load it, even when running on a runtime environment of the wrong arch, meaning that the <code>System.loadLibrary</code> line would fail.
  
 
The plan is to eventually eliminate patching of the <code>System.loadLibrary</code> line and wrapper script by making <code>jpackage-utils</code> multilib aware.  This involves the following changes:  creating <code>%{_libdir}/java</code> and <code>%{_libdir}/jni</code> directories; giving JNI-containing packages the ability to require an architecture-specific runtime environment; adding support for specifying the required runtime architecture in a wrapper script; modifying <code>jpackage-utils</code>'s runtime scripts to search <code>%{_libdir}/java</code>; modifying IcedTea to look for JNI shared objects in <code>%{_libdir}/jni</code>.
 
The plan is to eventually eliminate patching of the <code>System.loadLibrary</code> line and wrapper script by making <code>jpackage-utils</code> multilib aware.  This involves the following changes:  creating <code>%{_libdir}/java</code> and <code>%{_libdir}/jni</code> directories; giving JNI-containing packages the ability to require an architecture-specific runtime environment; adding support for specifying the required runtime architecture in a wrapper script; modifying <code>jpackage-utils</code>'s runtime scripts to search <code>%{_libdir}/java</code>; modifying IcedTea to look for JNI shared objects in <code>%{_libdir}/jni</code>.
  
The <code>%{_jnidir</code>} rpm macro defines the main JNI jar repository. Like <code>%{_javadir</code>} it is declined in <code>-ext</code> and <code>-x.y.z</code> variants. It follows exactly the same rules as the <code>%{_javadir</code>}-derived tree structure, except that it hosts JAR files that use JNI.
+
The <code>%{_jnidir}</code> rpm macro defines the main JNI jar repository. Like <code>%{_javadir}</code> it is declined in <code>-ext</code> and <code>-x.y.z</code> variants. It follows exactly the same rules as the <code>%{_javadir}</code>-derived tree structure, except that it hosts JAR files that use JNI.
  
<code>%{_jnidir</code>} usually expands into <code>/usr/lib/java</code>.
+
<code>%{_jnidir}</code> usually expands into <code>/usr/lib/java</code>.
  
 
== Things to avoid ==
 
== Things to avoid ==
Line 393: Line 497:
 
sed -i '/class-path/I d' META-INF/MANIFEST.MF
 
sed -i '/class-path/I d' META-INF/MANIFEST.MF
 
</pre>
 
</pre>
'''Will this preserve the line ending as the [http://java.sun.com/docs/books/tutorial/deployment/jar/downman.html this page]  says it must?'''
 
  
== Comments ==
+
[[Category:Packaging guidelines]]
 
+
[[Category:Java]]
- Which version of java should stuff be built for?  Probably 1.5 (for gcj) if possible?  Should mention something about this.  (VilleSkyttä)
+
 
+
- I think referencing the GCJ Guidelines, which say the package should build on GCJ, is sufficient, since building on GCJ implies building on 1.5.  In general packages should build against/require whatever Java version upstream uses. (ThomasFitzsimmons)
+
 
+
- Referring to GCJ guidelines would work for me, but the 1.5 issue needs to be explicitly mentioned there, it's not clear to everyone. (VilleSkyttä)
+
 
+
- "Requires: java" should have a version in it (depending on which version of java it was built for).  Possibly also depend on jre instead of java (maybe this is just cosmetic)?  (VilleSkyttä)
+
 
+
- Agreed.  I removed the conditional brackets around >= specific_version.  I think we should just stick with "java" and not bother with "jre", since that's how it's been done in the past. (ThomasFitzsimmons)
+
 
+
- Thanks.  Spec templates still have the unversioned form, though. (VilleSkyttä)
+
 
+
- Drop versioned jars and install only unversioned ones?  https://www.redhat.com/archives/fedora-devel-list/2008-March/msg02346.html  (VilleSkyttä)
+
 
+
- Fine by me. (ThomasFitzsimmons)
+
 
+
- For users attempting to introduce a new Java package, we should tell them to first check if the package exists on JPackage (JPackage.org). JPackage packages follow a large majority of the guidelines in this draft, and thus importing should be fairly easy. Additionally, having a package in sync with JPackage will prevent potential incompatibility issues with other JPackage packages. (DeepakBhole)
+
 
+
- Would we want that to be a '''should''' or a '''must'''?  In other words, if a packager wants to deviate from the JPackage package but still falls within the Guidelines do we want to allow them that freedom?
+
 
+
- My one major issue with this Guideline is the use of "canonical document" in the header for "Java Packaging".  We do have other Guidelines that point to external sources for additional sources but they are targeted pieces (For instance, make sure .desktop files provided by the package follow the freedesktop spec [LINK to spec] ).  The Java Guidelines are broader and also have an overlay of information (saying that the JPackage Guidelines are the "canonical document" seems to mean "follow the JPackage Guidelines except where the Fedora Guidelines differ").  This makes it harder for a reviewer to understand what's going on in a package that they attempt to review because they need to keep flipping between two Guidelines and trying to remember where one differs from another.  It would be better organization if the Java Guidelines took one of the following approaches:  1) Major concerns listed in the Fedora Guidelines.  Specifics point to the relevant section of the JPackage Guidelines.  For instance:
+
<pre>
+
=== Jar File Naming ===
+
Jar files must be named after the package name using the [http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?revision=HEAD&root=jpackage#id2434750 JPackage Jar File Naming Guideline]  
+
</pre>
+
For something that differs we could note the derivation and that our Guidelines take precedence:
+
<pre>
+
=== Jar File Naming ===
+
Our rules are derived from the [http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?revision=HEAD&root=jpackage#id2434750 JPackage Guidelines]  
+
but we don't use versioned names for jars.  Please use the following rules instead:
+
[...]  
+
</pre>
+
The alternative to this would be to have people read the entirety of the JPackage Guidelines and then point out the places that we differ.  We would probably want to do that by importing the JPackage Guidelines to the wiki and annotating the few cases where we differ.  Note that we would probably want to decide whether resyncing when JPackage changes a Guidelines be done automatically or if the new version had to be brought in through FPC -> FESCo approval.  We would also need someone from the Java team to do that resyncing as we might otherwise be unaware of the changes.
+

Revision as of 15:00, 20 July 2011

These guidelines are laid out in order of relevance to packaging.

Contents

Introduction

The Basics

The term Java means many things to many people: a class library, a bytecode interpreter, a JIT compiler, a language specification, etc. For the vast majority of users and developers, Java is a programming language and runtime environment that is architecture- and OS-agnostic. The normal flow of code is .java (source file) .class (Java bytecode) .jar (a zip archive). In the majority of cases, a user executes a Java program by specifying a class name containing a main method (just like C and C++). Often, this is done by invoking the java binary with a list of JAR files specifying the classpath like so:

java [-cp <jar1:jar2:jar3>] <main-class> [<args>]

Java Packaging

The JPackage Project has defined standard file system locations and conventions for use in Java packages. Many distributions have inherited these conventions and in the vast majority of cases, Fedora follows them verbatim. We include relevant sections of the JPackage guidelines here but caution that the canonical document will always reside upstream: JPackage Guidelines . Over time, we would like to remove any divergences in these documents, but where they are different, these Fedora guidelines will take precedence for Fedora packages.

TODO: Find the proper jpackage link and fix it.

Package naming

Packages MUST follow the standard Fedora Packaging/NamingGuidelines.

Java API documentation MUST be placed into a sub-package called %{name}-javadoc.

Release tags

Packages MUST follow the standard Fedora Package versioning guidelines .

JAR file installation

The following applies to all JAR files except JNI-using JAR files, GCJ files and application-specific JAR files (ie. JAR files that can only reasonably be used as part of an application and therefore constitute application-private data).

Split JAR files

If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging should be preferred.

Filenames

  • If the package provides a single JAR and the filename provided by the build is %{name}.jar or %{name}-%{version}.jar then filename %{name}.jar MUST be used.
  • If the package provides a single JAR and the filename provided by the build is neither %{name}-%{version}.jar nor %{name}.jar then this file MUST be installed as %{name}.jar and a symbolic link with the usual name must be provided.
  • If the package provides more than one JAR file, the filenames assigned by the build MUST be used (without versions).
  • If the project usually provides alternative JAR file names by installing symbolic links then such symlinks MAY be installed in the same directory as the JAR files.

Installation directory

  • All JAR files MUST go into %{_javadir} or a Java-version specific directory %{_javadir}-* as appropriate[1].
  • If the number of provided JAR files exceeds two, you MUST place them into a sub-directory named %{name}.

Javadoc installation

  • Java API documentation uses a system known as javadoc. All javadocs MUST be created and installed into a directory of %{_javadocdir}/%{name}.
  • Directory or symlink %{_javadocdir}/%{name}-%{version} SHOULD NOT exist.
  • The javadoc subpackage MUST be declared noarch even if main package is architecture specific.

BuildRequires and Requires

At a minimum, Java packages MUST:

BuildRequires: java-devel [>= specific_version] 
BuildRequires:  jpackage-utils

Requires:  java >= specific_version
Requires:  jpackage-utils

For historical reasons, when specifying versions 1.6.0 or greater, an epoch of 1 must be included. Example:

Requires: java >= 1:1.6.0

build-classpath

build-classpath is a script that can be used to generate classpaths from generic names of JAR files. Example:

export CLASSPATH=$(build-classpath commons-logging commons-net xbean/xbean-reflect)
Note.png
Additional information
You can use either package names (all jar files will be included) or jar filenames with path prefix to select only some jar files from whole package.

build-jar-repository

build-jar-repository is similar to build-classpath but instead of producing a classpath entry, it creates symlinks in a given directory. Example:

$ mkdir lib
$ build-jar-repository -s -p lib commons-logging commons-net
$ ls -l lib
commons-logging.jar -> /usr/share/java/commons-logging.jar
commons-net.jar -> /usr/share/java/commons-net.jar

ant

ant is a build tool used by many Java packages. Packages built using ant ship with build.xml files which contain build targets similar to Makefiles. Packages built using ant must:

BuildRequires: ant
...
%build
...
ant

maven2

In Fedora 14 and older (including EPEL), the package is called maven2. Packages built using maven ship with pom.xml files. They MUST:

Requires(post): jpackage-utils
Requires(postun): jpackage-utils

and SHOULD contain common sections such as the following:

...
%build
export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository
mkdir -p $MAVEN_REPO_LOCAL

mvn-jpp \
-Dmaven.repo.local=$MAVEN_REPO_LOCAL \
install javadoc:javadoc
...

%install
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
# artifactId and jarName are usually %{name} for single module projects
%add_to_maven_depmap [groupId] [artifactId] %{version} JPP[/optional_subDir] [jarName]

...
%post
%update_maven_depmap

%postun
%update_maven_depmap
...
Note.png
Note:
Multimodule Maven projects should use javadoc:aggregate instead of javadoc:javadoc.
Important.png
Important
Please read Java/JPPMavenReadme for details about mvn-jpp and %add_to_maven_depmap usage.

maven3

In Fedora 15 and newer, maven 3 is used and the package is called maven. Packages built using maven ship with pom.xml files. They SHOULD contain common sections such as the following:

...
%build
mvn-rpmbuild install javadoc:aggregate 
...

%install
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
install -pm 644 target/%{name}-%{version}.jar $RPM_BUILD_ROOT/%{_javadir}/%{name}.jar

# second argument is optional (parent poms have no jars)
%add_maven_depmap JPP-%{name}.pom %{name}.jar
...
%files
%{_mavendepmapfragdir}/%{name}
%{_mavenpomdir}/JPP-%{name}.pom

Useful mvn-rpmbuild customisations:

  • -Dmaven.local.depmap.file=FILE.xml - xml file that defines alternative dependency maps
  • -Dmaven.local.debug=true makes custom resolver output more debugging information
Important.png
Important
Fedora 15+ have both Maven 3.X and Maven 2.2.1 (packages maven and maven2 respectively). Only maven package contains mvn-rpmbuild. Maven 2 is considered deprecated and is included to ensure backward compatibility. Use of maven2 is strongly discouraged in Fedora 15 and newer.
Important.png
Important
For detailed instructions on use of add_maven_depmap macro see macro documentation

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 %add_maven_depmap macro. In its simplest form add_maven_depmap looks like this:

%add_maven_depmap JPP-%{name}.pom

This will read pom file in question and provide mapping between groupId,artifactId inside pom file and pom file placed into %{_mavenpomdir}. Given pom file already has to exist inside %{_mavenpomdir}. Mapping is stored inside %{_mavendepmapfragdir}/%{name} file. All mappings (fragments) are read by mvn-rpmbuild during startup. This form should only be used for pom-only artifacts (i.e. parent poms).

%add_maven_depmap JPP-%{name}.pom %{name}.jar

In addition to creating mapping, this will also ensure that jar and pom files are named correctly and placed in correct subdirectories.

%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. I.e. if pom file stated it contains groupId commons-lang, artifactId commons-lang, by using this form we also added mapping between groupId org.apache.commons and jar/pom files.

%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.

Wrapper Scripts

Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in %{_bindir}.

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.

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

The previous example installs the "msv" script (5th argument) with main class being com.sun.msv.driver.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.

GCJ

Building GCJ AOT bits is discouraged unless you have a very strong reason to include them in the packages. Even when AOT bits are built and included in packages it is recommended to not require java-1.5.0-gcj because this will force every single user to install it even if one wants to use another JVM.

Please refer to Packaging/GCJGuidelines for GCJ-specific guidelines.

-devel packages

-devel packages don't really make sense for Java packages. Header files do not exist for Java packages.


Maven pom.xml files and depmaps

If upstream project is shipping Maven pom.xml files, these MUST be installed with the corresponding %add_maven_depmap calls.

If upstream project does not ship pom.xml file [official maven repo] should be checked and if there are pom.xml files they SHOULD be installed.

Idea.png
Tip
Mvnrepository site can be used to ease

Specfile Template

ant

Name:           # see normal package guidelines
Version:        # see normal package guidelines
Release:        1%{?dist}
Summary:        # see normal package guidelines

Group:          # see normal package guidelines
License:        # see normal package guidelines
URL:            # see normal package guidelines
Source0:        # see normal package guidelines
BuildArch:      noarch

BuildRequires:  jpackage-utils

BuildRequires:  java-devel

BuildRequires:  ant

Requires:       jpackage-utils

Requires:       java

%description

%package javadoc
Summary:        Javadocs for %{name}
Group:          Documentation
Requires:       jpackage-utils

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

%prep
%setup -q

find -name '*.class' -exec rm -f '{}' \;
find -name '*.jar' -exec rm -f '{}' \;

%build
ant

%install

mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}

%files
%{_javadir}/*
%doc

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


%changelog


maven 2

Important.png
Important
Fedora 15+ have both Maven 3.X and Maven 2.2.1 packaged (packages maven and maven2 respectively). Maven 2 is considered deprecated and is included to ensure backward compatibility. Use of maven2 is strongly discouraged, however, older Fedora releases (and EPEL) still require its use.
Name:           # see normal package guidelines
Version:        # see normal package guidelines
Release:        1%{?dist}
Summary:        # see normal package guidelines

Group:          # see normal package guidelines
License:        # see normal package guidelines
URL:            # see normal package guidelines
Source0:        # see normal package guidelines

BuildArch:      noarch

BuildRequires:  jpackage-utils

BuildRequires:  java-devel

BuildRequires:  maven2

BuildRequires:    maven-compiler-plugin
BuildRequires:    maven-install-plugin
BuildRequires:    maven-jar-plugin
BuildRequires:    maven-javadoc-plugin
BuildRequires:    maven-release-plugin
BuildRequires:    maven-resources-plugin
BuildRequires:    maven-surefire-plugin

Requires:       jpackage-utils

Requires(post):       jpackage-utils
Requires(postun):     jpackage-utils

Requires:       java

%description
some smart and long description.

%package javadoc
Summary:        Javadocs for %{name}
Group:          Documentation
Requires:       jpackage-utils

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

%prep
%setup -q

%build

export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository
mkdir -p $MAVEN_REPO_LOCAL

mvn-jpp -Dmaven.repo.local=$MAVEN_REPO_LOCAL \
        install javadoc:javadoc # or javadoc:aggregate

%install

mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}

install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -pm 644 [path to pom]  \
        $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom

%add_to_maven_depmap project_group_id project_artifact_id %{version} JPP %{name}


%post
%update_maven_depmap

%postun
%update_maven_depmap


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

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

%changelog

Important.png
Depmap information
Last two arguments to %add_to_maven_depmap macro represent location of installed jar file. Using ".. jpp/foo bar" as last two arguments will mean that groupId/artifactId of package will resolve to jar file %{_javadir}/foo/bar.jar.

For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located here .

maven 3

Important.png
Important
Only Fedora 15 and newer releases have Maven 3. For older releases and EPEL, refer to the maven 2 template.
Name:           # see normal package guidelines
Version:        # see normal package guidelines
Release:        1%{?dist}
Summary:        # see normal package guidelines

Group:          # see normal package guidelines
License:        # see normal package guidelines
URL:            # see normal package guidelines
Source0:        # see normal package guidelines

BuildArch:      noarch

BuildRequires:  jpackage-utils

BuildRequires:  java-devel

BuildRequires:  maven

BuildRequires:    maven-compiler-plugin
BuildRequires:    maven-install-plugin
BuildRequires:    maven-jar-plugin
BuildRequires:    maven-javadoc-plugin
BuildRequires:    maven-release-plugin
BuildRequires:    maven-resources-plugin
BuildRequires:    maven-surefire-plugin

Requires:       jpackage-utils
Requires:       java

%description
some smart and long description.

%package javadoc
Summary:        Javadocs for %{name}
Group:          Documentation
Requires:       jpackage-utils

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

%prep
%setup -q

%build
mvn-rpmbuild install javadoc:aggregate

%install

mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}

install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
install -pm 644 [path to pom]  \
        $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom

%add_maven_depmap JPP-%{name}.pom %{name}.jar


%files
%{_mavenpomdir}/JPP-%{name}.pom
%{_mavendepmapfragdir}/%{name}
%{_javadir}/%{name}.jar
%doc

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

%changelog

Important.png
Important
For detailed instructions on use of add_maven_depmap macro see macro documentation

Packaging JAR files that use JNI

Applicability

Java programs that wish to make calls into native libraries do so via the Java Native Interface (JNI). A Java package uses JNI if it contains a .so

Stop (medium size).png Note that GCJ packages contain .sos in %{_libdir}/gcj/%{name} but they are not JNI .sos.

Guideline

JAR files that require JNI shared objects MUST be installed in %{_libdir}/%{name}. The JNI shared objects themselves must also be installed in %{_libdir}/%{name}. If the JNI-using code calls System.loadLibrary you'll have to patch it to use System.load, passing it the full path to the dynamic shared object. If the package installs a wrapper script you'll need to manually add %{_libdir}/%{name}/<jar filename> to CLASSPATH. If you are depending on a JNI-using JAR file, you'll need to add it manually -- build-classpath will not find it.

Rationale

This is less convenient, but cleaner from a packaging point-of-view, than putting the JAR file in %{_javadir}, and putting the JNI shared object in %{_libdir} to be loaded from the default library path. First, JNI shared objects are dlopen'd, and dlopen'd shared objects should not be placed directly in %{_libdir} since they are application-private data, and not libraries meant to be linked to directly -- that is, not meant to be shared. Second, placing the JAR file in %{_javadir} causes the build-classpath script to always load it, even when running on a runtime environment of the wrong arch, meaning that the System.loadLibrary line would fail.

The plan is to eventually eliminate patching of the System.loadLibrary line and wrapper script by making jpackage-utils multilib aware. This involves the following changes: creating %{_libdir}/java and %{_libdir}/jni directories; giving JNI-containing packages the ability to require an architecture-specific runtime environment; adding support for specifying the required runtime architecture in a wrapper script; modifying jpackage-utils's runtime scripts to search %{_libdir}/java; modifying IcedTea to look for JNI shared objects in %{_libdir}/jni.

The %{_jnidir} rpm macro defines the main JNI jar repository. Like %{_javadir} it is declined in -ext and -x.y.z variants. It follows exactly the same rules as the %{_javadir}-derived tree structure, except that it hosts JAR files that use JNI.

%{_jnidir} usually expands into /usr/lib/java.

Things to avoid

Pre-built JAR files / Other bundled software

Many Java projects re-ship their dependencies in their own releases. This is unacceptable in Fedora. All packages MUST be built from source and MUST enumerate their dependencies with Requires. They MUST NOT build against or re-ship the pre-included JAR files but instead symlink out to the JAR files provided by dependencies. There may arise rare cases that an upstream project is distributing JAR files that are actually not re-distributable by Fedora. In this situation, the JAR files themselves should not be redistributed -- even in the source zip. A modified source zip should be created with some sort of modifier in the name (ex. -CLEAN) along with instructions for reproducing. It is a good idea to have something similar to the following at the end of %prep (courtesy David Walluck):

JAR files=""
for j in $(find -name \*.jar); do
if [ ! -L $j ] ; then
JAR files="$JAR files $j"
fi
done
if [ ! -z "$JAR files" ] ; then
echo "These JAR files should be deleted and symlinked to system JAR files: $JAR files"
exit 1
fi

Javadoc scriptlets

Older JPackage packages contained %post scriptlets creating %ghost symlinks. These MUST not appear in Fedora Java packages and are actively being removed at JPackage.

Selected rpmlint issues

class-path-in-manifest

Use sed to remove class-path elements in MANIFEST.MF (or whatever file is being used as the JAR manifest) prior to JAR creation. Example:

sed -i '/class-path/I d' META-INF/MANIFEST.MF