These guidelines are laid out in order of relevance to packaging.
Introduction
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.
- For installation of architecture dependent JAR files, see Packaging JAR files that use JNI.
Filenames
- If the package provides a single JAR file installed filename SHOULD be
%{name}.jar
. - If the package provides multiple JAR file, files SHOULD be installed in a
%{name}
subdirectory - Versioned JAR files (
*-%{version}.jar
) MUST NOT be installed unless the package is a compatibility package - Packages CAN provide alternative filenames as long as they do not conflict with other packages
BuildRequires and Requires
Java packages MUST BuildRequire their respective build system:
BuildRequires: maven-local
for packages built with MavenBuildRequires: ant
for packages built with antBuildRequires: java-devel
for packages built with javac
Java binary packages or their dependencies MUST have Requires (generated by RPM or manual) on:
java-headless
orjava-headless >= 1:minimal_required_version
jpackage-utils
If java-headless requirement is insufficient package MUST have Requires:
java
orjava >= 1:minimal_required_version
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.
No class-path in MANIFEST.MF
- JAR files MUST NOT include
classh-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 either %mvn_install
or %add_maven_depmap
macros.
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
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.
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.
Packaging and using EE APIs
There are a number of various project providing implementations for Java EE APIs. To simplify packaging and use of these APIs certain standardization is necessary.
EE API List
Following is a list of EE APIs as of Java EE 6[1] with chosen packages that provide implementations:
- javax.activation - JDK
- javax.annotation - JDK
- javax.el - tomcat-el-2.2-api
- javax.enterprise.inject - cdi-api
- javax.inject - atinject
- javax.jws - JDK
- javax.mail - javamail
- javax.management - JDK
- javax.management.remote - JDK
- javax.persistence - geronimo-jpa
- javax.security.auth.message - geronimo-jaspic-spec
- javax.servlet - tomcat-servlet-3.0-api
- javax.servlet.jsp - glassfish-jsp/glassfish-jsp-api
- javax.servlet.jsp.jstl - jakarta-taglibs-standard
- javax.transaction - JDK
- javax.ws.rs - jsr-311
- javax.wsdl - wsdl4j
- javax.xml - JDK
- javax.xml.bind - JDK
- javax.xml.rpc - axis
- javax.xml.soap - JDK
- javax.xml.stream - JDK
- javax.xml.ws - JDK
Packages providing APIs
In addition to following generic guidelines they MUST:
- Add Provides: javax.XXX from the EE API list
- Add directory %{_javadir}/javax.XXX that will contain symlinks to all implementation jar files and their dependencies
At one time there CAN BE multiple API implementations but there MUST be at most one package having specific javax.XXX virtual provide.
Packages using APIs
Packages that need to use EE API SHOULD use:
- Requires: javax.XXX from the EE API list
- build-classpath javax.XXX or equivalent instead of relying on package-specific jar name.
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 .so
s 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 CAN BE symlinked to%{_libdir}/%{name}
. - JNI shared objects MUST be placed in
%{_libdir}/%{name}