Java Packaging Guidelines

These guidelines are laid out in order of relevance to packaging.

Contents

  1. Java Packaging Guidelines
    1. Introduction
      1. Background
      2. The Basics
    2. Java Packaging
      1. Package naming
        1. Release tags
      2. Jar file naming
      3. Directory structure
      4. BuildRequires and Requires
      5. build-classpath
      6. build-jar-repository
      7. ant
      8. maven
      9. Wrapper Scripts
      10. GCJ
      11. -devel packages
    3. Specfile Template
      1. ant
      2. maven
    4. Packaging JAR files that use JNI
      1. Applicability
      2. Guideline
      3. Rationale
    5. Things to avoid
      1. Pre-built JAR files / Other bundled software
      2. Javadoc scriptlets
      3. Selected rpmlint issues
        1. class-path-in-manifest
    6. Comments

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. Recent (early 2008) developments have 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 <jar1:jar2:jar3>] <main-class> [<args>]

Java Packaging

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

For now, refer to the Packaging/JPackagePolicy for release tags. That document should eventually be folded into this one.

Jar file naming

  1. If a package provides a single JAR file it must have the same name as the package itself.

ex. jaf.jar

1. If the project name and the commonly used JAR filename differ, a symbolic link with the usual name must also be provided.

ex. Single JAR complete naming. Project name is jaf, common name is activation.

activation.jar ’ jaf.jar

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

ex. 

ant-1.5.3.jar 
      ant-optional-1.5.3.jar

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

  2. If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging should be preferred.

Directory structure

All JAR files MUST go into %{_javadir}. Exceptions include 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 API documentation uses a system known as javadoc. All javadocs MUST be installed into %{_javadocdir}.

BuildRequires and Requires

At a minimum, Java packages MUST: 

BuildRequires: java-devel [>= specific_version] 
BuildRequires:  jpackage-utils

Requires:  java >= specific_version
Requires:  jpackage-utils

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

and 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
# JAR files/poms
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
install -d -m 755 $RPM_BUILD_ROOT%{_datadir}/maven2/poms
# Copy pom
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 Template

ant

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)

# This package owns /usr/share/java which will be
# needed by practically all java packages
BuildRequires:  jpackage-utils

# Java bytecode compiler, etc.
BuildRequires:  java-devel

# If package requires ant to build  
BuildRequires:  ant

# This package owns /usr/share/java which will be
# needed by practically all java packages
Requires:       jpackage-utils

# Needed to run any java programs
Requires:       java

%description
# SNPG

%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

# All Java binaries must be removed from the sources and be rebuilt

# Remove jar files
find -name '*.jar' -o -name '*.class' -exec rm -f '{}' \;

# You may need to remove other pre-built Java binary files.
# For example: WAR, EAR, SAR, ....

%build
# Substitute -link for javadoc references to dependent packages
# (including the JDK itself)
ant

%install
rm -rf $RPM_BUILD_ROOT

# JAR files
mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar]  \
       $RPM_BUILD_ROOT%{_javadir}/%{name}-%{version}.jar

# Repeat for every other jar

# Javadocs
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}/*
# Add any doc files here
%doc

%files javadoc
%defattr(-,root,root,-)
%{_javadocdir}/%{name}

%files manual
%defattr(-,root,root,-)
%doc [manual directory]/*

%changelog
# SNPG

maven

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)

# This package owns /usr/share/java which will be
# needed by practically all java packages
BuildRequires:  jpackage-utils

# Java bytecode compiler, etc.
BuildRequires:  java-devel

# package requires maven to build
BuildRequires:  maven2

# maven plugins required by this package during build
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

# This package owns /usr/share/java which will be
# needed by practically all java packages
Requires:       jpackage-utils

# This package calls the update_maven_depmap macro in post and postun, provided
# by jpackage-utils
Requires(post):       jpackage-utils
Requires(postun):     jpackage-utils

# Needed to run any java programs
Requires:       java

%description
# SNPG

%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

# By default, maven uses ~/.m2/ for cache
# Make it use a clean, local subdir directory instead
export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository
mkdir -p $MAVEN_REPO_LOCAL

# Use mvn-jpp to build, calling the install (compile + test + install)
# and javadoc targets
mvn-jpp \
    -Dmaven.repo.local=$MAVEN_REPO_LOCAL \
    install javadoc:javadoc

%install
rm -rf $RPM_BUILD_ROOT

# JAR files
mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar]  \
       $RPM_BUILD_ROOT%{_javadir}/%{name}-%{version}.jar

# Repeat for every other jar

# Javadocs
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] \
      $RPM_BUILD_ROOT%{_javadocdir}/%{name}

# pom
# pom is always placed in %{_datadir}/maven2/poms, with the name
# being JPP[.subdirname in %{_javadir} if present]-jarname.pom
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

# create a mapping from upstream groupid/artifact id to where we install the
# artifact(s)
%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}/*
# Add any doc files here
%doc

%files javadoc
%defattr(-,root,root,-)
%{_javadocdir}/%{name}

%files manual
%defattr(-,root,root,-)
%doc [manual directory]/*

%changelog
# SNPG

For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located here.

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

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

Guideline

JAR files that require JNI shared objects MUST be installed in %{_libdir}/%{name}. The JNI shared objects themselves must also be installed 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. If the package installs a wrapper script you'll need to manually add %{_libdir}/%{name}/<jar filename> to CLASSPATH. If you are depending on a JNI-using JAR file, you'll need to add it manually -- build-classpath will not find it.

Rationale

This is less convenient, but cleaner from a packaging point-of-view, than putting the JAR file in %{_javadir}, and putting the JNI shared object in %{_libdir} to be loaded from the default library path. First, JNI shared objects are dlopen'd, and dlopen'd shared objects should not be placed directly in %{_libdir} 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 %{_javadir} causes the build-classpath script to always load it, even when running on a runtime environment of the wrong arch, meaning that the System.loadLibrary line would fail.

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

The %{_jnidir} rpm macro defines the main JNI jar repository. Like %{_javadir} it is declined in -ext and -x.y.z variants. It follows exactly the same rules as the %{_javadir}-derived tree structure, except that it hosts JAR files that use JNI.

%{_jnidir} usually expands into /usr/lib/java.

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

# make sure there are no JAR files left
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

Will this preserve the line ending as the this page says it must?

Comments

- Which version of java should stuff be built for? Probably 1.5 (for gcj) if possible? Should mention something about this. (VilleSkyttä)

- "Requires: java" should have a version in it (depending on which version of java it was built for). Possibly also depend on jre instead of java (maybe this is just cosmetic)? (VilleSkyttä)

- Drop versioned jars and install only unversioned ones? https://www.redhat.com/archives/fedora-devel-list/2008-March/msg02346.html (VilleSkyttä)

- For users attempting to introduce a new Java package, we should tell them to first check if the package exists on JPackage (JPackage.org). JPackage packages follow a large majority of the guidelines in this draft, and thus importing should be fairly easy. Additionally, having a package in sync with JPackage will prevent potential incompatibility issues with other JPackage packages. (DeepakBhole)

- My one major issue with this Guideline is the use of "canonical document" in the header for "Java Packaging". We do have other Guidelines that point to external sources for additional sources but they are targeted pieces (For instance, make sure .desktop files provided by the package follow the freedesktop spec [LINK to spec]). The Java Guidelines are broader and also have an overlay of information (saying that the JPackage Guidelines are the "canonical document" seems to mean "follow the JPackage Guidelines except where the Fedora Guidelines differ"). This makes it harder for a reviewer to understand what's going on in a package that they attempt to review because they need to keep flipping between two Guidelines and trying to remember where one differs from another. It would be better organization if the Java Guidelines took one of the following approaches: 1) Major concerns listed in the Fedora Guidelines. Specifics point to the relevant section of the JPackage Guidelines. For instance:

For something that differs we could note the derivation and that our Guidelines take precedence:

The alternative to this would be to have people read the entirety of the JPackage Guidelines and then point out the places that we differ. We would probably want to do that by importing the JPackage Guidelines to the wiki and annotating the few cases where we differ. Note that we would probably want to decide whether resyncing when JPackage changes a Guidelines be done automatically or if the new version had to be brought in through FPC -> FESCo approval. We would also need someone from the Java team to do that resyncing as we might otherwise be unaware of the changes.