From Fedora Project Wiki
No edit summary
Line 5: Line 5:
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.
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.


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


=== Package naming ===
 
== Package naming ==


Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines | package naming guidelines]].
Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines | package naming guidelines]].
Line 14: Line 14:
Java API documentation '''MUST''' be placed into a sub-package called <code>%{name}-javadoc</code>.
Java API documentation '''MUST''' be placed into a sub-package called <code>%{name}-javadoc</code>.


==== Release tags ====
== Release tags ==
Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines#Package_Versioning | package versioning guidelines]].
Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines#Package_Versioning | package versioning guidelines]].


=== Pre-built dependencies ===
== Pre-built dependencies ==
Packages '''MUST''' follow the standard Fedora [[Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries | dependency bundling guidelines]].
Packages '''MUST''' follow the standard Fedora [[Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries | dependency bundling guidelines]].


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


=== JAR file installation ===
== JAR file installation ==


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


==== Split JAR files ====
=== 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.
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 ====
=== Installation directory ===


* All architecture-independent JAR files '''MUST''' go into <code>%{_javadir}</code> or a Java-version specific directory <code>%{_javadir}-<i>*</i></code> as appropriate[http://lists.fedoraproject.org/pipermail/packaging/2010-January/006792.html]. Packages '''CAN''' place JAR files into subdirectories.
* All architecture-independent JAR files '''MUST''' go into <code>%{_javadir}</code> or a Java-version specific directory <code>%{_javadir}-<i>*</i></code> as appropriate[http://lists.fedoraproject.org/pipermail/packaging/2010-January/006792.html]. Packages '''CAN''' place JAR files into subdirectories.
Line 36: Line 36:
* For installation of architecture dependent JAR files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]]
* For installation of architecture dependent JAR files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]]


==== Filenames ====
=== Filenames ===


* If the package provides a '''single''' JAR file installed filename '''SHOULD''' be <code>%{name}.jar</code>.
* If the package provides a '''single''' JAR file installed filename '''SHOULD''' be <code>%{name}.jar</code>.
Line 46: Line 46:
{{admon/note|Note|Here %{name} refers either to package name, or name of subpackage where the jar is installed.}}
{{admon/note|Note|Here %{name} refers either to package name, or name of subpackage where the jar is installed.}}


=== BuildRequires and Requires ===
== BuildRequires and Requires ==
Java packages '''MUST''' BuildRequire their respective build system:
Java packages '''MUST''' BuildRequire their respective build system:
* <code>BuildRequires: maven-local</code> for packages built with Maven
* <code>BuildRequires: maven-local</code> for packages built with Maven
Line 60: Line 60:
* <code>java</code> or <code>java >= 1:minimal_required_version</code>
* <code>java</code> or <code>java >= 1:minimal_required_version</code>


=== Javadoc installation ===
== Javadoc installation ==


* Java API documentation uses a system known as Javadoc.  All javadocs '''MUST''' be created and installed into a directory of <code>%{_javadocdir}/%{name}</code>.  
* Java API documentation uses a system known as Javadoc.  All javadocs '''MUST''' be created and installed into a directory of <code>%{_javadocdir}/%{name}</code>.  
Line 66: Line 66:
* The javadoc subpackage '''MUST''' be declared <code>noarch</code> even if main package is architecture specific.
* The javadoc subpackage '''MUST''' be declared <code>noarch</code> even if main package is architecture specific.


=== No class-path in MANIFEST.MF ===
== No class-path in MANIFEST.MF ==
* JAR files '''MUST NOT''' include <code>classh-path</code> entry inside META-INF/MANIFEST.MF
* JAR files '''MUST NOT''' include <code>classh-path</code> entry inside META-INF/MANIFEST.MF


=== CLASSPATH modification ===
== CLASSPATH modification ==
When package needs to have additional dependencies in CLASSPATH packager '''SHOULD''' use build-classpath or build-jar-repository commands to modify CLASSPATH instead of manually specifying path to JAR files of dependencies.
When package needs to have additional dependencies in CLASSPATH packager '''SHOULD''' use build-classpath or build-jar-repository commands to modify CLASSPATH instead of manually specifying path to JAR files of dependencies.


=== Maven pom.xml files ===
== 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 in one of following ways:
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 in one of following ways:


Line 80: Line 80:
{{admon/note|Additional documentation|Usage of %add_maven_depmap macro is documented in detail in [https://fedorahosted.org/released/javapackages/doc/#_add_maven_depmap_macro Java Packaging HOWTO].}}
{{admon/note|Additional documentation|Usage of %add_maven_depmap macro is documented in detail in [https://fedorahosted.org/released/javapackages/doc/#_add_maven_depmap_macro Java Packaging HOWTO].}}


=== Wrapper Scripts ===
== Wrapper Scripts ==
Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in <code>%{_bindir}</code>.   
Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in <code>%{_bindir}</code>.   


Line 93: Line 93:
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.  
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.  


=== Compatibility packages ===
== 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:
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:



Revision as of 14:32, 4 November 2013

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


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.


Package naming

Packages MUST follow the standard Fedora package naming guidelines.

Java API documentation MUST be placed into a sub-package called %{name}-javadoc.

Release tags

Packages MUST follow the standard Fedora package versioning guidelines.

Pre-built dependencies

Packages MUST follow the standard Fedora dependency bundling guidelines.

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 a Java-version specific directory %{_javadir}-* as appropriate[1]. Packages CAN place JAR files into subdirectories.

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


Note.png
Note
Here %{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
  • BuildRequires: gradle for packages built with gradle

Java binary packages MUST have transitive Requires (generated by RPM or manual) on:

  • java-headless or java-headless >= 1:minimal_required_version
  • jpackage-utils

If Java package needs sound or graphical server connection it MUST have non-transitive 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

CLASSPATH modification

When package needs to have additional dependencies in CLASSPATH packager SHOULD use build-classpath or build-jar-repository commands to modify CLASSPATH instead of manually specifying path to JAR files of dependencies.

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 in one of following ways:

  • By using %mvn_build and %mvn_install macros when building with Maven
  • By using %add_maven_depmap macros when building with Ant or other buildsystems
Note.png
Additional documentation
Usage of %add_maven_depmap macro is documented in detail in Java Packaging HOWTO.

Wrapper Scripts

Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in %{_bindir}.

The jpackage-utils package contains a convenience %jpackage_script macro that can be used to create scripts that work for the majority of packages. See its definition and documentation in /etc/rpm/macros.jpackage. 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 true 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 ":"). build-classpath is run on every part of 4th argument to create full classpaths.

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 are named in the same way as original except addition of version to package name,
  • Any JAR or POM files MUST be versioned.
Note.png
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.

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[2] with chosen packages that provide implementations:

  • javax.activation - JDK
  • javax.annotation - JDK
  • javax.el - tomcat-el-2.2-api
  • javax.enterprise.inject - cdi-api
  • javax.inject - atinject
  • javax.jws - JDK
  • javax.mail - javamail
  • javax.management - JDK
  • javax.management.remote - JDK
  • javax.persistence - geronimo-jpa
  • javax.security.auth.message - geronimo-jaspic-spec
  • javax.servlet - tomcat-servlet-3.0-api
  • javax.servlet.jsp - glassfish-jsp/glassfish-jsp-api
  • javax.servlet.jsp.jstl - jakarta-taglibs-standard
  • javax.transaction - JDK
  • javax.ws.rs - jsr-311
  • javax.wsdl - wsdl4j
  • javax.xml - JDK
  • javax.xml.bind - JDK
  • javax.xml.rpc - axis
  • javax.xml.soap - JDK
  • javax.xml.stream - JDK
  • javax.xml.ws - JDK

Packages providing APIs

In addition to following generic guidelines they MUST:

  • Add Provides: javax.XXX from the EE API list
  • Add directory %{_javadir}/javax.XXX that will contain symlinks to all implementation jar files and their dependencies

At one time there CAN BE multiple API implementations but there MUST be at most one package having specific javax.XXX virtual provide.

Packages using APIs

Packages that need to use EE API SHOULD use:

  • Requires: javax.XXX from the EE API list
  • build-classpath javax.XXX or equivalent instead of relying on package-specific jar name.


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.

Stop (medium size).png Note that GCJ packages contain .sos in %{_libdir}/gcj/%{name} but they are not JNI .sos.

Guideline

  • JNI packages MUST follow guidelines of ordinary Java packages with exceptions listed here
  • JAR files using JNI or containing JNI shared objects themselves MUST be placed in %{_jnidir} and CAN BE symlinked to %{_libdir}/%{name}.
  • JNI shared objects MUST be placed in %{_libdir}/%{name}
Note.png
Note
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.
Note.png
Macro expansions
%{_jnidir} usually expands into %{_prefix}/lib/java. %{_prefix}/lib64/java will cease its existence and will be decomissioned