Packaging:Java

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(2 intermediate revisions by one user 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.
  
Line 20: Line 23:
  
 
==== 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_Version | Package versioning guidelines]].
  
 
=== JAR file installation ===
 
=== JAR file installation ===
Line 36: Line 39:
 
* If the package provides more than '''one''' JAR file, the filenames assigned by the build '''MUST''' be used (without versions).
 
* 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.
 
* 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 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].
+
* 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.
 +
 
 +
* For installation of architecture dependent jar files, see [[#Packaging_JAR_files_that_use_JNI|Packaging JAR files that use JNI]]
 +
 
 +
=== 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
 +
* Jar and pom files '''MUST''' be versioned
 +
* Base name of jar and pom files '''MUST''' be the same as original package jar and pom filenames and they '''MUST''' be placed alongside original files
 +
* Package '''SHOULD NOT''' provide maven fragments (%add_maven_depmap calls)
 +
 
 +
{{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.}}
  
* If the number of provided JAR files exceeds '''two''', you '''MUST''' place them into a sub-directory named <code>%{name}</code>.
+
==== Compatibility package example ====
 +
 
 +
* Original package: plexus-container-2.0.0
 +
<pre>
 +
Name:    plexus-container
 +
Version: 2.0.0
 +
...
 +
 
 +
%files
 +
...
 +
%{_javadir}/plexus/container.jar
 +
%{_mavenpomdir}/JPP.plexus-container.pom
 +
%{_mavendepmapfragdir}/%{name}
 +
...
 +
</pre>
 +
 
 +
* Compat package: plexus-container1-1.5.0
 +
<pre>
 +
Name:    plexus-container15
 +
Version: 1.5.0
 +
...
 +
 
 +
%files
 +
...
 +
%{_javadir}/plexus/container-1.5.0.jar
 +
%{_mavenpomdir}/JPP.plexus-container-1.5.0.pom
 +
...
 +
</pre>
  
 
=== Javadoc installation ===
 
=== Javadoc installation ===
Line 55: Line 99:
 
BuildRequires:  jpackage-utils
 
BuildRequires:  jpackage-utils
  
Requires:  java >= specific_version
+
Requires:  java [>= specific_version]
 
Requires:  jpackage-utils</pre>
 
Requires:  jpackage-utils</pre>
  
Line 68: Line 112:
 
<pre>export CLASSPATH=$(build-classpath commons-logging commons-net xbean/xbean-reflect)
 
<pre>export CLASSPATH=$(build-classpath commons-logging commons-net xbean/xbean-reflect)
 
</pre>
 
</pre>
{{admon/note|Additional information|You can use either package names (all jar files will be included) or jar filenames with path prefix to select only some jar files from whole package.}}
+
{{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 ===
 
=== build-jar-repository ===
Line 89: Line 133:
 
</pre>
 
</pre>
  
=== maven ===
+
=== maven3 ===
<code>maven</code> is a tool used by many Java 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:
 
+
=== maven2 ===
+
In Fedora 14 and older (including EPEL), the package is called <code>maven2</code>.  Packages built using <code>maven</code> ship with <code>pom.xml</code> files.  They '''MUST''':
+
 
+
<pre>Requires(post): jpackage-utils
+
Requires(postun): jpackage-utils</pre>
+
 
+
and '''SHOULD''' contain common sections such as the following:
+
  
 
<pre>
 
<pre>
 
...
 
...
 
%build
 
%build
export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository
+
mvn-rpmbuild package javadoc:aggregate
mkdir -p $MAVEN_REPO_LOCAL
+
 
+
mvn-jpp \
+
-Dmaven.repo.local=$MAVEN_REPO_LOCAL \
+
install javadoc:javadoc
+
 
...
 
...
  
Line 115: Line 146:
 
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
 
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
 
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
 
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
# artifactId and jarName are usually %{name} for single module projects
+
install -pm 644 target/%{name}-%{version}.jar $RPM_BUILD_ROOT/%{_javadir}/%{name}.jar
%add_to_maven_depmap [groupId] [artifactId] %{version} JPP[/optional_subDir] [jarName]
+
  
 +
# second argument is optional (parent poms have no jars)
 +
%add_maven_depmap JPP-%{name}.pom %{name}.jar
 
...
 
...
%post
 
%update_maven_depmap
 
  
%postun
+
%check
%update_maven_depmap
+
mvn-rpmbuild verify
...
+
 
 +
%files
 +
%{_mavendepmapfragdir}/%{name}
 +
%{_mavenpomdir}/JPP-%{name}.pom
 
</pre>
 
</pre>
  
{{admon/note|Note:|Multimodule Maven projects should use javadoc:aggregate instead of javadoc:javadoc.}}
+
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|Please read [[Java/JPPMavenReadme]] for details about mvn-jpp and %add_to_maven_depmap usage. }}
+
{{admon/important|Important|For detailed instructions on use of add_maven_depmap macro see [[#depmap_macro|macro documentation]]}}
  
=== maven3 ===
+
=== add_maven_depmap macro ===
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 '''MUST''':
+
{{Anchor|depmap_macro}}
  
<pre>Requires(post): jpackage-utils
+
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.
Requires(postun): jpackage-utils</pre>
+
  
and '''SHOULD''' contain common sections such as the following:
+
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.
 +
 
 +
=== 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}}
 +
 
 +
 
 +
=== Patching Maven <code>pom.xml</code> files ===
 +
 
 +
Sometimes Maven <code>pom.xml</code> files need to be patched before they are used to build packages. One could use traditional patches to maintain changes, but package maintainers '''SHOULD''' use <code>%pom_*</code> macros developed specially to ease this task.
 +
 
 +
These macros are designed to be called from <code>%prep</code> section of spec files. There are documented in <code>/etc/rpm/macros.fjava</code> configuration file, which is also [http://git.fedorahosted.org/git/?p=javapackages.git;a=blob_plain;f=macros.fjava available online]. See the documentation for technical details how to use these macros. Below are some examples added for convenience.
 +
 
 +
Often dependencies specified in Maven <code>pom.xml</code> files need to be removed because of different reasons. <code>%pom_remove_dep</code> macro can be used to ease this task:
  
 
<pre>
 
<pre>
...
+
# Removes dependency on groupId:artifactId from ./pom.xml
%build
+
%pom_remove_dep groupId:artifactId
mvn-rpmbuild install javadoc:aggregate
+
...
+
  
%install
+
# Removes dependency on groupId:artifactId from ./submodule/pom.xml
install -d -m 755 $RPM_BUILD_ROOT%{_javadir}
+
%pom_remove_dep groupId:artifactId submodule
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
+
install -pm 644 pom.xml $RPM_BUILD_ROOT/%{_mavenpomdir}/JPP-%{name}.pom
+
# artifactId and jarName are usually %{name} for single module projects
+
%add_to_maven_depmap [groupId] [artifactId] %{version} JPP[/optional_subDir] [jarName]
+
  
...
+
# Removes dependency on groupId:artifactId from ./full/path/to/file.pom
%post
+
%pom_remove_dep groupId:artifactId full/path/to/file.pom
%update_maven_depmap
+
  
%postun
+
# Removes dependency on all artifacts in group groupId from ./pom.xml
%update_maven_depmap
+
%pom_remove_dep groupId:
...
+
 
 +
# Removes all dependencies from ./pom.xml
 +
%pom_remove_dep :
 
</pre>
 
</pre>
  
Useful mvn-rpmbuild customisations:  
+
<code>%pom_remove_plugin</code> macro works exactly as <code>%pom_remove_dep</code>, except it removes Maven plugin invocations. Some examples:
* -Dmaven.local.depmap.file=FILE.xml - xml file that defines alternative dependency maps
+
 
* -Dmaven.local.debug=true makes custom resolver output more debugging information
+
<pre>
 +
# Disables maven-jar-plugin so that classpath isn't included in manifests
 +
%pom_remove_plugin :maven-jar-plugin
 +
 
 +
# Disable a proprietary plugin that isn't packaged for Fedora
 +
%pom_remove_plugin com.example.mammon:useless-proprietary-plugin submodule
 +
</pre>
 +
 
 +
Sometimes some submodules of upstream project cannot be built for various reasons and there is a need to disable them. This can be achieved by using <code>%pom_disable_module</code>, for example:
 +
 
 +
<pre>
 +
# Disables child-module-1, a submodule of the main pom.xml file
 +
%pom_disable_module child-module-1
 +
 
 +
# Disables grandchild-module, a submodule of child-module-2/pom.xml
 +
%pom_disable_module grandchild-module child-module-2
 +
</pre>
 +
 
 +
The above macros cover the most common cases of modifying <code>pom.xml</code> files, however if there is a need to apply some less-common patches there are also two generic macros for modifying <code>pom.xml</code> files. <code>%pom_xpath_remove</code> can be used to remove arbitrary XML nodes, described by [http://www.w3.org/TR/xpath/ XPath] expressions. <code>%pom_xpath_inject</code> macro is capable of injecting arbitrary [http://www.w3.org/TR/xml/ XML] code to any <code>pom.xml</code> file. Below you can find some examples for these macros.
 +
 
 +
<pre>
 +
# Removes parent definition
 +
%pom_xpath_remove "pom:parent"
 +
 
 +
# Removes extensions from the build
 +
%pom_xpath_remove "pom:build/pom:extensions" module/pom.xml
 +
 
 +
# Adds new dependency
 +
%pom_xpath_inject "pom:dependencies" "<dependency><groupId>org.example.project</groupId><artifactId>awesomeproject</artifactId><version>1.0.0.GA</version></dependency>"
 +
</pre>
  
{{admon/important|Important|Fedora 15+ have both Maven 3.X and Maven 2.2.1 (packages maven and maven2 respectively). Only maven package contains mvn-rpmbuild. Maven 2 is considered deprecated and is included to ensure backward compatibility. Use of maven2 is strongly discouraged in Fedora 15 and newer.}}  
+
{{admon/note|Note|POM files use a specific namespace - http://maven.apache.org/POM/4.0.0. The easiest way to respect this namespace in XPath expressions is prefixing all node names with <code>pom:</code>. For example, <code>pom:environment/pom:os</code> will work because it selects nodes from <code>pom</code> namespace, but <code>environment/os</code> won't find anything because it looks for nodes that don't belong to any XML namespace.}}
  
{{admon/important|Important|Please read [[Java/JPPMavenReadme]] for details about mvn-rpmbuild and %add_to_maven_depmap usage. }}
+
Using <code>%pom_*</code> macros not only increases readability of the spec file, but also improves maintainability of the package as there are no patches that would need to be rebased with each upstream release.
  
 
=== Wrapper Scripts ===
 
=== Wrapper Scripts ===
Line 190: Line 289:
 
=== -devel packages ===
 
=== -devel packages ===
 
<code>-devel</code> packages don't really make sense for Java packages.  Header files do not exist for Java 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_to_maven_depmaps 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 ==
 
== Specfile Template ==
Line 264: Line 355:
  
  
=== maven 2 ===
+
=== maven 3 ===
{{admon/important|Important|Fedora 15+ have both Maven 3.X and Maven 2.2.1 packaged (packages maven and maven2 respectively). Maven 2 is considered deprecated and is included to ensure backward compatibility. Use of maven2 is strongly discouraged, however, older Fedora releases (and EPEL) still require its use.}}
+
 
+
 
<pre>
 
<pre>
 
Name:          # see normal package guidelines
 
Name:          # see normal package guidelines
Line 284: Line 373:
 
BuildRequires:  java-devel
 
BuildRequires:  java-devel
  
BuildRequires:  maven2
+
BuildRequires:  maven
  
 
BuildRequires:    maven-compiler-plugin
 
BuildRequires:    maven-compiler-plugin
Line 295: Line 384:
  
 
Requires:      jpackage-utils
 
Requires:      jpackage-utils
 
Requires(post):      jpackage-utils
 
Requires(postun):    jpackage-utils
 
 
 
Requires:      java
 
Requires:      java
  
 
%description
 
%description
 +
some smart and long description.
  
 
%package javadoc
 
%package javadoc
Line 315: Line 401:
  
 
%build
 
%build
 
+
mvn-rpmbuild package javadoc:aggregate
export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository
+
mkdir -p $MAVEN_REPO_LOCAL
+
 
+
mvn-jpp -Dmaven.repo.local=$MAVEN_REPO_LOCAL \
+
        install javadoc:javadoc # or javadoc:aggregate
+
  
 
%install
 
%install
Line 334: Line 415:
 
         $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom
 
         $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom
  
%add_to_maven_depmap project_group_id project_artifact_id %{version} JPP %{name}
+
%add_maven_depmap JPP-%{name}.pom %{name}.jar
  
 
+
%check
%post
+
mvn-rpmbuild verify
%update_maven_depmap
+
 
+
%postun
+
%update_maven_depmap
+
  
 
%files
 
%files
%{_mavenpomdir}/*
+
%{_mavenpomdir}/JPP-%{name}.pom
%{_mavendepmapfragdir}/*
+
%{_mavendepmapfragdir}/%{name}
%{_javadir}/*
+
%{_javadir}/%{name}.jar
 
%doc
 
%doc
  
Line 356: Line 433:
 
</pre>
 
</pre>
  
{{admon/important|Depmap information|Last two arguments to %add_to_maven_depmap macro represent location of installed jar file. Using ".. jpp/foo bar" as last two arguments will mean that groupId/artifactId of package will resolve to jar file %{_javadir}/foo/bar.jar.}}
+
{{admon/important|Important|For detailed instructions on use of add_maven_depmap macro see [[#add_maven_depmap_macro|macro documentation]]}}
  
For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located [http://fedoraproject.org/wiki/Java/JPPMavenReadme here] .
+
== 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.  
  
=== maven 3 ===
+
=== EE API List ===
{{admon/important|Important|Only Fedora 15 and newer releases have Maven 3. For older releases and EPEL, refer to the maven 2 template.}}
+
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 - 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
  
<pre>
+
=== Packages providing APIs ===
Name:           # see normal package guidelines
+
In addition to following generic guidelines they '''MUST''':
Version:       # see normal package guidelines
+
* Add '''Provides: javax.XXX''' from the [[#EE_API_List|EE API list]]
Release:        1%{?dist}
+
* Add directory %{_javadir}/javax.XXX that will contain symlinks to all implementation jar files and their dependencies
Summary:        # see normal package guidelines
+
  
Group:          # see normal package guidelines
+
At one time there '''CAN BE''' multiple API implementations but there '''MUST''' be at most one package having specific '''javax.XXX''' virtual provide.
License:        # see normal package guidelines
+
URL:            # see normal package guidelines
+
Source0:        # see normal package guidelines
+
  
BuildArch:     noarch
+
=== Packages using APIs ===
 +
Packages that need to use EE API '''SHOULD''' use:
 +
* '''Requires: javax.XXX''' from the [[#EE_API_List|EE API list]]
 +
* '''build-classpath javax.XXX''' or equivalent instead of relying on package-specific jar name.
  
BuildRequires:  jpackage-utils
 
  
BuildRequires:  java-devel
+
== Packaging JAR files that use JNI ==
 +
{{Anchor|JNI}}
 +
=== Applicability ===
  
BuildRequires: maven
+
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.
  
BuildRequires:   maven-compiler-plugin
+
{{Template:Warning}} Note that GCJ packages contain <code>.so</code>s in <code>%{_libdir}/gcj/%{name}</code> but they are not JNI .sos.
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
+
=== Guideline ===
  
Requires(post):      jpackage-utils
+
* JNI packages '''MUST''' follow guidelines of ordinary Java packages with exceptions listed here
Requires(postun):    jpackage-utils
+
* 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>.
 +
* JNI shared objects '''MUST''' be placed in <code>%{_libdir}/%{name}</code>
  
Requires:      java
+
{{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.}}
  
%description
+
{{admon/note|Macro expansions|<code>%{_jnidir}</code> usually expands into <code>%{_prefix}/lib/java</code>. <code>%{_prefix}/lib64/java</code> will cease its existence and will be decomissioned}}
  
%package javadoc
+
=== Example ===
Summary:       Javadocs for %{name}
+
To satisfy this Fedora requirement of using "System.load()" instead of "System.loadLibrary()" while still providing 32-bit versus 64-bit usability as well as complying with Java's write-once-run-anywhere goal, most JNI jar file should contain code similar to the following (as used in the pki-symkey JNI package):  
Group:          Documentation
+
<pre>
Requires:      jpackage-utils
+
    static boolean tryLoad(String filename) {
 +
        try {
 +
            System.load(filename);
 +
        } catch (Exception e) {
 +
            return false;
 +
        } catch (UnsatisfiedLinkError e) {
 +
            return false;
 +
        }
  
%description javadoc
+
         return true;
This package contains the API documentation for %{name}.
+
    }
 
+
%prep
+
%setup -q
+
 
+
%build
+
mvn-rpmbuild install javadoc:aggregate
+
 
+
%install
+
 
+
mkdir -p $RPM_BUILD_ROOT%{_javadir}
+
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar
+
 
+
mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
+
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}
+
 
+
install -d -m 755 $RPM_BUILD_ROOT%{_mavenpomdir}
+
install -pm 644 [path to pom]  \
+
         $RPM_BUILD_ROOT%{_mavenpomdir}/JPP-%{name}.pom
+
 
+
%add_to_maven_depmap project_group_id project_artifact_id %{version} JPP %{name}
+
 
+
 
+
%post
+
%update_maven_depmap
+
 
+
%postun
+
%update_maven_depmap
+
 
+
%files
+
%{_mavenpomdir}/*
+
%{_mavendepmapfragdir}/*
+
%{_javadir}/*
+
%doc
+
 
+
%files javadoc
+
%{_javadocdir}/%{name}
+
 
+
%changelog
+
  
 +
    // Load native library
 +
    static {
 +
        boolean mNativeLibrariesLoaded = false;
 +
        String os = System.getProperty("os.name");
 +
        if ((os.equals("Linux"))) {
 +
            // Check for 64-bit library availability
 +
            // prior to 32-bit library availability.
 +
            mNativeLibrariesLoaded =
 +
                    tryLoad("/usr/lib64/symkey/libsymkey.so");
 +
            if (mNativeLibrariesLoaded) {
 +
                System.out.println("64-bit symkey library loaded");
 +
            } else {
 +
                // REMINDER:  May be trying to run a 32-bit app
 +
                //            on 64-bit platform.
 +
                mNativeLibrariesLoaded =
 +
                        tryLoad("/usr/lib/symkey/libsymkey.so");
 +
                if (mNativeLibrariesLoaded) {
 +
                    System.out.println("32-bit symkey library loaded");
 +
                } else {
 +
                    System.out.println("FAILED loading symkey library!");
 +
                    System.exit(-1);
 +
                }
 +
            }
 +
        } else {
 +
            try {
 +
                System.loadLibrary("symkey");
 +
                System.out.println("symkey library loaded");
 +
                mNativeLibrariesLoaded = true;
 +
            } catch (Throwable t) {
 +
                // This is bad news, the program is doomed at this point
 +
                t.printStackTrace();
 +
            }
 +
        }
 +
    }
 
</pre>
 
</pre>
  
{{admon/important|Depmap information|Last two arguments to %add_to_maven_depmap macro represent location of installed jar file. Using ".. jpp/foo bar" as last two arguments will mean that groupId/artifactId of package will resolve to jar file %{_javadir}/foo/bar.jar.}}
+
Packages utilizing approach of bundling so files as resources within JAR files themselves do not have these issues and are more self-contained.
  
For detailed instructions on the JPackage/Fedora maven, see the JPackage Maven rpm readme located [http://fedoraproject.org/wiki/Java/JPPMavenReadme here] .
+
=== Notes on multiarch ===
  
{{Anchor|JNI}}
+
Our guidelines have never been completely multiarch-aware. So it was never really possible to install both i686 and x86_64 JNI-using java libraries. However guidelines complicated things by introducing usage of %{_libdir} and other directories. This version makes it clear we do not support multiarch for JNI-using packages.
  
== Packaging JAR files that use JNI ==
+
Some of the complications with multiarch for JNI packages are:
 
+
* build-classpath and related tools would need to be aware what will be architecture of executing JVM
=== Applicability ===
+
* build-jar-classpath would still not work for creating symlinks because it would create them on build architecture instead of runtime architecture
 
+
* Previous reasons cause creating of /usr/bin wrappers impractical
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
+
* Handling proper requires in RPM is impossible. For example package Z-native.i686 and JDK.x86_64 are installed. As far as RPM is concerned this would be enough to provide Z.noarch with needed "Requires: Z-native", but it would not work during runtime.
 
+
{{Template:Warning}} Note that GCJ packages contain <code>.so</code>s in <code>%{_libdir}/gcj/%{name}</code> but they are not JNI .sos.
+
 
+
=== 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.
+
 
+
=== Rationale ===
+
 
+
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 ==
 
== Things to avoid ==
Line 503: Line 586:
 
sed -i '/class-path/I d' META-INF/MANIFEST.MF
 
sed -i '/class-path/I d' META-INF/MANIFEST.MF
 
</pre>
 
</pre>
 +
  
 
[[Category:Packaging guidelines]]
 
[[Category:Packaging guidelines]]
 
[[Category:Java]]
 
[[Category:Java]]

Revision as of 19:27, 9 January 2013


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

Contents

Introduction

The Basics

The term Java means many things to many people: a class library, a bytecode interpreter, a JIT compiler, a language specification, etc. For the vast majority of users and developers, Java is a programming language and runtime environment that is architecture- and OS-agnostic. The normal flow of code is .java (source file) .class (Java bytecode) .jar (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 java binary with a list of JAR files specifying the classpath like so:

java [-cp <jar1:jar2:jar3>] <main-class> [<args>]

Java Packaging

The JPackage Project has defined standard file system locations and conventions for use in Java packages. Many distributions have inherited these conventions and in the vast majority of cases, Fedora follows them verbatim. We include relevant sections of the JPackage guidelines here but caution that the canonical document will always reside upstream: JPackage Guidelines . Over time, we would like to remove any divergences in these documents, but where they are different, these Fedora guidelines will take precedence for Fedora packages.

TODO: Find the proper jpackage link and fix it.

Package naming

Packages MUST follow the standard Fedora Packaging/NamingGuidelines.

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

Release tags

Packages MUST follow the standard Fedora Package versioning guidelines.

JAR file installation

The following applies to all JAR files except JNI-using JAR files, GCJ files and application-specific JAR files (ie. JAR files that can only reasonably be used as part of an application and therefore constitute application-private data).

Split JAR files

If a project offers the choice of packaging it as a single monolithic jar or several ones, the split packaging should be preferred.

Filenames

  • If the package provides a single JAR and the filename provided by the build is %{name}.jar or %{name}-%{version}.jar then filename %{name}.jar MUST be used.
  • If the package provides a single JAR and the filename provided by the build is neither %{name}-%{version}.jar nor %{name}.jar then this file MUST be installed as %{name}.jar 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.
Note.png
Note
Here %{name} refers either to package name, or name of subpackage where the jar is installed.

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.

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
  • Jar and pom files MUST be versioned
  • Base name of jar and pom files MUST be the same as original package jar and pom filenames and they MUST be placed alongside original files
  • Package SHOULD NOT provide maven fragments (%add_maven_depmap calls)
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 from main package and will return versioned jar if it matches the version asked for in the pom file.

Compatibility package example

  • Original package: plexus-container-2.0.0
Name:    plexus-container
Version: 2.0.0
...

%files
...
%{_javadir}/plexus/container.jar
%{_mavenpomdir}/JPP.plexus-container.pom
%{_mavendepmapfragdir}/%{name}
...
  • Compat package: plexus-container1-1.5.0
Name:    plexus-container15
Version: 1.5.0
...

%files
...
%{_javadir}/plexus/container-1.5.0.jar
%{_mavenpomdir}/JPP.plexus-container-1.5.0.pom
...

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.

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

build-classpath is a script that can be used to generate classpaths from generic names of JAR files. Example:

export CLASSPATH=$(build-classpath commons-logging commons-net xbean/xbean-reflect)
Note.png
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

build-jar-repository is similar to build-classpath 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

ant is a build tool used by many Java packages. Packages built using ant ship with build.xml files which contain build targets similar to Makefiles. Packages built using ant must:

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

maven3

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

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

%check
mvn-rpmbuild verify

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

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
Important.png
Important
For detailed instructions on use of add_maven_depmap macro see macro documentation

add_maven_depmap macro

Maven identifies jar files by a set of strings: groupId, artifactId and version (mostly). To let mvn-rpmbuild know what groupId:artifactId corresponds to which pom or jar file, we use the %add_maven_depmap macro. %add_maven_depmap reads the groupId and artifactId from the pom file and creates a file in %{_mavendepmapfragdir} that maps groupId:artifactId pairs to jar files under %{_javadir}. 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 -f option as shown below -- all depmap fragments for a given package are written to the same file, %{_mavendepmapfragdir}/%{name}. You should be sure to include this file in the %files section of your RPM.

For the macro to work properly, all jar files must be copied into %{_javadir} (see JAR file installation), and all pom files must be copied into %{_mavenpomdir} and given file names of the following form, where jarname is the name of the jar without the .jar suffix:

%{_mavenpomdir}/JPP[.subdirectory]-jarname.pom

Note that the subdirectory is only necessary if the jar file is put into a subdirectory of %{_javadir}. For example:

  • For junit, the jar is %{_javadir}/junit.jar, so the pom would be %{_mavenpomdir}/JPP-junit.pom.
  • For plexus-ant-factory, the jar is %{_javadir}/plexus/ant-factory.jar, so the pom would named %{_mavenpomdir}/JPP.plexus-ant-factory.pom.

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 %{_mavenpomdir}/JPP-commons-parent.pom.

In its simplest form (a pom without a jar file), %add_maven_depmap looks like this:

%add_maven_depmap JPP-%{name}.pom

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 %{_mavenpomdir}.

For a pom that maps directly to a jar file, the following is the correct form:

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

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.

%add_maven_depmap JPP-%{name}.pom %{name}.jar -a "org.apache.commons:commons-lang"

This form also adds additional mappings for given pom/jar file. 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.

%add_maven_depmap JPP-%{name}.pom %{name}.jar -f "XXX"

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

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

This form should be used when a package consists of multiple jar files that are installed into a subdirectory of %{_javadir}. Note that in this case, the pom file name includes the optional subdirectory field.

Maven pom.xml files and depmaps

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

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

Idea.png
Tip
Mvnrepository site can be used to ease


Patching Maven pom.xml files

Sometimes Maven pom.xml files need to be patched before they are used to build packages. One could use traditional patches to maintain changes, but package maintainers SHOULD use %pom_* macros developed specially to ease this task.

These macros are designed to be called from %prep section of spec files. There are documented in /etc/rpm/macros.fjava configuration file, which is also available online. See the documentation for technical details how to use these macros. Below are some examples added for convenience.

Often dependencies specified in Maven pom.xml files need to be removed because of different reasons. %pom_remove_dep macro can be used to ease this task:

# Removes dependency on groupId:artifactId from ./pom.xml
%pom_remove_dep groupId:artifactId

# Removes dependency on groupId:artifactId from ./submodule/pom.xml
%pom_remove_dep groupId:artifactId submodule

# Removes dependency on groupId:artifactId from ./full/path/to/file.pom
%pom_remove_dep groupId:artifactId full/path/to/file.pom

# Removes dependency on all artifacts in group groupId from ./pom.xml
%pom_remove_dep groupId:

# Removes all dependencies from ./pom.xml
%pom_remove_dep :

%pom_remove_plugin macro works exactly as %pom_remove_dep, except it removes Maven plugin invocations. Some examples:

# Disables maven-jar-plugin so that classpath isn't included in manifests
%pom_remove_plugin :maven-jar-plugin

# Disable a proprietary plugin that isn't packaged for Fedora
%pom_remove_plugin com.example.mammon:useless-proprietary-plugin submodule

Sometimes some submodules of upstream project cannot be built for various reasons and there is a need to disable them. This can be achieved by using %pom_disable_module, for example:

# Disables child-module-1, a submodule of the main pom.xml file
%pom_disable_module child-module-1

# Disables grandchild-module, a submodule of child-module-2/pom.xml
%pom_disable_module grandchild-module child-module-2

The above macros cover the most common cases of modifying pom.xml files, however if there is a need to apply some less-common patches there are also two generic macros for modifying pom.xml files. %pom_xpath_remove can be used to remove arbitrary XML nodes, described by XPath expressions. %pom_xpath_inject macro is capable of injecting arbitrary XML code to any pom.xml file. Below you can find some examples for these macros.

# Removes parent definition
%pom_xpath_remove "pom:parent"

# Removes extensions from the build
%pom_xpath_remove "pom:build/pom:extensions" module/pom.xml

# Adds new dependency
%pom_xpath_inject "pom:dependencies" "<dependency><groupId>org.example.project</groupId><artifactId>awesomeproject</artifactId><version>1.0.0.GA</version></dependency>"
Note.png
Note
POM files use a specific namespace - http://maven.apache.org/POM/4.0.0. The easiest way to respect this namespace in XPath expressions is prefixing all node names with pom:. For example, pom:environment/pom:os will work because it selects nodes from pom namespace, but environment/os won't find anything because it looks for nodes that don't belong to any XML namespace.

Using %pom_* macros not only increases readability of the spec file, but also improves maintainability of the package as there are no patches that would need to be rebased with each upstream release.

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.

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

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

Specfile Template

ant

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

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

BuildRequires:  jpackage-utils

BuildRequires:  java-devel

BuildRequires:  ant

Requires:       jpackage-utils

Requires:       java

%description

%package javadoc
Summary:        Javadocs for %{name}
Group:          Documentation
Requires:       jpackage-utils

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

%prep
%setup -q

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

%build
ant

%install

mkdir -p $RPM_BUILD_ROOT%{_javadir}
cp -p [build path to jar] $RPM_BUILD_ROOT%{_javadir}/%{name}.jar

mkdir -p $RPM_BUILD_ROOT%{_javadocdir}/%{name}
cp -rp [javadoc directory] $RPM_BUILD_ROOT%{_javadocdir}/%{name}

%files
%{_javadir}/*
%doc

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


%changelog


maven 3

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

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

BuildArch:      noarch

BuildRequires:  jpackage-utils

BuildRequires:  java-devel

BuildRequires:  maven

BuildRequires:    maven-compiler-plugin
BuildRequires:    maven-install-plugin
BuildRequires:    maven-jar-plugin
BuildRequires:    maven-javadoc-plugin
BuildRequires:    maven-release-plugin
BuildRequires:    maven-resources-plugin
BuildRequires:    maven-surefire-plugin

Requires:       jpackage-utils
Requires:       java

%description
some smart and long description.

%package javadoc
Summary:        Javadocs for %{name}
Group:          Documentation
Requires:       jpackage-utils

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

%prep
%setup -q

%build
mvn-rpmbuild 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

%check
mvn-rpmbuild verify

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

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

%changelog

Important.png
Important
For detailed instructions on use of add_maven_depmap macro see macro documentation

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

Example

To satisfy this Fedora requirement of using "System.load()" instead of "System.loadLibrary()" while still providing 32-bit versus 64-bit usability as well as complying with Java's write-once-run-anywhere goal, most JNI jar file should contain code similar to the following (as used in the pki-symkey JNI package):

    static boolean tryLoad(String filename) {
        try {
            System.load(filename);
        } catch (Exception e) {
            return false;
        } catch (UnsatisfiedLinkError e) {
            return false;
        }

        return true;
    }

    // Load native library
    static {
        boolean mNativeLibrariesLoaded = false;
        String os = System.getProperty("os.name");
        if ((os.equals("Linux"))) {
            // Check for 64-bit library availability
            // prior to 32-bit library availability.
            mNativeLibrariesLoaded =
                    tryLoad("/usr/lib64/symkey/libsymkey.so");
            if (mNativeLibrariesLoaded) {
                System.out.println("64-bit symkey library loaded");
            } else {
                // REMINDER:  May be trying to run a 32-bit app
                //            on 64-bit platform.
                mNativeLibrariesLoaded =
                        tryLoad("/usr/lib/symkey/libsymkey.so");
                if (mNativeLibrariesLoaded) {
                    System.out.println("32-bit symkey library loaded");
                } else {
                    System.out.println("FAILED loading symkey library!");
                    System.exit(-1);
                }
            }
        } else {
            try {
                System.loadLibrary("symkey");
                System.out.println("symkey library loaded");
                mNativeLibrariesLoaded = true;
            } catch (Throwable t) {
                // This is bad news, the program is doomed at this point
                t.printStackTrace();
            }
        }
    }

Packages utilizing approach of bundling so files as resources within JAR files themselves do not have these issues and are more self-contained.

Notes on multiarch

Our guidelines have never been completely multiarch-aware. So it was never really possible to install both i686 and x86_64 JNI-using java libraries. However guidelines complicated things by introducing usage of %{_libdir} and other directories. This version makes it clear we do not support multiarch for JNI-using packages.

Some of the complications with multiarch for JNI packages are:

  • build-classpath and related tools would need to be aware what will be architecture of executing JVM
  • build-jar-classpath would still not work for creating symlinks because it would create them on build architecture instead of runtime architecture
  • Previous reasons cause creating of /usr/bin wrappers impractical
  • Handling proper requires in RPM is impossible. For example package Z-native.i686 and JDK.x86_64 are installed. As far as RPM is concerned this would be enough to provide Z.noarch with needed "Requires: Z-native", but it would not work during runtime.

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 Requires. 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 %prep (courtesy David Walluck):

JAR files=""
for j in $(find -name \*.jar); do
if [ ! -L $j ] ; then
JAR files="$JAR files $j"
fi
done
if [ ! -z "$JAR files" ] ; then
echo "These JAR files should be deleted and symlinked to system JAR files: $JAR files"
exit 1
fi

Javadoc scriptlets

Older JPackage packages contained %post scriptlets creating %ghost symlinks. These MUST not appear in Fedora Java packages and are actively being removed at JPackage.

Selected rpmlint issues

class-path-in-manifest

Use sed to remove class-path elements in MANIFEST.MF (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