User:Abo/JavaPackagingDraftUpdateWithChanges

'''This page is not up to date. The latest draft is at User:Abo/JavaPackagingDraftUpdate.'''

(This is a draft update to Packaging:Java.)

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

Background

 * '''Old text:
 * 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.

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. Since 2008 this has enabled Fedora to ship a package under the OpenJDK name.

The Basics

 * '''Old text:
 * 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:

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.

Package naming
Packages MUST follow the standard Fedora Packaging/NamingGuidelines.

Java API documentation MUST be placed into a sub-package called.

Release tags

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

Packages may declare release tags as defined by Packaging/JPackagePolicy. That document should eventually be folded into this one.

JAR file installation

 * '''Old text:
 * === Jar file naming ===
 * If a package provides a single JAR file it must have the same name as the package itself.
 * ex.
 * 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 , common name is.
 * 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 .  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  }.
 * 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 .  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  }.
 * === Directory structure ===
 * All JAR files MUST go into .  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  }.
 * Java API documentation uses a system known as javadoc. All javadocs MUST be installed into  }.
 * Java API documentation uses a system known as javadoc. All javadocs MUST be installed into  }.

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  then this name MUST be used.

If the package provides a single JAR and the filename provided by the build is  then this name MUST be used and a symbolic link   pointing to this file MUST be installed.

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.

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 installed into a subdirectory of. The name of the subdirectory SHOULD be either  or   with a symlink   pointing to it.

The javadoc subpackage MAY be declared.

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)

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

maven
is a tool used by many Java packages. In Fedora, 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 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

 * '''Old text:
 * Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in }.  These can be as simple as this example:

Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in. These can be as simple as this example:

. /usr/share/java-utils/java-functions
 * 1) !/bin/bash

MAIN_CLASS=MyCoolApp

set_classpath "mycoolapp"

run "$@"

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

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 (Changed from "Development Documentation") Requires:      %{name} = %{version}-%{release} Requires:      jpackage-utils BuildArch:     noarch (added)

%description javadoc This package contains the API documentation for %{name}.

%package manual Summary:       Manual for %{name} Group:         Documentation (Changed from "Development Documentation") Requires:      jpackage-utils Requires:      %{name} = %{version}-%{release}

%description manual The manual 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 ln -s %{name}-%{version}.jar \ (added) $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

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

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

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

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

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 BuildArch:     noarch (added)

%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

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 ln -s %{name}-%{version}.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%{_datadir}/maven2/poms install -pm 644 [path to pom] \ $RPM_BUILD_ROOT%{_datadir}/maven2/poms/JPP-%{name}.pom

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

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

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

%changelog

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

Applicability

 * '''Old text:
 * 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.
 * Note that GCJ packages contain s in  } but they are not JNI .sos.

Java programs that wish to make calls into native libraries do so via the Java Native Interface (JNI) by calling the Java method  or   to load a   file into the Java runtime environment. If a Java package contains a .so file then it is most likely either a JNI .so file (in which case the JNI guidelines apply) or a GCJ .so file (see below).

Guideline

 * '''Old text:
 * 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.

JAR files that require JNI shared objects MUST be installed in, with the usual filenames and optionally symlinks as provided by the build. The JNI shared objects themselves MUST also be installed in. If the JNI-using code calls  it must be patched to use , passing it the full path to the dynamic shared object.

If the package installs a wrapper script then the script will need to add  to. Likewise, the  script will not find JAR files that uses JNI, so they need to be added manually.

Rationale

 * '''Old text:
 * 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.

A JNI-using JAR file that was placed in  would be loaded even if the Java runtime environment's architecture didn't match the architecture of the corresponding JNI shared object, in which case the   call would fail.

The shared object is 'd specifically by the corresponding Java archive and is not meant to be loaded any other way. Thus is should not be packaged among the shared libraries in.

Thus, though less convenient, it's cleaner from a packaging point-of-view to put the JAR and shared object in an arch- and library-specific directory.


 * '''Old text:
 * 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.
 * } usually expands into.
 * } usually expands into.

The plan is to eventually eliminate patching of the  line and wrapper script by making   multilib aware. This involves the following changes: creating   (AKA  ) 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.

Pre-built JAR files / Other bundled software

 * '''Old text:
 * 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):

Many Java projects re-ship their dependencies in their own releases. This is unacceptable in Fedora. Any prebuilt binaries (.jar and .class files) MUST either be removed from the source tree in  or a modified source archive with the offending files remove be provided, in accordance with Packaging:Guidelines and Packaging:SourceURL. There may arise rare cases that an upstream project is distributing JAR files that are actually not re-distributable by Fedora. In this situation, a modified source archive MUST be created and used as described above.

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 use the JAR files provided by dependencies.

It is a good idea to have something similar to the following at the end of :


 * '''Old text:

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


 * '''New text:

if find -name '*.class' -o -name '*.jar' | grep. >&2; then echo >&2 "Prebuilt binaries found in the sources. See https://fedoraproject.org/wiki/Packaging:Java#Pre-built_JAR_files_.2F_Other_bundled_software for instructions." 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


 * '''Removed text:
 * -Will this preserve the line ending as the this page says it must?