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.
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
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 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 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 file installed filename MUST be
%{name}.jar. - If the package provides multiple JAR file, files MUST 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
Here %{name} refers either to package name, or name of subpackage where the jar is installed.
Installation directory
- All architecture-independent JAR files MUST go into
%{_javadir}or a Java-version specific directory%{_javadir}-*as appropriate[1]. Packages CAN place JAR files into subdirectories.
- For installation of architecture dependent JAR files, see Packaging JAR files that use JNI
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 are named in the same way as original except addition of version to package name,
- Any JAR or POM files MUST be versioned.
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.
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
noarcheven if main package is architecture specific.
BuildRequires and Requires
Java packages MUST BuildRequire their respective build system:
BuildRequires: maven-localfor packages built with MavenBuildRequires: antfor packages built with antBuildRequires: java-develfor packages built with javacBuildRequires: gradlefor packages built with gradle
Java binary packages MUST have transitive Requires on:
javaorjava >= 1:minimal_required_versionjpackage-utils
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)
You can use either jar filename or directory name relative to %{_javadir}, %{_jnidir} or %{_javajnidir} (all jar files will be included).
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
Maven pom.xml files and depmaps
If upstream project is shipping Maven pom.xml files, these MUST be installed. Additionally they MUST install corresponding depmaps by calling %add_maven_depmap macro.
Example:
...
%install
...
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
%add_maven_depmap JPP-%{name}.pom %{name}.jar
...
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.
-devel packages
-devel packages don't really make sense for Java packages. Header files do not exist for Java packages.
Specfile Template
Apache Ant
Name: # see normal package guidelines
Version: # see normal package guidelines
Release: 1%{?dist}
Summary: # see normal package guidelines
License: # see normal package guidelines
URL: # see normal package guidelines
Source0: # see normal package guidelines
BuildArch: noarch
BuildRequires: ant
Requires: jpackage-utils
Requires: java
%description
%package javadoc
Summary: API documentation for %{name}
%description javadoc
This package contains %{summary}.
%prep
%setup -q
find -name \*.jar -o -name \*.class -delete
%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}/%{name}.jar
%doc LICENSE
%files javadoc
%{_javadocdir}/%{name}
%doc LICENSE
%changelog
Apache Maven
Name: # see normal package guidelines
Version: # see normal package guidelines
Release: 1%{?dist}
Summary: # see normal package guidelines
License: # see normal package guidelines
URL: # see normal package guidelines
Source0: # see normal package guidelines
BuildArch: noarch
BuildRequires: maven-local
%description
some smart and long description.
%package javadoc
Summary: API documentation for %{name}
%description javadoc
This package contains %{symmary}.
%prep
%setup -q
%build
%mvn_build
%install
%mvn_install
%files -f .mfiles
%dir %{_javadir}/%{name}
%doc LICENSE
%files javadoc -f .mfiles-javadoc
%doc LICENSE
%changelog
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[2] 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.
.png){kind=small}
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 CAN BE symlinked to%{_libdir}/%{name}. - JNI shared objects MUST be placed 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.%{_jnidir} usually expands into %{_prefix}/lib/java. %{_prefix}/lib64/java will cease its existence and will be decomissionedExample
To satisfy this Fedora requirement of using "System.load()" instead of "System.loadLibrary()" while still providing 32-bit versus 64-bit usability as well as complying with Java's write-once-run-anywhere goal, most JNI jar file should contain code similar to the following (as used in the pki-symkey JNI package):
static boolean tryLoad(String filename) {
try {
System.load(filename);
} catch (Exception e) {
return false;
} catch (UnsatisfiedLinkError e) {
return false;
}
return true;
}
// Load native library
static {
boolean mNativeLibrariesLoaded = false;
String os = System.getProperty("os.name");
if ((os.equals("Linux"))) {
// Check for 64-bit library availability
// prior to 32-bit library availability.
mNativeLibrariesLoaded =
tryLoad("/usr/lib64/symkey/libsymkey.so");
if (mNativeLibrariesLoaded) {
System.out.println("64-bit symkey library loaded");
} else {
// REMINDER: May be trying to run a 32-bit app
// on 64-bit platform.
mNativeLibrariesLoaded =
tryLoad("/usr/lib/symkey/libsymkey.so");
if (mNativeLibrariesLoaded) {
System.out.println("32-bit symkey library loaded");
} else {
System.out.println("FAILED loading symkey library!");
System.exit(-1);
}
}
} else {
try {
System.loadLibrary("symkey");
System.out.println("symkey library loaded");
mNativeLibrariesLoaded = true;
} catch (Throwable t) {
// This is bad news, the program is doomed at this point
t.printStackTrace();
}
}
}
Packages utilizing approach of bundling so files as resources within JAR files themselves do not have these issues and are more self-contained.
Notes on multiarch
Our guidelines have never been completely multiarch-aware. So it was never really possible to install both i686 and x86_64 JNI-using java libraries. However guidelines complicated things by introducing usage of %{_libdir} and other directories. This version makes it clear we do not support multiarch for JNI-using packages.
Some of the complications with multiarch for JNI packages are:
- build-classpath and related tools would need to be aware what will be architecture of executing JVM
- build-jar-classpath would still not work for creating symlinks because it would create them on build architecture instead of runtime architecture
- Previous reasons cause creating of /usr/bin wrappers impractical
- Handling proper requires in RPM is impossible. For example package Z-native.i686 and JDK.x86_64 are installed. As far as RPM is concerned this would be enough to provide Z.noarch with needed "Requires: Z-native", but it would not work during runtime.
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