From Fedora Project Wiki

(Moved "comments" block to the talk page where people can actually edit them.)
(Deprecate this page.)
 
(21 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<!-- page was renamed from PackagingDrafts/Java
{{OldGuidelinePage|Java}}
-->
{{DISPLAYTITLE:Fedora Packaging Guidelines for Java}}
= Java Packaging Guidelines =
<div style="float: right; margin-left: 0.5em" class="toclimit-2">__TOC__</div>
These guidelines are laid out in order of relevance to packaging.


This page represents Fedora guidelines for packaging libraries and applications written in Java and related languages using Java Virtual Machine as bytecode interpreter. It does not aim to extensively describe packaging techniques and tips. RPM macros and commands used here are documented in man pages. Furthermore a separate [https://fedora-java.github.io/howto/latest/ Java Packaging HOWTO] describes Java packaging techniques in detail and includes examples, templates and documentation aimed at packagers and Java developers who are taking their first steps in Java RPM packaging.


Fedora Java packaging is originally based on [http://www.jpackage.org JPackage Project] standards. Over time we have diverged in packaging tools in most areas but we mostly keep backward compatibility with older packages that make use of JPackage standards.


== Introduction ==


=== Background ===
== Package naming ==
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 ===
Packages MUST follow the standard Fedora [[Packaging/NamingGuidelines | package naming guidelines]].
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>
Java API documentation MUST be placed into a sub-package called <code>%{name}-javadoc</code>.


== Java Packaging ==
== Release tags ==
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.
Packages MUST follow the standard Fedora [[Packaging/NamingGuidelines#Package_Versioning | package versioning guidelines]].


=== Package naming ===
== Pre-built dependencies ==
Packages MUST follow the standard Fedora [[Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries | dependency bundling guidelines]].


Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines]]  .  Java API documentation '''MUST''' be placed into a sub-package called <code>%{name}-javadoc</code>.
In particular <code>*.class</code> and <code>*.jar</code> files from upstream releases MUST NOT be used during build of Fedora packages and they MUST NOT be included in binary RPM.


==== Release tags ====
== JAR file installation ==
For now, refer to the [[Packaging/JPackagePolicy]]  for release tags.  That document should eventually be folded into this one.


=== Jar file naming ===
The following applies to all JAR files except [[#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).


# If a package provides a single JAR file it must have the same name as the package itself.
=== Split JAR files ===


ex. <code>jaf.jar</code>
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 project name and the commonly used JAR filename differ, a symbolic link with the usual name must also be provided.
=== Installation directory ===


ex. Single JAR complete naming.  Project name is <code>jaf</code>, common name is <code>activation</code>.
* All architecture-independent JAR files MUST go into <code>%{_javadir}</code> or its subdirectory.


<code>activation.jar ’ jaf.jar</code>
* For installation of architecture dependent JAR files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]].


# If the package provides several JAR files, the filenames assigned by the build must be used.  Above symlinking rules apply.
=== Filenames ===


ex.   <pre>ant-1.5.3.jar
* If the package provides a '''single''' JAR file installed filename SHOULD be <code>%{name}.jar</code>.
ant-optional-1.5.3.jar</pre>
* If the package provides '''multiple''' JAR files, they SHOULD be installed in a <code>%{name}</code> subdirectory
* Versioned JAR files (<code>*-%{version}.jar</code>) MUST NOT be installed unless the package is a compatibility package
* Packages MAY provide alternative filenames as long as they do not conflict with other packages


# If the number of provided JAR files exceeds '''two''', you must place them into a sub-directory.


# If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging should be preferred.
{{admon/note|Note|Here %{name} refers either to package name, or name of subpackage where the jar is installed.}}


=== Directory structure ===
== BuildRequires and Requires ==
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 packages MUST BuildRequire their respective build system:
* <code>BuildRequires: maven-local</code> for packages built with Maven
* <code>BuildRequires: ant</code> for packages built with ant
* <code>BuildRequires: java-devel</code> for packages built with javac


Java API documentation uses a system known as javadoc.  All javadocs '''MUST''' be installed into <code>%{_javadocdir</code>}.
Java binary packages or their dependencies MUST have Requires (generated by RPM or manual) on:
* <code>java-headless</code> or <code>java-headless >= 1:minimal_required_version</code>
* <code>javapackages-filesystem</code>


=== BuildRequires and Requires ===
If java-headless requirement is insufficient package MUST have Requires:
At a minimum, Java packages '''MUST''':
* <code>java</code> or <code>java >= 1:minimal_required_version</code>


<pre>BuildRequires: java-devel [>= specific_version]
== Javadoc installation ==
BuildRequires:  jpackage-utils


Requires:  java >= specific_version
* javadoc documentation MAY be generated
Requires:  jpackage-utils</pre>
* If javadoc documentation is generated it MUST be installed into a directory of <code>%{_javadocdir}/%{name}</code> as part of javadoc subpackage
* 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.


For historical reasons, when specifying versions 1.6.0 or greater, an epoch of 1 must be included.  Example:
== No class-path in MANIFEST.MF ==
* JAR files MUST NOT include <code>class-path</code> entry inside META-INF/MANIFEST.MF


<pre>Requires: java >= 1:1.6.0
== Hardcoded paths ==
</pre>
Packages MUST NOT hardcode paths to JAR files they use. When package needs to reference a JAR file, packager SHOULD use one of tools designed to locating JAR files in the system.


=== build-classpath ===
== Maven pom.xml files ==
<code>build-classpath</code> is a script that can be used to generate classpaths from generic names of JAR files. Example:
If upstream project is shipping Maven <code>pom.xml</code> files, these MUST be installed. Additionally package MUST install mapping between upstream artifact and filesystem by using the <code>%mvn_install</code> macro.


<pre>export CLASSPATH=$(build-classpath commons-logging commons-net)
{{admon/note|Additional documentation|Additional artifact installation documentation is available for[https://fedora-java.github.io/howto/latest/#ant Ant projects] and [https://fedora-java.github.io/howto/latest/#maven Maven projects].}}
</pre>


=== build-jar-repository ===
<code>build-jar-repository</code> is similar to <code>build-classpath</code> but instead of producing a classpath entry, it creates symlinks in a given directory.  Example:
<pre>$ 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
</pre>


=== ant ===
If upstream project does not ship Maven <code>pom.xml</code> file, official [http://mvnrepository.com/ maven repository] should be searched and if there are <code>pom.xml</code> files they SHOULD be installed.
<code>ant</code> is a build tool used by many Java packages. Packages built using <code>ant</code> ship with <code>build.xml</code> files which contain build targets similar to <code>Makefiles</code>. Packages built using <code>ant</code> must:


<pre>BuildRequires: ant
If modifications to Maven pom.xml files are needed <code>%pom_*</code> family of macros SHOULD be used
...
%build
...
ant
</pre>


=== maven ===
{{admon/note|Additional documentation|Usage of %pom_* macros is documented in detail in [https://fedora-java.github.io/howto/latest/#helper_macros Java Packaging HOWTO].}}
<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''':


<pre>Requires(post): jpackage-utils
== Wrapper Scripts ==
Requires(postun): jpackage-utils</pre>
Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in <code>%{_bindir}</code>. Packages SHOULD use <code>%jpackage_script</code> to create these wrapper scripts.


and '''SHOULD''' contain common sections such as the following:
{{admon/note|Additional documentation|Usage of %jpackage_script macro is documented in [https://fedora-java.github.io/howto/latest#_generating_application_shell_scripts Java Packaging HOWTO].}}


<pre>
== Compatibility packages ==
...
In certain cases it might be necessary to create compatibility packages that provide older API/ABI level of the same library. However creating these compatibility packages is strongly discouraged. To standardize and simplify packaging of such compatibility packages following rules apply:
%build
export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository
mkdir -p $MAVEN_REPO_LOCAL


mvn-jpp \
* Compatibility packages MUST be named in the same way as original except addition of version to package name,
-Dmaven.repo.local=$MAVEN_REPO_LOCAL \
* Any JAR and POM files MUST be versioned.
install javadoc:javadoc
...
%install
rm -rf $RPM_BUILD_ROOT
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -d -m 755 $RPM_BUILD_ROOT%{_datadir}/maven2/poms
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_datadir}/maven2/poms/JPP-maven-archiver.pom
%add_to_maven_depmap org.apache.maven maven-archiver %{version} JPP maven-archiver
...
%post
%update_maven_depmap


%postun
{{admon/note|Ant and Maven compatibility|build-classpath and related tools will resolve versioned jar files if versioned jar is asked for. Maven will use dependency information will return versioned jar if it matches the version asked for in the pom file.}}
%update_maven_depmap
...
</pre>
 
=== Wrapper Scripts ===
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
. /usr/share/java-utils/java-functions
 
MAIN_CLASS=MyCoolApp
 
set_classpath "mycoolapp"
 
run "$@"
</pre>
 
=== GCJ ===
Please refer to [[Packaging/GCJGuidelines]]  for GCJ-specific guidelines.
 
=== -devel packages ===
<code>-devel</code> packages don't really make sense for Java packages.  Header files do not exist for Java packages.
 
== Specfile Template ==
=== ant ===
<pre>
Name:          # see normal package guidelines
Version:        # see normal package guidelines
Release:        1%{?dist}
Summary:        # see normal package guidelines (SNPG)
 
Group:          # SNPG
License:        # SNPG
URL:            # SNPG
Source0:        # SNPG
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
 
BuildRequires:  jpackage-utils
 
BuildRequires:  java-devel
 
BuildRequires:  ant
 
Requires:      jpackage-utils
 
Requires:      java
 
%description
 
%package javadoc
Summary:        Javadocs for %{name}
Group:          Development Documentation
Requires:      %{name} = %{version}-%{release}
Requires:      jpackage-utils
 
%description javadoc
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
%setup -q
 
 
find -name '*.jar' -o -name '*.class' -exec rm -f '{}' \;
 
 
%build
ant
 
%install
rm -rf $RPM_BUILD_ROOT
 
mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar]  \
$RPM_BUILD_ROOT%{_javadir}/%{name}-%{version}.jar
 
 
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory]  \
$RPM_BUILD_ROOT%{_javadocdir}/%{name}
 
%clean
rm -rf $RPM_BUILD_ROOT
 
%files
%defattr(-,root,root,-)
%{_javadir}/*
%doc
 
%files javadoc
%defattr(-,root,root,-)
%{_javadocdir}/%{name}
 
%files manual
%defattr(-,root,root,-)
%doc [manual directory] /*
 
%changelog
</pre>
 
=== maven ===
<pre>
Name:          # see normal package guidelines
Version:        # see normal package guidelines
Release:        1%{?dist}
Summary:        # see normal package guidelines (SNPG)
 
Group:          # SNPG
License:        # SNPG
URL:            # SNPG
Source0:        # SNPG
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
 
BuildRequires:  jpackage-utils
 
BuildRequires:  java-devel
 
BuildRequires:  maven2
 
BuildRequires:    maven2-plugin-compiler
BuildRequires:    maven2-plugin-install
BuildRequires:    maven2-plugin-jar
BuildRequires:    maven2-plugin-javadoc
BuildRequires:    maven2-plugin-release
BuildRequires:    maven2-plugin-resources
BuildRequires:    maven2-plugin-surefire
 
Requires:      jpackage-utils
 
Requires(post):      jpackage-utils
Requires(postun):    jpackage-utils
 
Requires:      java
 
%description
 
%package javadoc
Summary:        Javadocs for %{name}
Group:          Development/Documentation
Requires:      %{name}-%{version}-%{release}
Requires:      jpackage-utils
 
%description javadoc
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
%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
 
%install
rm -rf $RPM_BUILD_ROOT
 
mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar]  \
$RPM_BUILD_ROOT%{_javadir}/%{name}-%{version}.jar
 
 
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory]  \
$RPM_BUILD_ROOT%{_javadocdir}/%{name}
 
install -d -m 755 $RPM_BUILD_ROOT%{_datadir}/maven2/poms
install -pm 644 [path to pom]  \
$RPM_BUILD_ROOT%{_datadir}/maven2/poms/JPP-%{name}.pom
 
%add_to_maven_depmap org.apache.maven %{name} %{version} JPP %{name}
 
%clean
rm -rf $RPM_BUILD_ROOT
 
%post
%update_maven_depmap
 
%postun
%update_maven_depmap
 
%files
%defattr(-,root,root,-)
%{_datadir}/maven2/poms
%{_mavendepmapfragdir}
%{_javadir}/*
%doc
 
%files javadoc
%defattr(-,root,root,-)
%{_javadocdir}/%{name}
 
%files manual
%defattr(-,root,root,-)
%doc [manual directory] /*
 
%changelog
 
</pre>
 
For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located [http://fedoraproject.org/wiki/Java/JPPMavenReadme here] .


== Packaging JAR files that use JNI ==
{{Anchor|JNI}}
{{Anchor|JNI}}
== Packaging JAR files that use 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 file. Note that this file can be embedded within JAR files themselves.


{{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.
* JNI packages MUST follow guidelines of ordinary Java packages with exceptions listed here
 
* JAR files using JNI or containing JNI shared objects themselves MUST be placed in <code>%{_jnidir}</code> and MAY be symlinked to <code>%{_libdir}/%{name}</code>.
=== Rationale ===
* JNI shared objects MUST be placed in <code>%{_libdir}/%{name}</code>  
 
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 <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>.
{{admon/note|Note|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. You can look at the [[JavaSystemLoadExample|example]].}}


== Things to avoid ==
{{admon/note|Macro expansions|<code>%{_jnidir}</code> expands into <code>%{_prefix}/lib/java</code>, even on 64-bit systems. Java packages using JNI do not support multiarch installation.}}
=== 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 <code>Requires</code>.  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 <code>%prep</code> (courtesy David Walluck):


<pre>
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
</pre>


=== Javadoc scriptlets ===
Older JPackage packages contained <code>%post</code> scriptlets creating <code>%ghost</code> symlinks.  These '''MUST''' not appear in Fedora Java packages and are actively being removed at JPackage.


=== Selected rpmlint issues ===
==== class-path-in-manifest ====
Use <code>sed</code> to remove <code>class-path</code> elements in <code>MANIFEST.MF</code> (or whatever file is being used as the JAR manifest) prior to JAR creation.  Example:


<pre>
[[Category:Java]]
sed -i '/class-path/I d' META-INF/MANIFEST.MF
[[Category:Packaging guidelines]]
</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?'''

Latest revision as of 20:18, 21 December 2018

This is an old copy of a packaging guideline, preserved here in the wiki while we complete the transition to the Fedora documentation system. The current version is located at https://docs.fedoraproject.org/en-US/packaging-guidelines/Java/. Please update your bookmarks.

This page represents Fedora guidelines for packaging libraries and applications written in Java and related languages using Java Virtual Machine as bytecode interpreter. It does not aim to extensively describe packaging techniques and tips. RPM macros and commands used here are documented in man pages. Furthermore a separate Java Packaging HOWTO describes Java packaging techniques in detail and includes examples, templates and documentation aimed at packagers and Java developers who are taking their first steps in Java RPM packaging.

Fedora Java packaging is originally based on JPackage Project standards. Over time we have diverged in packaging tools in most areas but we mostly keep backward compatibility with older packages that make use of JPackage standards.


Package naming

Packages MUST follow the standard Fedora package naming guidelines.

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

Release tags

Packages MUST follow the standard Fedora package versioning guidelines.

Pre-built dependencies

Packages MUST follow the standard Fedora dependency bundling guidelines.

In particular *.class and *.jar files from upstream releases MUST NOT be used during build of Fedora packages and they MUST NOT be included in binary RPM.

JAR file installation

The following applies to all JAR files except 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).

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.

Installation directory

  • All architecture-independent JAR files MUST go into %{_javadir} or its subdirectory.

Filenames

  • If the package provides a single JAR file installed filename SHOULD be %{name}.jar.
  • If the package provides multiple JAR files, they SHOULD be installed in a %{name} subdirectory
  • Versioned JAR files (*-%{version}.jar) MUST NOT be installed unless the package is a compatibility package
  • Packages MAY provide alternative filenames as long as they do not conflict with other packages


Note
Here %{name} refers either to package name, or name of subpackage where the jar is installed.

BuildRequires and Requires

Java packages MUST BuildRequire their respective build system:

  • BuildRequires: maven-local for packages built with Maven
  • BuildRequires: ant for packages built with ant
  • BuildRequires: java-devel for packages built with javac

Java binary packages or their dependencies MUST have Requires (generated by RPM or manual) on:

  • java-headless or java-headless >= 1:minimal_required_version
  • javapackages-filesystem

If java-headless requirement is insufficient package MUST have Requires:

  • java or java >= 1:minimal_required_version

Javadoc installation

  • javadoc documentation MAY be generated
  • If javadoc documentation is generated it MUST be installed into a directory of %{_javadocdir}/%{name} as part of javadoc subpackage
  • Directory or symlink %{_javadocdir}/%{name}-%{version} SHOULD NOT exist.
  • The javadoc subpackage MUST be declared noarch even if main package is architecture specific.

No class-path in MANIFEST.MF

  • JAR files MUST NOT include class-path entry inside META-INF/MANIFEST.MF

Hardcoded paths

Packages MUST NOT hardcode paths to JAR files they use. When package needs to reference a JAR file, packager SHOULD use one of tools designed to locating JAR files in the system.

Maven pom.xml files

If upstream project is shipping Maven pom.xml files, these MUST be installed. Additionally package MUST install mapping between upstream artifact and filesystem by using the %mvn_install macro.

Additional documentation
Additional artifact installation documentation is available forAnt projects and Maven projects.


If upstream project does not ship Maven pom.xml file, official maven repository should be searched and if there are pom.xml files they SHOULD be installed.

If modifications to Maven pom.xml files are needed %pom_* family of macros SHOULD be used

Additional documentation
Usage of %pom_* macros is documented in detail in Java Packaging HOWTO.

Wrapper Scripts

Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in %{_bindir}. Packages SHOULD use %jpackage_script to create these wrapper scripts.

Additional documentation
Usage of %jpackage_script macro is documented in Java Packaging HOWTO.

Compatibility packages

In certain cases it might be necessary to create compatibility packages that provide older API/ABI level of the same library. However creating these compatibility packages is strongly discouraged. To standardize and simplify packaging of such compatibility packages following rules apply:

  • Compatibility packages MUST be named in the same way as original except addition of version to package name,
  • Any JAR and POM files MUST be versioned.
Ant and Maven compatibility
build-classpath and related tools will resolve versioned jar files if versioned jar is asked for. Maven will use dependency information will return versioned jar if it matches the version asked for in the pom file.

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 file. Note that this file can be embedded within JAR files themselves.

Note that GCJ packages contain .sos in %{_libdir}/gcj/%{name} but they are not JNI .sos.

Guideline

  • JNI packages MUST follow guidelines of ordinary Java packages with exceptions listed here
  • JAR files using JNI or containing JNI shared objects themselves MUST be placed in %{_jnidir} and MAY be symlinked to %{_libdir}/%{name}.
  • JNI shared objects MUST be placed in %{_libdir}/%{name}
Note
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. You can look at the example.
Macro expansions
%{_jnidir} expands into %{_prefix}/lib/java, even on 64-bit systems. Java packages using JNI do not support multiarch installation.
Retrieved from "https://fedoraproject.org/w/index.php?title=Packaging:Java&oldid=530783"