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://fedorahosted.org/released/javapackages/doc/ 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.

−

=== The Basics ===

+

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.

−

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 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 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 a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging '''should''' be preferred.

+

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.

−

==== Filenames ====

+

== JAR file installation ==

−

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

+

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

−

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

+

=== Split JAR files ===

−

==== Installation directory ====

+

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

* For installation of architecture dependent jar files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]]

+

* All architecture-independent JAR files '''MUST''' go into <code>%{_javadir}</code> or its subdirectory.

−

=== Compatibility packages ===

+

* For installation of architecture dependent JAR files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]].

−

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

+

=== Filenames ===

−

* Jar and pom files '''MUST''' be versioned

−

* Additional version symlinks '''CAN''' be created with "%mvn_build -v"

−

{{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 from main package and will return versioned jar if it matches the version asked for in the pom file.}}

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.

−

</pre>

−

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

+

== Maven pom.xml files ==

+

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 either <code>%mvn_install</code> or <code>%add_maven_depmap</code> macros.

Java package doesn't need to specify any Requires, because these will be automatically generated.

−

=== build-classpath ===

+

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>build-classpath</code> is a script that can be used to generate classpaths from generic names of JAR files. Example:

<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 ===

+

== Wrapper Scripts ==

−

<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:

+

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.

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

+

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:

−

−

<pre>

−

BuildRequires: maven-local

−

...

−

%build

−

%mvn_build

−

...

−

−

%install

−

%mvn_install

−

...

−

−

−

%files -f .mfiles

−

</pre>

−

−

Useful <code>%mvn_build</code> options:

−

* <code>-X</code> - enable debugging output

−

* <code>-f</code> - skip compilation and execution of tests

−

* <code>-j</code> - skip javadoc generation and installation

−

−

=== Mapping between pom and jar files ===

−

{{Anchor|pom_jar_mapping}}

−

−

Maven identifies jar files by a set of strings: groupId, artifactId and version (mostly). <code>%mvn_install</code> reads the groupId and artifactId from the pom file and creates a file in <code>%{_mavendepmapfragdir}</code> that maps groupId:artifactId pairs to jar files under <code>%{_javadir}</code>.

The macro <code>%mvn_alias</code> can be used to add additional mappings for given pom/jar file. For example, if the pom file indicates that it contains groupId commons-lang, artifactId commons-lang, this macro ensures that we also add a mapping between groupId org.apache.commons and the installed jar/pom files. This is necessary in cases where the groupId or artifactId may have changed, and other packages might require different IDs than those reflected in the installed pom.

−

−

=== Alternative JAR file names ===

−

In some cases, it may be important to be able to provide symlinks to actual JAR files. This can be achieved with <code>%mvn_file</code> macro. This macro allows packager to specify name of the JAR files, its location in <code>%{_javadir}</code> directory and can create symlinks to the JAR file. These symlinks can be possibly located outside of the <code>%{_javadir}</code> directory.

−

−

Example of usage of <code>%mvn_file</code> macro:

−

−

<pre>

−

%pre

−

...

−

%mvn_file :guice google/guice guice

−

</pre>

−

−

This means that JAR file for artifact identified as artifactId="guice" (any groupId) will by will be installed in <code>%{_javadir}/google/guice.jar</code> and there will be also a symlink to this jar file located in <code>%{_javadir}/guice.jar</code>. Note the macro will add ".jar" extension automatically.

−

−

=== Single artifact per package ===

−

If the project consists of multiple artifacts, it is recommended to install each artifact to the separate subpackage. The macro <code>%mvn_build -s</code> will automatically generate <code>.mfiles</code> file for every artifact in the project. This file contains list of files related to specific artifact (typically JAR file, POM file and depmap). It can be later used in <code>%files</code> section of the spec file.

If upstream project is shipping Maven pom.xml files, these '''MUST''' be installed with <code>%mvn_install</code> call. The macro will also automatically install corresponding depmap.

−

−

If upstream project does not ship pom.xml file [[http://search.maven.org/ 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}}

−

−

=== Patching Maven <code>pom.xml</code> files ===

−

−

Sometimes Maven <code>pom.xml</code> files need to be patched before they are used to build packages. One could use traditional patches to maintain changes, but package maintainers '''SHOULD''' use <code>%pom_*</code> macros developed specially to ease this task.

−

−

These macros are designed to be called from <code>%prep</code> section of spec files. There are documented in <code>/etc/rpm/macros.fjava</code> configuration file, which is also [http://git.fedorahosted.org/git/?p=javapackages.git;a=blob_plain;f=macros.fjava available online]. See the documentation for technical details how to use these macros. Below are some examples added for convenience.

−

−

Often dependencies specified in Maven <code>pom.xml</code> files need to be removed because of different reasons. <code>%pom_remove_dep</code> macro can be used to ease this task:

Sometimes some submodules of upstream project cannot be built for various reasons and there is a need to disable them. This can be achieved by using <code>%pom_disable_module</code>, for example:

−

−

<pre>

−

# Disables child-module-1, a submodule of the main pom.xml file

−

%pom_disable_module child-module-1

−

−

# Disables grandchild-module, a submodule of child-module-2/pom.xml

−

%pom_disable_module grandchild-module child-module-2

−

</pre>

−

−

The above macros cover the most common cases of modifying <code>pom.xml</code> files, however if there is a need to apply some less-common patches there are also two generic macros for modifying <code>pom.xml</code> files. <code>%pom_xpath_remove</code> can be used to remove arbitrary XML nodes, described by [http://www.w3.org/TR/xpath/ XPath] expressions. <code>%pom_xpath_inject</code> macro is capable of injecting arbitrary [http://www.w3.org/TR/xml/ XML] code to any <code>pom.xml</code> file. Below you can find some examples for these macros.

{{admon/note|Note|POM files use a specific namespace - http://maven.apache.org/POM/4.0.0. The easiest way to respect this namespace in XPath expressions is prefixing all node names with <code>pom:</code>. For example, <code>pom:environment/pom:os</code> will work because it selects nodes from <code>pom</code> namespace, but <code>environment/os</code> won't find anything because it looks for nodes that don't belong to any XML namespace.}}

−

−

Using <code>%pom_*</code> macros not only increases readability of the spec file, but also improves maintainability of the package as there are no patches that would need to be rebased with each upstream release.

−

−

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

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 ===

−

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.

* Compatibility packages '''MUST''' be named in the same way as original except addition of version to package name,

−

BuildRequires: maven-install-plugin

+

* Any JAR and POM files '''MUST''' be versioned.

−

BuildRequires: maven-jar-plugin

−

BuildRequires: maven-javadoc-plugin

−

BuildRequires: maven-release-plugin

−

BuildRequires: maven-resources-plugin

−

BuildRequires: maven-surefire-plugin

−

−

−

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

−

−

%install

−

%mvn_install

−

−

−

%files -f .mfiles

−

%doc

−

−

%files javadoc -f .mfiles-javadoc

−

%doc

−

−

%changelog

−

−

</pre>

+

{{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.}}

{{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.}}

+

{{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]].}}

−

−

{{admon/note|Macro expansions|<code>%{_jnidir}</code> usually expands into <code>%{_prefix}/lib/java</code>. <code>%{_prefix}/lib64/java</code> will cease its existence and will be decomissioned}}

−

−

=== Example ===

−

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):

−

<pre>

−

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();

−

}

−

}

−

}

−

</pre>

−

−

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 <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 ===

+

{{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.}}

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.

Release tags

Pre-built dependencies

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

NoteHere %{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

jpackage-utils

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

java or java >= 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.

Additional documentationUsage of %add_maven_depmap macro is documented in detail in Java Packaging HOWTO.

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

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 compatibilitybuild-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 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:

Packages using APIs

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.