(This is a draft update to [[Packaging:Java]].)
These guidelines are laid out in order of relevance to packaging.
== 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. Since 2008 this has enabled Fedora to ship a package under the OpenJDK name.
=== 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
== 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.
=== 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 ====
Java packages '''MUST''' follow the standard Fedora [[Packaging:NamingGuidelines#Package_Release | Release Guidelines]]. If a package is coming into Fedora from JPackage, please refer to [[Packaging/JPackagePolicy]].
=== JAR file installation ===
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).
==== 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
then this filename '''MUST''' be used.
If the package provides a '''single''' JAR and the filename provided by the build is %{name}-%{version}.jar
then this name '''MUST''' be used and a symbolic link %{name}.jar
pointing to this file '''MUST''' be installed.
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.
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[http://lists.fedoraproject.org/pipermail/packaging/2010-January/006792.html].
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 installed into a subdirectory of %{_javadocdir}
. The name of the subdirectory '''MUST''' be either %{name}
or %{name}-%{version}
with a symlink %{name}
pointing to it.
The javadoc subpackage '''MAY''' be declared noarch
.
=== BuildRequires and Requires ===
At a minimum, Java packages '''MUST''':
BuildRequires: java-devel [>= specific_version] BuildRequires: jpackage-utils Requires: java >= specific_version Requires: jpackage-utilsFor 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)=== 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=== maven ===
maven
is a tool used by many Java packages. In Fedora, the package is called maven2
. Packages built using maven
ship with pom.xml
files. They '''MUST''':
Requires(post): jpackage-utils Requires(postun): jpackage-utilsand '''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 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 %update_maven_depmap ...=== Wrapper Scripts === Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in
%{_bindir}
. These can be as simple as this example:
#!/bin/bash . /usr/share/java-utils/java-functions MAIN_CLASS=MyCoolApp set_classpath "mycoolapp" run "$@"=== GCJ === 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.
== Specfile Templates ==
=== 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 BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) BuildRequires: java-devel # Optionally: >= 1:1.6.0 Requires: java >= 1:1.6.0 BuildRequires: jpackage-utils Requires: jpackage-utils BuildRequires: ant %description %package javadoc Summary: Javadocs for %{name} Group: Documentation Requires: jpackage-utils BuildArch: noarch %description javadoc This package contains the API documentation for %{name}. %package manual Summary: Manual for %{name} Group: Documentation Requires: jpackage-utils %description manual The manual for %{name}. %prep %setup -q find -name '*.class' -exec rm -f '{}' \; find -name '*.jar' -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 ln -s %{name}-%{version}.jar \ $RPM_BUILD_ROOT%{_javadir}/%{name}.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=== maven ===
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 BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) BuildRequires: java-devel # Optionally: >= 1:1.6.0 Requires: java >= 1:1.6.0 BuildRequires: jpackage-utils Requires: jpackage-utils Requires(post): jpackage-utils Requires(postun): jpackage-utils 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 %description %package javadoc Summary: Javadocs for %{name} Group: Documentation Requires: jpackage-utils BuildArch: noarch %description javadoc This package contains the API documentation for %{name}. %package manual Summary: Manual for %{name} Group: Documentation Requires: jpackage-utils %description manual The manual for %{name}. %prep %setup -q find -name '*.class' -exec rm -f '{}' \; find -name '*.jar' -exec rm -f '{}' \; %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 ln -s %{name}-%{version}.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%{_datadir}/maven2/poms install -pm 644 [path to pom] \ $RPM_BUILD_ROOT%{_datadir}/maven2/poms/JPP-%{name}.pom # artifactId and jarName are usually %{name} %add_to_maven_depmap [groupId] [artifactId] %{version} JPP[/optional_subDir] [jarName] %clean rm -rf $RPM_BUILD_ROOT %post %update_maven_depmap %postun %update_maven_depmap %files %defattr(-,root,root,-) %{_mavenpomdir}/* %{_mavendepmapfragdir} %{_javadir}/* %doc %files javadoc %defattr(-,root,root,-) %{_javadocdir}/%{name} %files manual %defattr(-,root,root,-) %doc [manual directory]/* %changelogFor detailed instructions on the JPackage/Fedora maven, see [[Java/JPPMavenReadme]]. {{Anchor|JNI}} == 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) by calling the Java method
System.loadLibrary
or System.load
to load a .so
file into the Java runtime environment. If a Java package contains a .so file then it is most likely either a JNI .so file (in which case the JNI guidelines apply) or a GCJ .so file (see below).
=== Guideline ===
JAR files that require JNI shared objects '''MUST''' be installed in a directory %{_libdir}/%{name}
, with the usual filenames and optionally symlinks as provided by the build. The JNI shared objects themselves '''MUST''' also be installed in %{_libdir}/%{name}
. If the JNI-using code calls System.loadLibrary
it must be patched to use System.load
, passing it the full path to the dynamic shared object.
If the package installs a wrapper script then the script will need to add %{_libdir}/%{name}/jar filename
to CLASSPATH
. Likewise, the build-classpath
script will not find JAR files that uses JNI, so they need to be added manually.
=== Rationale ===
A JNI-using JAR file that was placed in %{_javadir}
would be loaded even if the Java runtime environment's architecture didn't match the architecture of the corresponding JNI shared object, in which case the System.loadLibrary
call would fail.
The shared object is dlopen
'd specifically by the corresponding Java archive and is not meant to be loaded any other way. Thus is should not be packaged among the shared libraries in %{_libdir}
.
Thus, though less convenient, it's cleaner from a packaging point-of-view to put the JAR and shared object in an arch- and library-specific directory.
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
(AKA %{_jnidir}
) 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
.
== 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. Any prebuilt binaries (.jar and .class files) '''MUST''' either be removed from the source tree in %prep
or a modified source archive with the offending files remove be provided, in accordance with [[Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries]] and [[Packaging:SourceURL]]. There may arise rare cases that an upstream project is distributing JAR files that are actually not re-distributable by Fedora. In this situation, a modified source archive '''MUST''' be created and used as described above.
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 use the JAR files provided by dependencies.
It is a good idea to have something similar to the following at the end of %prep
:
if find -name '*.class' -o -name '*.jar' | grep . >&2; then echo >&2 "Prebuilt binaries found in the sources. See https://fedoraproject.org/wiki/Packaging:Java#Pre-built_JAR_files_.2F_Other_bundled_software for instructions." 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[[Category:Packaging guidelines]] [[Category:Java]]