|
|
(124 intermediate revisions by 5 users not shown) |
Line 1: |
Line 1: |
| These guidelines are laid out in order of relevance to packaging. | | These guidelines are laid out in order of relevance to packaging. |
| | |
|
| |
|
| == Introduction == | | == 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://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. |
|
| |
|
| === The Basics ===
| | 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. |
| 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 <code>.java</code> (source file) <code>.class</code> (Java bytecode) <code>.jar</code> (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 <code>java</code> binary with a list of JAR files specifying the classpath like so:
| |
| | |
| <code>java [-cp <jar1:jar2:jar3>] <main-class> [<args>] </code>
| |
| | |
| == Java Packaging ==
| |
| The [http://www.jpackage.org 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: [http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?revision=HEAD&root=jpackage 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 ===
| | == Package naming == |
|
| |
|
| Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines]]. | | 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 ====
| | == Release tags == |
| Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines#Package_Version | Package versioning guidelines]]. | | Packages '''MUST''' follow the standard Fedora [[Packaging/NamingGuidelines#Package_Versioning | package versioning guidelines]]. |
|
| |
|
| === JAR file installation === | | == Pre-built dependencies == |
| | Packages '''MUST''' follow the standard Fedora [[Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries | dependency bundling guidelines]]. |
|
| |
|
| The following applies to all JAR files except [[#JNI|JNI-using JAR files]], [[#GCJ|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).
| | 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. |
|
| |
|
| ==== Split JAR files ==== | | == JAR file installation == |
|
| |
|
| If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging '''should''' be preferred.
| | 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). |
|
| |
|
| ==== Filenames ==== | | === Split JAR files === |
|
| |
|
| * If the package provides a '''single''' JAR and the filename provided by the build is <code>%{name}.jar</code> or <code>%{name}-%{version}.jar</code> then filename <code>%{name}.jar</code> '''MUST''' be used.
| | If a project offers the choice of packaging it as a single monolithic JAR or several ones, the split packaging '''SHOULD''' be preferred. |
| * If the package provides a '''single''' JAR and the filename provided by the build is neither <code>%{name}-%{version}.jar</code> nor <code>%{name}.jar</code> then this file '''MUST''' be installed as <code>%{name}.jar</code> 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.
| |
|
| |
|
| {{admon/note|Note|Here %{name} refers either to package name, or name of subpackage where the jar is installed.}}
| | === Installation directory === |
|
| |
|
| ==== 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 a Java-version specific directory <code>%{_javadir}-<i>*</i></code> as appropriate[http://lists.fedoraproject.org/pipermail/packaging/2010-January/006792.html]. | | * For installation of architecture dependent JAR files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]]. |
|
| |
|
| * If the number of provided JAR files exceeds '''two''', you '''SHOULD''' place them into a sub-directory named <code>%{name}</code>.
| | === Filenames === |
|
| |
|
| * For installation of architecture dependent jar files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]] | | * 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 |
| | * 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 |
|
| |
|
| === 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
| | {{admon/note|Note|Here %{name} refers either to package name, or name of subpackage where the jar is installed.}} |
| * Jar files '''MUST NOT''' be unversioned
| |
| * Base name of versioned jar files '''MUST''' be the same as original package jars and they '''MUST''' be placed alongside original jar files
| |
| * Package '''SHOULD NOT''' provide maven fragments or pom files
| |
|
| |
|
| {{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 from main package and will return versioned jar if it matches the version asked for in the pom file.}}
| | == BuildRequires and Requires == |
| | 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 |
|
| |
|
| ==== Compatibility package example ==== | | 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>jpackage-utils</code> |
|
| |
|
| * Original package: plexus-container-2.0.0
| | If java-headless requirement is insufficient package '''MUST''' have Requires: |
| <pre> | | * <code>java</code> or <code>java >= 1:minimal_required_version</code> |
| Name: plexus-container
| |
| Version: 2.0.0
| |
| ...
| |
|
| |
|
| %files
| | == Javadoc installation == |
| ...
| |
| %{_javadir}/plexus/container.jar
| |
| %{_mavenpomdir}/JPP.plexus-container.pom
| |
| %{_mavendepmapfragdir}/%{name}
| |
| ...
| |
| </pre>
| |
|
| |
|
| * Compat package: plexus-container1-1.5.0
| | * Java API documentation uses a system known as Javadoc. All javadocs '''MUST''' be created and installed into a directory of <code>%{_javadocdir}/%{name}</code>. |
| <pre>
| |
| Name: plexus-container15
| |
| Version: 1.5.0
| |
| ...
| |
| | |
| %files
| |
| ...
| |
| %{_javadir}/plexus/container-1.5.0.jar
| |
| ...
| |
| </pre>
| |
| | |
| === 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>. | |
| * 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. |
|
| |
|
| === BuildRequires and Requires === | | == No class-path in MANIFEST.MF == |
| At a minimum, Java packages '''MUST''':
| | * JAR files '''MUST NOT''' include <code>classh-path</code> entry inside META-INF/MANIFEST.MF |
|
| |
|
| <pre>BuildRequires: java-devel [>= specific_version]
| | == Hardcoded paths == |
| BuildRequires: jpackage-utils
| | 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. |
|
| |
|
| Requires: java [>= specific_version]
| | == Maven pom.xml files == |
| Requires: jpackage-utils</pre>
| | 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 either <code>%mvn_install</code> or <code>%add_maven_depmap</code> macros. |
|
| |
|
| For historical reasons, when specifying versions 1.6.0 or greater, an epoch of 1 must be included. Example:
| | {{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].}} |
|
| |
|
| <pre>Requires: java >= 1:1.6.0
| |
| </pre>
| |
|
| |
|
| === build-classpath ===
| | 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. |
| <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 xbean/xbean-reflect) | | If modifications to Maven pom.xml files are needed <code>%pom_*</code> family of macros '''SHOULD''' be used |
| </pre> | |
| {{admon/note|Additional information|You can use either jar filename or directory name relative to %{_javadir}, %{_jnidir} or %{_javajnidir} (all jar files will be included).}}
| |
|
| |
|
| === build-jar-repository ===
| | {{admon/note|Additional documentation|Usage of %pom_* macros is documented in detail in [https://fedorahosted.org/released/javapackages/doc/#helper_macros Java Packaging HOWTO].}} |
| <code>build-jar-repository</code> is similar to <code>build-classpath</code> but instead of producing a classpath entry, it creates symlinks in a given directory. Example:
| |
| <pre>$ 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
| |
| </pre>
| |
|
| |
|
| === ant === | | == Wrapper Scripts == |
| <code>ant</code> is a build tool used by many Java packages. Packages built using <code>ant</code> ship with <code>build.xml</code> files which contain build targets similar to <code>Makefiles</code>. Packages built using <code>ant</code> must: | | 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. |
|
| |
|
| <pre>BuildRequires: ant
| | {{admon/note|Additional documentation|Usage of %jpackage_script macro is documented in [https://fedorahosted.org/released/javapackages/doc/#_generating_application_shell_scripts Java Packaging HOWTO].}} |
| ... | |
| %build
| |
| ...
| |
| ant
| |
| </pre>
| |
|
| |
|
| === maven3 === | | == Compatibility packages == |
| In Fedora 15 and newer, maven 3 is used and the package is called <code>maven</code>. Packages built using <code>maven</code> ship with <code>pom.xml</code> files. They '''SHOULD''' contain common sections such as the following: | | 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: |
| | |
| <pre>
| |
| ...
| |
| %build
| |
| mvn-rpmbuild package 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
| |
| | |
| # second argument is optional (parent poms have no jars)
| |
| %add_maven_depmap JPP-%{name}.pom %{name}.jar
| |
| ...
| |
| %files
| |
| %{_mavendepmapfragdir}/%{name}
| |
| %{_mavenpomdir}/JPP-%{name}.pom
| |
| </pre>
| |
| | |
| 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
| |
| | |
| {{admon/important|Important|For detailed instructions on use of add_maven_depmap macro see [[#depmap_macro|macro documentation]]}}
| |
| | |
| === add_maven_depmap macro ===
| |
| {{Anchor|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 the <code>%add_maven_depmap</code> macro. <code>%add_maven_depmap</code> reads the groupId and artifactId from the pom file and creates a file in <code>%{_mavendepmapfragdir}</code> that maps groupId:artifactId pairs to jar files under <code>%{_javadir}</code>. All fragments in this directory are read by mvn-rpmbuild during startup, allowing the locally installed jar files and poms to be used as a maven repository.
| |
| | |
| Note that -- unless you use the <code>-f</code> option as shown below -- all depmap fragments for a given package are written to the same file, <code>%{_mavendepmapfragdir}/%{name}</code>. You should be sure to include this file in the <code>%files</code> section of your RPM.
| |
| | |
| For the macro to work properly, all jar files must be copied into <code>%{_javadir}</code> (see [[#JAR_file_installation|JAR file installation]]), and all pom files must be copied into <code>%{_mavenpomdir}</code> and given file names of the following form, where <code>jarname</code> is the name of the jar without the .jar suffix:
| |
| <pre>%{_mavenpomdir}/JPP[.subdirectory]-jarname.pom</pre>
| |
| Note that the subdirectory is only necessary if the jar file is put into a subdirectory of <code>%{_javadir}</code>. For example:
| |
| * For junit, the jar is <code>%{_javadir}/junit.jar</code>, so the pom would be <code>%{_mavenpomdir}/JPP-junit.pom</code>.
| |
| * For plexus-ant-factory, the jar is <code>%{_javadir}/plexus/ant-factory.jar</code>, so the pom would named <code>%{_mavenpomdir}/JPP.plexus-ant-factory.pom</code>.
| |
| If a pom is installed with no corresponding jar file -- for example, for parent poms -- the same convention should be followed:
| |
| * The Apache commons parent pom is installed in <code>%{_mavenpomdir}/JPP-commons-parent.pom</code>.
| |
| | |
| In its simplest form (a pom without a jar file), <code>%add_maven_depmap</code> looks like this:
| |
| <pre>%add_maven_depmap JPP-%{name}.pom</pre>
| |
| This will read the pom file in question and provide a mapping between the groupId and artifactId inside the pom file and the pom file placed into <code>%{_mavenpomdir}</code>.
| |
| | |
| For a pom that maps directly to a jar file, the following is the correct form:
| |
| <pre>%add_maven_depmap JPP-%{name}.pom %{name}.jar</pre>
| |
| In addition to creating the pom mapping, this will also ensure that the correct jar is associated with the groupId and artifactId from the pom.
| |
| | |
| <pre>%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang"</pre>
| |
| This form also adds additional mappings for given pom/jar file. For example, if the pom file indicates that it contains groupId commons-lang, artifactId commons-lang, this form ensures that we also add a mapping between groupId org.apache.commons and the installed jar/pom files. This is necessary in cases where the groupId or artifactId may have changed, and other packages might require different IDs than those reflected in the installed pom.
| |
| | |
| <pre>%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX"</pre>
| |
| This form stores dependency mapping inside <code>%{_mavendepmapfragdir}/%{name}-XXX</code> instead of standard location. This is useful for packages with multiple subpackages where each has its own jar files.
| |
| | |
| <pre>%add_maven_depmap JPP.%{name}-sub.pom %{name}/sub.jar</pre>
| |
| This form should be used when a package consists of multiple jar files that are installed into a subdirectory of <code>%{_javadir}</code>. Note that in this case, the pom file name includes the optional subdirectory field.
| |
| | |
| === Wrapper Scripts ===
| |
| Applications wishing to provide a convenient method of execution '''SHOULD''' provide a wrapper script in <code>%{_bindir}</code>.
| |
| | |
| The jpackage-utils package contains a convenience <code>%jpackage_script</code> macro that can be used to create scripts that work for the majority of packages. See its definition and documentation in <code>/etc/rpm/macros.jpackage</code>. 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 <code>true</code> 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.
| |
| | |
| <pre>
| |
| %install
| |
| ...
| |
| %jpackage_script com.sun.msv.driver.textui.Driver "" "" msv-msv:msv-xsdlib:relaxngDatatype:isorelax msv true
| |
| ...
| |
| </pre>
| |
| 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.
| |
| | |
| === 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 ===
| |
| <code>-devel</code> 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 [[http://repo1.maven.org/maven2/ official maven repo]] should be checked and if there are pom.xml files they '''SHOULD''' be installed.
| |
| | |
| {{admon/tip|Tip|[http://mvnrepository.com/ Mvnrepository site] can be used to ease}}
| |
| | |
| == Specfile Template ==
| |
| === ant ===
| |
| | |
| <pre>
| |
| 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
| | * 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. |
|
| |
|
| BuildRequires: java-devel
| | {{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.}} |
| | |
| 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
| |
| </pre>
| |
| | |
| | |
| | |
| === maven 3 ===
| |
| {{admon/important|Important|Only Fedora 15 and newer releases have Maven 3.}} | |
| | |
| <pre>
| |
| 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 package 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
| |
| | |
| </pre>
| |
| | |
| {{admon/important|Important|For detailed instructions on use of add_maven_depmap macro see [[#depmap_macro|macro documentation]]}}
| |
|
| |
|
| == Packaging and using EE APIs == | | == Packaging and using EE APIs == |
Line 371: |
Line 100: |
|
| |
|
| === EE API List === | | === EE API List === |
| Following is a list of EE APIs as of Java EE 6[http://docs.oracle.com/javaee/6/api/]: | | Following is a list of EE APIs as of Java EE 6[http://docs.oracle.com/javaee/6/api/] with chosen packages that provide implementations: |
| * javax.activation | | * javax.activation - JDK |
| * javax.annotation | | * javax.annotation - JDK |
| * javax.el | | * javax.el - tomcat-el-2.2-api |
| * javax.inject | | * javax.enterprise.inject - cdi-api |
| * javax.jws | | * javax.inject - atinject |
| * javax.mail | | * javax.jws - JDK |
| * javax.management | | * javax.mail - javamail |
| * javax.management.remote | | * javax.management - JDK |
| * javax.persistence | | * javax.management.remote - JDK |
| * javax.security.auth.message | | * javax.persistence - geronimo-jpa |
| * javax.servlet | | * javax.security.auth.message - geronimo-jaspic-spec |
| * javax.servlet.jsp | | * javax.servlet - tomcat-servlet-3.0-api |
| * javax.servlet.jsp.jstl | | * javax.servlet.jsp - glassfish-jsp/glassfish-jsp-api |
| * javax.transaction | | * javax.servlet.jsp.jstl - jakarta-taglibs-standard |
| * javax.ws.rs | | * javax.transaction - JDK |
| * javax.wsdl | | * javax.ws.rs - jsr-311 |
| * javax.xml | | * javax.wsdl - wsdl4j |
| * javax.xml.bind | | * javax.xml - JDK |
| * javax.xml.rpc | | * javax.xml.bind - JDK |
| * javax.xml.soap | | * javax.xml.rpc - axis |
| * javax.xml.stream | | * javax.xml.soap - JDK |
| * javax.xml.ws | | * javax.xml.stream - JDK |
| | | * javax.xml.ws - JDK |
|
| |
|
| === Packages providing APIs === | | === Packages providing APIs === |
Line 401: |
Line 130: |
| * Add directory %{_javadir}/javax.XXX that will contain symlinks to all implementation jar files and their dependencies | | * Add directory %{_javadir}/javax.XXX that will contain symlinks to all implementation jar files and their dependencies |
|
| |
|
| At one time there '''MUST''' be at most one package providing given API. | | 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 using APIs === |
Line 413: |
Line 142: |
| === Applicability === | | === 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 | | 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. |
|
| |
|
| {{Template:Warning}} Note that GCJ packages contain <code>.so</code>s in <code>%{_libdir}/gcj/%{name}</code> but they are not JNI .sos. | | {{Template:Warning}} Note that GCJ packages contain <code>.so</code>s in <code>%{_libdir}/gcj/%{name}</code> but they are not JNI .sos. |
Line 419: |
Line 148: |
| === Guideline === | | === Guideline === |
|
| |
|
| JAR files that require JNI shared objects '''MUST''' be installed in <code>%{_libdir}/%{name}</code>. The JNI shared objects themselves must also be installed in <code>%{_libdir}/%{name}</code>. 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. If the package installs a wrapper script you'll need to manually add <code>%{_libdir}/%{name}/<jar filename></code> to <code>CLASSPATH</code>. If you are depending on a JNI-using JAR file, you'll need to add it manually -- <code>build-classpath</code> will not find it. | | * 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>. |
| === Rationale ===
| | * JNI shared objects '''MUST''' be placed in <code>%{_libdir}/%{name}</code> |
| | |
| This is less convenient, but cleaner from a packaging point-of-view, than putting the JAR file in <code>%{_javadir}</code>, and putting the JNI shared object in <code>%{_libdir}</code> to be loaded from the default library path. First, JNI shared objects are <code>dlopen</code>'d, and <code>dlopen</code>'d shared objects should not be placed directly in <code>%{_libdir}</code> 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 <code>%{_javadir}</code> causes the build-classpath script to always load it, even when running on a runtime environment of the wrong arch, meaning that the <code>System.loadLibrary</code> line would fail.
| |
| | |
| The plan is to eventually eliminate patching of the <code>System.loadLibrary</code> line and wrapper script by making <code>jpackage-utils</code> multilib aware. This involves the following changes: creating <code>%{_libdir}/java</code> and <code>%{_libdir}/jni</code> 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 <code>jpackage-utils</code>'s runtime scripts to search <code>%{_libdir}/java</code>; modifying IcedTea to look for JNI shared objects in <code>%{_libdir}/jni</code>.
| |
| | |
| The <code>%{_jnidir}</code> rpm macro defines the main JNI jar repository. Like <code>%{_javadir}</code> it is declined in <code>-ext</code> and <code>-x.y.z</code> variants. It follows exactly the same rules as the <code>%{_javadir}</code>-derived tree structure, except that it hosts JAR files that use JNI.
| |
| | |
| <code>%{_jnidir}</code> usually expands into <code>/usr/lib/java</code>.
| |
| | |
| == 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 <code>Requires</code>. 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 <code>%prep</code> (courtesy David Walluck):
| |
|
| |
|
| <pre> | | {{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]].}} |
| 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
| |
| </pre> | |
|
| |
|
| === Javadoc scriptlets ===
| | {{admon/note|Macro expansions|<code>%{_jnidir}</code> expands into <code>%{_prefix}/lib/java</code>, even on 64-bit systems. Java packages using JNI do not support multiarch installation.}} |
| Older JPackage packages contained <code>%post</code> scriptlets creating <code>%ghost</code> symlinks. These '''MUST''' not appear in Fedora Java packages and are actively being removed at JPackage.
| |
|
| |
|
| === Selected rpmlint issues ===
| |
| ==== class-path-in-manifest ====
| |
| Use <code>sed</code> to remove <code>class-path</code> elements in <code>MANIFEST.MF</code> (or whatever file is being used as the JAR manifest) prior to JAR creation. Example:
| |
|
| |
|
| <pre>
| |
| sed -i '/class-path/I d' META-INF/MANIFEST.MF
| |
| </pre>
| |
|
| |
|
|
| |
|
| [[Category:Java]] | | [[Category:Java]] |
| [[Category:Packaging guidelines drafts]] | | [[Category:Packaging guidelines drafts]] |
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 its subdirectory.
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
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
jpackage-utils
If java-headless requirement is insufficient package MUST have 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
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 either %mvn_install
or %add_maven_depmap
macros.
Additional documentationUsage of %add_maven_depmap macro is documented in detail in
Java Packaging HOWTO.
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
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.
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 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[1] 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.
Note that GCJ packages contain .so
s 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}
NoteIf 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.