Contents
- 1 TODO
- 2 Introduction
- 3 Java Packaging
- 4 Specfile Template
- 5 Packaging JAR files that use JNI
- 6 Things to avoid
- 7 Authors
TODO
This section lists remarks and improvements to be included in the following policy. It doesn't belong to the policy itself and it should, hopefully, be empty when the policy will be publicly available on definitive wiki
- the policy should mention %jar, %java, %javac, %javadoc, %java_home that should be used when those tools/paths are needed. (hanssi)
- The part about Requires should be pushed in rpm dependency solver (misc)
- The same goes for maven and Requires(post), postun. This should be detected by rpm., and we should use filetrigger. (misc)
- what does the require on jpackages-utils bring ? (misc)
- The part about 1%{?dist} should be adapted to use %mkrel (as we didn't decide to drop it afaik). (misc)
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 [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, Mageia 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 Mageia guidelines will take precedence for Mageia packages.
TODO : Ensure jpackage still provide a packaging policy. I can't find it on the website.
Package naming
Packages name should follow the upstream name. To delimit name parts, a dash '-' must be used unless another separator appears in upstream name.
Java API documentation uses a system known as javadoc. It must be placed into a sub-package called %{name}-javadoc.
Release tags
Packages must follow the standard Mageia package versioning guideline
TODO : add the link to versioning policy
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}.jar nor %{name}-%{version}.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.
Installation directory
- All JAR files must go into %{_javadir} or a Java-version specific directory %{_javadir}-* as appropriate[|(1)].
- If the number of provided JAR files exceeds two, they must be placed into a sub-directory named %{name}.
Javadoc installation
- 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-rpmbuild Requires: java >= specific_version Requires: jpackage-utils
java-rpmbuild selects the "main" java compiler (openjdk on all archs where it is supported, gcj/ecj on others)
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)
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.
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
ant based build scripts are generally bundled with their required jars. But in order to avoid to ship pre-build jar files and to build the package against the system installed jars, the spec file should either:
- add some parameters to ant (if the build.xml supports it) constructed with build-classpath
- patch the build.xml to use the jars in the standard location
- create symlinks where the build.xml expect them (using build-jar-repository?)
maven
maven is a tool used by many Java packages. In Mageia, the package is called maven2. Packages built using maven ship with pom.xml files. They must:
Requires(post): jpackage-utils Requires(postun): jpackage-utils
and should contain common sections such as the following:
... %build export MAVEN_REPO_LOCAL=$(pwd)/.m2/repository mkdir -p $MAVEN_REPO_LOCAL mvn-jpp \ -Dmaven.repo.local=$MAVEN_REPO_LOCAL \ install javadoc:javadoc ... %install rm -rf $RPM_BUILD_ROOT install -d -m 755 $RPM_BUILD_ROOT%{_javadir} install -d -m 755 $RPM_BUILD_ROOT%{_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] ... %post %update_maven_depmap %postun %update_maven_depmap ...
Note
Multimodule Maven projects should use javadoc:aggregate instead of javadoc:javadoc.
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 [maven repo] should be checked and if there are pom.xml files they should be installed.
Tip
[site] can be used to ease.
Wrapper Scripts
Applications wishing to provide a convenient method of execution should provide a wrapper script in %{_bindir}. These can be as simple as this example:
#!/bin/sh if [ -f /usr/share/java-utils/java-functions ] ; then . /usr/share/java-utils/java-functions else echo "Can't find functions library, aborting" exit 1 fi # Configuration MAIN_CLASS=<MyCoolApp> # Set parameters set_classpath "<mycoolapp>" # Let's start run "$@"
Specify your script as additional source :
... Source1: %{name}.jtidy.script ...
and install it into %{_bindir}:
%install ... # shell script mkdir -p %{buildroot}%{_bindir} cp -ap %{SOURCE1} %{buildroot}%{_bindir}/%{name} ...
Don't forget set file permissions correctly:
%files ... %attr(755, root, root) %{_bindir}/* ...
GCJ
Building GCJ AOT bits is discouraged. If you have a good reason to build them they must be placed in a sub-package named %{name}-gcj to avoid a require on java-1.5.0-gcj on the main package, because this will force every single user to install it even if one wants to use another JVM.
TODO : Add specific policy for GCJ (if useful)
Specfile Template
ant
Name: # see spec syntax policy Version: # see normal package guidelines Release: %mkrel 1 Summary: # see normal package guidelines License: # see normal package guidelines Group: # 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' -delete find -name '*.jar' -delete %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 %defattr(-,root,root,-) %{_javadir}/* %doc %files javadoc %defattr(-,root,root,-) %{_javadocdir}/%{name} %changelog
maven
Name: # see normal package guidelines Version: # see normal package guidelines Release: %mkrel 1 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: maven2 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(post): jpackage-utils Requires(postun): 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 %build 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 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 %defattr(-,root,root,-) %{_mavenpomdir}/* %{_mavendepmapfragdir}/* %{_javadir}/* %doc %files javadoc %defattr(-,root,root,-) %{_javadocdir}/%{name} %changelog
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.
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
Caution : Note that GCJ packages contain .sos in %{_libdir}/gcj/%{name} but they are not JNI .sos.
Guideline
JAR files that require JNI shared objects must be installed in %{_libdir}/%{name}. The JNI shared objects themselves must also be installed in %{_libdir}/%{name}. 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. If the package installs a wrapper script you'll need to manually add %{_libdir}/%{name}/<jar filename> to CLASSPATH. If you are depending on a JNI-using JAR file, you'll need to add it manually -- build-classpath will not find it.
Rationale
This is less convenient, but cleaner from a packaging point-of-view, than putting the JAR file in %{_javadir}, and putting the JNI shared object in %{_libdir} to be loaded from the default library path. First, JNI shared objects are dlopen'd, and dlopen'd shared objects should not be placed directly in %{_libdir} 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 %{_javadir} causes the build-classpath script to always load it, even when running on a runtime environment of the wrong arch, meaning that the System.loadLibrary line would fail.
The plan is to eventually eliminate patching of the System.loadLibrary line and wrapper script by making jpackage-utils multilib aware. This involves the following changes: creating %{_libdir}/java and %{_libdir}/jni 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 jpackage-utils's runtime scripts to search %{_libdir}/java; modifying **IcedTea** to look for JNI shared objects in %{_libdir}/jni.
The %{_jnidir} rpm macro defines the main JNI jar repository. Like %{_javadir} it is declined in -ext and -x.y.z variants. It follows exactly the same rules as the %{_javadir}-derived tree structure, except that it hosts JAR files that use JNI.
%{_jnidir} usually expands into /usr/lib/java.
TODO : add guideline about JNA
Things to avoid
Pre-built JAR files / Other bundled software
Many Java projects re-ship their dependencies in their own releases. This should be avoided in Mageia. All packages should be built from source and should enumerate their dependencies with Requires. They should 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 Mageia. 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 Mageia 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
Authors
- Fedora project
- François Jaouen