Line 62: | Line 62: | ||
<code>build-classpath</code> is a script that can be used to generate classpaths from generic names of JAR files. Example: | <code>build-classpath</code> is a script that can be used to generate classpaths from generic names of JAR files. Example: | ||
<pre>export CLASSPATH=$(build-classpath commons-logging commons-net) | <pre>export CLASSPATH=$(build-classpath commons-logging commons-net xbean/xbean-reflect) | ||
</pre> | </pre> | ||
Revision as of 15:07, 15 October 2010
These guidelines are laid out in order of relevance to packaging.
Introduction
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.
TODO: Find the proper jpackage link and fix it.
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 Packaging/NamingGuidelines#Package_Version .
Jar file naming
- If a package provides a single JAR file it must have the same name as the package itself.
ex. apache-commons-io.jar
- 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 apache-commons-io
, common name is commons-io
.
commons-io.jar -> apache-commons-io.jar
- 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
- If the number of provided JAR files exceeds two, you must place them into a sub-directory.
- 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}/%{name}-%{version}
. Unversioned symlink should be created too.
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 xbean/xbean-reflect)
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 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
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.
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) BuildRequires: jpackage-utils BuildRequires: java-devel BuildRequires: ant Requires: jpackage-utils Requires: java %description %package javadoc Summary: Javadocs for %{name} Group: Documentation Requires: %{name} = %{version}-%{release} Requires: jpackage-utils %description javadoc This package contains the API documentation 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 mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}-%{version} cp -rp [javadoc directory] \ $RPM_BUILD_ROOT%{_javadocdir}/%{name}-%{version} ln -s %{name}-%{version} $RPM_BUILD_ROOT%{_javadocdir}/%{name} %clean rm -rf $RPM_BUILD_ROOT %files %defattr(-,root,root,-) %{_javadir}/* %doc %files javadoc %defattr(-,root,root,-) %{_javadocdir}/%{name} %{_javadocdir}/%{name}-%{version} %changelog
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) BuildRequires: jpackage-utils BuildRequires: java-devel BuildRequires: maven2 BuildRequires: maven-compiler-plugin BuildRequires: maven-install-plugin BuildRequires: maven-jar-plugin BuildRequires: maven-javadoc-plugin BuildRequires: maven-release-plugin BuildRequires: maven-resources-plugin BuildRequires: maven-surefire-plugin Requires: jpackage-utils Requires(post): jpackage-utils Requires(postun): jpackage-utils Requires: java %description %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}. %prep %setup -q %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 mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}-%{version} cp -rp [javadoc directory] \ $RPM_BUILD_ROOT%{_javadocdir}/%{name}-%{version} ln -s %{name}-%{version} $RPM_BUILD_ROOT%{_javadocdir}/%{name} install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir} install -pm 644 [path to pom] \ $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom %add_to_maven_depmap project_group_id project_artifact_id %{version} JPP %{name} %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} %{_javadocdir}/%{name}-%{version} %changelog
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
.so
s 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):
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?