User:Akurtakov/JavaPackagingDraftUpdate

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

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  (source file)   (Java bytecode)   (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  binary with a list of JAR files specifying the classpath like so:

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.

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

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 and the filename provided by the build is  or   then filename   MUST be used.
 * If the package provides a single JAR and the filename provided by the build is neither  nor   then this file MUST be installed as   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.

Installation directory

 * All JAR files MUST go into  or a Java-version specific directory   as appropriate.


 * If the number of provided JAR files exceeds two, you MUST place them into a sub-directory named.

Javadoc installation

 * Java API documentation uses a system known as javadoc. All javadocs MUST be created and installed into a directory of.
 * Directory or symlink  SHOULD NOT exist.
 * The javadoc subpackage MUST be declared  even if main package is architecture specific.

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
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
is similar to  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
is a build tool used by many Java packages. Packages built using  ship with   files which contain build targets similar to. Packages built using  must:

BuildRequires: ant ... %build ... ant

maven2
In Fedora 14 and older (including EPEL), the package is called. Packages built using  ship with   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 install -d -m 755 $RPM_BUILD_ROOT%{_javadir} install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir} install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom %add_to_maven_depmap [groupId] [artifactId] %{version} JPP[/optional_subDir] [jarName]
 * 1) artifactId and jarName are usually %{name} for single module projects

... %post %update_maven_depmap

%postun %update_maven_depmap ...

maven3
In Fedora 15 and newer, maven 3 is used and the package is called. Packages built using  ship with   files. They SHOULD contain common sections such as the following:

... %build mvn-rpmbuild install javadoc:aggregate ...

%install install -d -m 755 $RPM_BUILD_ROOT%{_javadir} install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir} install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom install -pm 644 target/%{name}-%{version}.jar $RPM_BUILD_ROOT/%{_javadir}/%{name}.jar

%add_maven_depmap JPP-%{name}.pom %{name}.jar ... %files %{_mavendepmapfragdir}/%{name} %{_mavenpomdir}/JPP-%{name}.pom
 * 1) second argument is optional (parent poms have no jars)

Useful mvn-rpmbuild customisations:
 * -Dmaven.local.depmap.file=FILE.xml - xml file that defines alternative dependency maps
 * -Dmaven.local.debug=true makes custom resolver output more debugging information

add_maven_depmap macro
Maven identifies jar files by a set of strings: groupId, artifactId and version (mostly). To let mvn-rpmbuild know what groupId:artifactId corresponds to which pom or jar file we use %add_maven_depmap macro. In its simplest form add_maven_depmap looks like this: %add_maven_depmap JPP-%{name}.pom This will read pom file in question and provide mapping between groupId,artifactId inside pom file and pom file placed into %{_mavenpomdir}. Given pom file already has to exist inside %{_mavenpomdir}. Mapping is stored inside %{_mavendepmapfragdir}/%{name} file. All mappings (fragments) are read by mvn-rpmbuild during startup. This form should only be used for pom-only artifacts (i.e. parent poms).

%add_maven_depmap JPP-%{name}.pom %{name}.jar In addition to creating mapping, this will also ensure that jar and pom files are named correctly and placed in correct subdirectories.

%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang" This form also adds additional mappings for given pom/jar file. I.e. if pom file stated it contains groupId commons-lang, artifactId commons-lang, by using this form we also added mapping between groupId org.apache.commons and jar/pom files.

%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX" This form stores dependency mapping inside %{_mavendepmapfragdir}/%{name}-XXX instead of standard location. This is useful for packages with multiple subpackages where each has its own jar files.

Wrapper Scripts
Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in.

The jpackage-utils package contains a convenience  macro that can be used to create scripts that work for the majority of packages. See its definition and documentation in. 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  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 ":"). 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.

Please refer to Packaging/GCJGuidelines for GCJ-specific guidelines.

-devel packages
packages don't really make sense for Java packages. Header files do not exist for Java packages.

Maven pom.xml files and depmaps
If upstream project is shipping Maven pom.xml files, these MUST be installed with the corresponding %add_maven_depmap calls.

If upstream project does not ship pom.xml file [official maven repo] should be checked and if there are pom.xml files they SHOULD be installed.

ant
Name:          # see normal package guidelines Version:       # see normal package guidelines Release:       1%{?dist} Summary:       # see normal package guidelines

Group:         # see normal package guidelines License:       # see normal package guidelines URL:           # see normal package guidelines Source0:       # see normal package guidelines BuildArch:     noarch

BuildRequires: jpackage-utils

BuildRequires: java-devel

BuildRequires: ant

Requires:      jpackage-utils

Requires:      java

%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

find -name '*.class' -exec rm -f '{}' \; find -name '*.jar' -exec rm -f '{}' \;

%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}/* %doc

%files javadoc %{_javadocdir}/%{name}

%changelog

maven 2
Name:          # see normal package guidelines Version:       # see normal package guidelines Release:       1%{?dist} Summary:       # see normal package guidelines

Group:         # see normal package guidelines License:       # see normal package guidelines URL:           # see normal package guidelines Source0:       # see normal package guidelines

BuildArch:     noarch

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

export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository mkdir -p $MAVEN_REPO_LOCAL

mvn-jpp -Dmaven.repo.local=$MAVEN_REPO_LOCAL \ install javadoc:javadoc # or javadoc:aggregate

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

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}

%post %update_maven_depmap

%postun %update_maven_depmap

%files %{_mavenpomdir}/* %{_mavendepmapfragdir}/* %{_javadir}/* %doc

%files javadoc %{_javadocdir}/%{name}

%changelog

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

maven 3
Name:          # see normal package guidelines Version:       # see normal package guidelines Release:       1%{?dist} Summary:       # see normal package guidelines

Group:         # see normal package guidelines License:       # see normal package guidelines URL:           # see normal package guidelines Source0:       # see normal package guidelines

BuildArch:     noarch

BuildRequires: jpackage-utils

BuildRequires: java-devel

BuildRequires: maven

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

%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-rpmbuild install javadoc:aggregate

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

install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir} install -pm 644 [path to pom] \ $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom

%add_maven_depmap JPP-%{name}.pom %{name}.jar

%files %{_mavenpomdir}/JPP-%{name}.pom %{_mavendepmapfragdir}/%{name} %{_javadir}/%{name}.jar %doc

%files javadoc %{_javadocdir}/%{name}

%changelog

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 s in   but they are not JNI .sos.

Guideline
JAR files that require JNI shared objects MUST be installed in. The JNI shared objects themselves must also be installed in. If the JNI-using code calls  you'll have to patch it to use , passing it the full path to the dynamic shared object. If the package installs a wrapper script you'll need to manually add  to. If you are depending on a JNI-using JAR file, you'll need to add it manually --  will not find it.

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

The plan is to eventually eliminate patching of the  line and wrapper script by making   multilib aware. This involves the following changes: creating   and   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  's runtime scripts to search  ; modifying IcedTea to look for JNI shared objects in.

The  rpm macro defines the main JNI jar repository. Like  it is declined in   and   variants. It follows exactly the same rules as the -derived tree structure, except that it hosts JAR files that use JNI.

usually expands into.

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. 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  (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  scriptlets creating   symlinks. These MUST not appear in Fedora Java packages and are actively being removed at JPackage.

class-path-in-manifest
Use  to remove   elements in   (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