[jsword-devel] Jar names and building a RPM for Linux

[DM Smith]

I am working on building a cross-platform jar file for Linux. I am 
considering creating a JPackage style RPM, perhaps even posting it at 
jpackage.org. To do this, we would need to follow JPackage-utils-policy, 
which I have attached.

Also there are standards (FHS <http://www.pathname.com/fhs>) on how 
files and directories should be laid out in Linux, which JPackage uses 
as its standard.

Anyway, to use it will require us to "depend" on other packages 
(jakarta-commons-net, ...) and to publish our application to standard 
locations. One good side effect of this is that our package is much smaller.

The biggest impact will be the jar names. By putting the jars in a 
standard location, we need to name the jars in a product specific 
manner. This means that common.jar will need to be renamed to indicate 
that it is part of jsword. Also, jars are to have a version number.

These guidelines make sense to me and if there are no objections, I am 
going to change the names of our jars to something like:
jsword.jar becomes jsword-1.0.jar
common.jar becomes jsword-util-1.0.jar or jsword-common-1.0.jar
bibledesktop.jar becomes bibledesktop-1.0.jar
(If there are objections after I make the change, we can always revert 
the change.)

When packaging, jsword.jar and common.jar will be in one 
jsword-1.0-jpp.rpm and bibledesktop will be in bibledesktop-1.0-jpp.rpm 
that depends the first.

Later we can automate the nightly construction of the RPMs.

In His Service,
    DM

JPackage-utils-policy in its entirety:
==============================================
$Id: jpackage-utils-policy,v 1.1 2004/12/15 16:23:45 robert Exp $

JPackage packaging policy

Package

Name

The package name, hereafter refered to as %{name}, is the complete
name of the packaged software.

Exception: if it is a requirement that multiple versions of a package
can be installed to a single machine, relevant part of the version
number is appended to complete software name to form the package name.

Package name must contain only lowercase characters.

Version

The package version, hereafter referred to as %{version}, is the
complete version of the packaged software.

Exception: non-numeric version extensions, such as "pre", "rc",
"beta", etc, are prohibited as they may confuse rpm. Instead, these
are included in the package revision.

Exception: when no exact version is available, as in non-tagged CVS
snapshot, use the snapshot date in YYYYMMDD format.

Release

The package release, hereafter refered to as %{release}, is a strictly
increasing number, followed by specific project jpp tag appended.

Exception: when non-numeric version extensions are used, this number
is preceded by the number 0, a dot, and the version extension to
ensure proper release ordering.

Granularity

Small is beautiful: prefer several modular subpackages when possible.

The main package must contain only basic files needed for running the
software, with license agreement and basic documentation files.

Any optional file must be provided as a separate subpackage, with
exact version and release dependency to the main package.

Any demo or sample files must be provided as a separate -demo
subpackage, with exact version and release dependency to the main
package.

Any user manual must be provided as a separate -manual subpackage,
with no special dependency to the main package.

Each Javadoc tree must be provided as a separate -javadoc subpackage,
with no special dependency to the main package.

Sections

free section contains free software.

non-free section contains non-free and non-distributable software.

Dependencies

A free package must avoid optional non-free runtime
dependencies. Build dependencies are needed, however, to ensure proper
build environment.

Files

Locations

Data and demo files must be installed into the standard
/usr/share/%{name} directory.

Javadoc files must be installed into a
/usr/share/javadoc/%{name}-%{version} directory.

Application archives must be installed under the /usr/share/java
directory in the following way:

For simple software with just a few jars, directly to top level.  For
simple software with many jars, into a /usr/share/java/%{name}
directory.  For complex applications, in a /usr/share/java/%{name}
subdirectory with proper internal structure.

Names

The general idea is that given package name, one should be able to
deduce jar name(s): package abcd should contain either a single
/usr/share/java/abcd.jar jar, or multiple /usr/share/java/abcd/*.jar
or /usr/share/java/abcd-*.jar jars.

Main jars stored directly under /usr/share/java must follow naming
pattern %{name}-%{version}.jar.

Secondary jars stored directly under /usr/share/java must follow
naming pattern %{name}-<subpackage>-%{version}.jar.

Jars stored in a /usr/share/java/%{name} subdirectory must follow
naming pattern <subpackage>-%{version}.jar.

All zip format archive must be converted to jar format, and a
compatibility symlink be provided.

All legacy names must be converted to standard names, and a
compatibility symlink be provided if there's substantial difference.

Compatibility symlinks must be versioned too.

For every versioned jar or symlink, a corresponding unversioned
symlink must be provided to allow version independant use.

Granularity
 
Once again, small is beautiful: prefer several modular jars when
possible.

Avoid duplicate classes, and remove redundant jars.

Building

In order to track source origin, it is preferable to use unmodified
original archives, when available in a form suitable for building.

Never use provided external binaries. Delete them to ensure potential
build interference.

Running

All applications must use a standardized wrapper script, using the
JPackage function library.

All servers must be shipped with usual service script, logrotate
configuration, etc...

Classpath references in MANIFEST files interfere with classpath, are
not configurable, and don't work in JDK 1.1.x. They must be removed.