Packaging:Java: Difference between revisions

Revision as of 18:37, 14 June 2017

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

For installation of architecture dependent JAR files, see Packaging JAR files that use JNI.

Filenames

If the package provides a single JAR file installed filename SHOULD be %{name}.jar.
If the package provides multiple JAR files, they SHOULD be installed in a %{name} subdirectory
Versioned JAR files (*-%{version}.jar) MUST NOT be installed unless the package is a compatibility package
Packages MAY provide alternative filenames as long as they do not conflict with other packages

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

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

java-headless or java-headless >= 1:minimal_required_version
javapackages-tools

If java-headless requirement is insufficient package MUST have Requires:

java or java >= 1:minimal_required_version

Javadoc installation

javadoc documentation MAY be generated
If javadoc documentation is generated it MUST be installed into a directory of %{_javadocdir}/%{name} as part of javadoc subpackage
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 class-path entry inside META-INF/MANIFEST.MF

Hardcoded paths

Packages MUST NOT hardcode paths to JAR files they use. When package needs to reference a JAR file, packager SHOULD use one of tools designed to locating JAR files in the system.

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 by using the %mvn_install macro.

Additional documentation
Additional artifact installation documentation is available forAnt projects and Maven projects.

If upstream project does not ship Maven pom.xml file, official maven repository should be searched and if there are pom.xml files they SHOULD be installed.

If modifications to Maven pom.xml files are needed %pom_* family of macros SHOULD be used

Additional documentation
Usage of %pom_* macros 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}. Packages SHOULD use %jpackage_script to create these wrapper scripts.

Additional documentation
Usage of %jpackage_script macro is documented in Java Packaging HOWTO.

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

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

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 MAY be symlinked to %{_libdir}/%{name}.
JNI shared objects MUST be placed in %{_libdir}/%{name}

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. You can look at the example.

Macro expansions
%{_jnidir} expands into %{_prefix}/lib/java, even on 64-bit systems. Java packages using JNI do not support multiarch installation.

@@ Line 1: / Line 1: @@
-These guidelines are laid out in order of relevance to packaging.
+{{DISPLAYTITLE:Fedora Packaging Guidelines for Java}}
+<div style="float: right; margin-left: 0.5em" class="toclimit-2">__TOC__</div>
+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://fedora-java.github.io/howto/latest/ 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.
-== 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 [https://fedora-java.github.io/howto/latest/ 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 [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.
@@ Line 10: / Line 9: @@
 == Package naming ==
-Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines | package naming guidelines]].
+Packages MUST follow the standard Fedora [[Packaging/NamingGuidelines | package naming guidelines]].
-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 ==
-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 ==
-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 ==
@@ Line 28: / Line 27: @@
 === 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 ===
-* All architecture-independent JAR files '''MUST''' go into <code>%{_javadir}</code> or its subdirectory.
+* All architecture-independent JAR files MUST go into <code>%{_javadir}</code> or its subdirectory.
 * For installation of architecture dependent JAR files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]].
@@ Line 38: / Line 37: @@
 === 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>.
-* If the package provides '''multiple''' JAR file, files '''SHOULD''' be installed in a <code>%{name}</code> subdirectory
+* If the package provides '''multiple''' JAR files, they SHOULD be installed in a <code>%{name}</code> subdirectory
-* Versioned JAR files (<code>*-%{version}.jar</code>) '''MUST NOT''' be installed unless the package is a compatibility package
+* Versioned JAR files (<code>*-%{version}.jar</code>) 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
+* Packages MAY provide alternative filenames as long as they do not conflict with other packages
@@ Line 47: / Line 46: @@
 == 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: ant</code> for packages built with ant
 * <code>BuildRequires: java-devel</code> for packages built with javac
-Java binary packages or their dependencies '''MUST''' have Requires (generated by RPM or manual) on:
+Java binary packages or their dependencies MUST have Requires (generated by RPM or manual) on:
 * <code>java-headless</code> or <code>java-headless >= 1:minimal_required_version</code>
 * <code>javapackages-tools</code>
-If java-headless requirement is insufficient package '''MUST''' have Requires:
+If java-headless requirement is insufficient package MUST have Requires:
 * <code>java</code> or <code>java >= 1:minimal_required_version</code>
 == Javadoc installation ==
-* javadoc documentation '''CAN''' be generated
+* javadoc documentation MAY be generated
-* If javadoc documentation is generated it '''MUST''' be installed into a directory of <code>%{_javadocdir}/%{name}</code> as part of javadoc subpackage
+* If javadoc documentation is generated it MUST be installed into a directory of <code>%{_javadocdir}/%{name}</code> as part of javadoc subpackage
-* Directory or symlink <code>%{_javadocdir}/%{name}-%{version}</code> '''SHOULD NOT''' exist.
+* Directory or symlink <code>%{_javadocdir}/%{name}-%{version}</code> SHOULD NOT exist.
-* 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 ==
-* JAR files '''MUST NOT''' include <code>class-path</code> entry inside META-INF/MANIFEST.MF
+* JAR files MUST NOT include <code>class-path</code> entry inside META-INF/MANIFEST.MF
 == Hardcoded paths ==
-Packages '''MUST NOT''' hardcode paths to JAR files they use.  When package needs to reference a JAR file, packager '''SHOULD''' use one of tools designed to locating JAR files in the system.
+Packages MUST NOT hardcode paths to JAR files they use.  When package needs to reference a JAR file, packager SHOULD use one of tools designed to locating JAR files in the system.
 == 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 by using the <code>%mvn_install</code> macro.
+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 by using the <code>%mvn_install</code> macro.
 {{admon/note|Additional documentation|Additional artifact installation documentation is available for[https://fedora-java.github.io/howto/latest/#ant Ant projects] and [https://fedora-java.github.io/howto/latest/#maven Maven projects].}}
-If upstream project does not ship Maven <code>pom.xml</code> file, official [http://mvnrepository.com/ maven repository] should be searched and if there are <code>pom.xml</code> files they '''SHOULD''' be installed.
+If upstream project does not ship Maven <code>pom.xml</code> file, official [http://mvnrepository.com/ maven repository] should be searched and if there are <code>pom.xml</code> files they SHOULD be installed.
-If modifications to Maven pom.xml files are needed <code>%pom_*</code> family of macros '''SHOULD''' be used
+If modifications to Maven pom.xml files are needed <code>%pom_*</code> family of macros SHOULD be used
 {{admon/note|Additional documentation|Usage of %pom_* macros is documented in detail in [https://fedora-java.github.io/howto/latest/#helper_macros Java Packaging HOWTO].}}
 == Wrapper Scripts ==
-Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in <code>%{_bindir}</code>. Packages '''SHOULD''' use <code>%jpackage_script</code> to create these wrapper scripts.
+Applications wishing to provide a convenient method of execution SHOULD provide a wrapper script in <code>%{_bindir}</code>. Packages SHOULD use <code>%jpackage_script</code> to create these wrapper scripts.
 {{admon/note|Additional documentation|Usage of %jpackage_script macro is documented in [https://fedora-java.github.io/howto/latest#_generating_application_shell_scripts Java Packaging HOWTO].}}
@@ Line 92: / Line 91: @@
 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 '''MUST''' be named in the same way as original except addition of version to package name,
+* Compatibility packages MUST be named in the same way as original except addition of version to package name,
-* Any JAR and POM files '''MUST''' be versioned.
+* Any JAR and POM files MUST be versioned.
 {{admon/note|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.}}
@@ Line 107: / Line 106: @@
 === Guideline ===
-* JNI packages '''MUST''' follow guidelines of ordinary Java packages with exceptions listed here
+* 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 <code>%{_jnidir}</code> and '''CAN BE''' symlinked to <code>%{_libdir}/%{name}</code>.
+* JAR files using JNI or containing JNI shared objects themselves MUST be placed in <code>%{_jnidir}</code> and MAY be symlinked to <code>%{_libdir}/%{name}</code>.
-* JNI shared objects '''MUST''' be placed in <code>%{_libdir}/%{name}</code>
+* JNI shared objects MUST be placed in <code>%{_libdir}/%{name}</code>
 {{admon/note|Note|If the JNI-using code calls <code>System.loadLibrary</code> you'll have to patch it to use <code>System.load</code>, passing it the full path to the dynamic shared object. You can look at the [[JavaSystemLoadExample|example]].}}

Search