JPackage Maven RPM Plugin

Work in progress

This site is in the process of being reviewed and updated.

-------------------------------------------
JPackage RPM Plugin Design
-------------------------------------------

Objective

The Objective of the JPackage Maven RPM Plugin
is to automate the generation RPMs that comply
with JPacakge standards and eliminate the
need for links and install jar file naming
by generating class and
configuration file loaders.

TODO - Do we need to generate other files as
well to completely eliminate linking and
install file naming?

The plugin should enable the generation of
an RPM for all maven builds.

Initial priority has been the packaging of
daemons and libraries.

Background

Automate the Creation of a JPackage RPM for Daemons

Self Explanatory

Eliminating File Linking

JPackages of Daemons ensure that
the files the Daemon uses are laid
out according to FHS standards.

If the JPackage does not change the
source code for the Daemon, then the
package installer must create links
pointing the Daemon to the new file
locations.

The plugin solves this by generating
the Java class loader and configuration
loader files that that are given
their library and configuration file
locations by the plugin.

Note that this does require JET
templates that can generate
the necessary classes.

Eliminating Install Jar File Naming

The jar artifacts that Maven produces
are named according to the Maven naming
convention for Jar files, currently the
artifactId plus the artifact version.

However the version is typically stripped,
so that the manually coded Daemon's class loaders, etc.
do not need to be recoded for each release.

By generating these files, the maven jar
artifact names can remain unchanged, which
simplifies the configuration file for the plugin.

Note that this does require JET
templates that can generate
the necessary classes.

Terminology and Concepts

JET Implementation Class

A JET Implementation class is a class
that was generated from a JET template.

This class is then used to generate
another file. The file could be a Java
file, an XML file, etc.

This is the same concept used by
Java Server Pages. Java Server Page
templates (Sometemplate.jsp)
are translated into servlets.

Servlets are class files (Sometemplate.class).
The class file is then used by the Servlet
Container to generate the response we see
on in a web browser.

In our case, we see a generated spec file
in the RPM Build Environment's SPECS directory, etc.

Plugin Invocation Prerequisites

The environment variables
$RPM_BUILD_ENVIRONMENT_ROOT
and
$M2_REPO
must be exported.

Maven Build Process Considerations

Dependencies

The plugin will generate Build_Requires and Requires
spec file headers that ensure that the project
can be built and installed.

Maven downloads dependencies automatically
from configured repositories. It is important
that Maven be pointed to JPackage repositories
only for the build, such that the dependencies
that are downloaded by RPM during the install,
are the same as the dependencies Maven uses during
the build.

The repository that Maven points to during the build
should therefore contain JPackage provided maven
projects only.

This repository and the JPackage RPM repository
must stay synchronized with respect to project updates
and revisions.

Dependencies pulled by Maven for the build should come
from a JPackage owned repository.

Use Cases

Daemon RPM Generation

Library RPM Generation

Plugin Concerns

The plugin is concerned with the following:

Fetching files from the local Maven repository
Creating install directory layouts
Placing files contained in the Maven repository
in the install layout directories
Specifying file permissions
Specifying file ownership

Process Driver

The process driver, or plugin goal,
is to generate an RPM spec file and
run it with RPM.

The Plugin takes as input a configuration file
and the Maven pom.xml file
uses values found in those two files
generate a spec file.

The process therefore has to encapsulate / enumerate all of the
various spec file permutations that JPackage developers
use.

So this plugin supports a
filtered set of these permutations.

The filter consists of current JPackage conventions.

When a convention for a permutation / spec file case
is missing, the JPackage team should be consulted and the
case convention documented.

Spec File Enumeration

The following is a list of generic concepts /
models employed in coding the spec file.

These are also the spec file generation cases
that the plugin supports.

Define Generic Properties

- Example
  ----------------------------------------------------------------------------
  %define jspspec 2.0
  ----------------------------------------------------------------------------

- Configuration File Source

- JPackage Convention

- Notes and Related Concepts

TODO
Try to eliminate the need for these completely
by working to standardize all such properties.

The question here is do we need
generic properties in the context of Maven?

TODO
Write the plugin without support for this
initially and evaluate the need.

Define Install Directories

- Spec File Example
  ----------------------------------------------------------------------------
  %define confdir %{_sysconfdir}/%
  Unknown macro: {name}
  ----------------------------------------------------------------------------
  - - Configuration Source
  InstallFile.name >> confdir
  InstallFile.value >> %{_sysconfdir}/%
  InstallFile.isDirectory = true

- JPackage Conventions

TODO
Standardize directory names
like confdir, so that they
can be provided as part of the
Archetype baseline.

TODO
Specify naming conventions for InstallFile names
Link Here

TODO
Specify standard JPackage install directories
Link Here

TODO
For standard install directories provided as
part of an Archetype, set isDirectory to true

- Notes and Related Concepts

TODO
Cross reference with:
Create Install Directories
Set Install Directory Permissions
Set Install Directory Ownership

Create Install Directories

- Example
  ----------------------------------------------------------------------------
  install -d -m 755 $RPM_BUILD_ROOT{%{confdir}}
  ----------------------------------------------------------------------------

- Configuration Source

InstallFile.name >> $RPM_BUILD_ROOT{%{confdir}}
InstallFile.permissions >> 755
Package.defaultPermissions >> 755
InstallFile.isDirectory = true >> -d

- Generation Rule

If InstallFile.permissions
is set then use that, otherwise
use Package.defaultPermissions

- JPackage Convention

- Notes and Related Concepts

TODO
Cross reference with:
Define Install Directories
Set Install Directory Default Permissions
Set Install Directory Ownership

Set Package Owned Directories

- Example
  ----------------------------------------------------------------------------
  %dir %
  Unknown macro: {homedir}
  ----------------------------------------------------------------------------

- Configuration Source

InstallFile.isPackageOwned = true >> %dir

- JPackage Convention

- Notes and Related Concepts

TODO
Cross reference with:
Define Install Directories
Set Install Directory Default Permissions
Set Install Directory Ownership

Set Install File Default Permissions

- Example
  ----------------------------------------------------------------------------
  %defattr(644,root,root,755)
  ----------------------------------------------------------------------------

- Configuration Source

Package.defaultFilePermissions >> 644
Package.defaultDirectoryPermissions >> 755

- JPackage Convention

- Notes and Related Concepts

TODO
Cross reference with:
Define Install Directories
Create Install Directories
Set Install Directory Ownership

Set Install File Custom Permissions

- Example
  ----------------------------------------------------------------------------
  %attr(775,root,tomcat) %
  Unknown macro: {appdir}
  ----------------------------------------------------------------------------
  - - Configuration Source
  InstallFile.permissions >> 775
  - - JPackage Convention
  - - Notes and Related Concepts
  TODO
  Cross reference with:
  Define Install Directories
  Create Install Directories
  Set Install Directory Ownership
  - Set Install File Default Ownership
  - - Example
      ----------------------------------------------------------------------------
      %defattr(644,root,root,755)
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.defaultUser >> root
  Package.defaultGroup >> root
  - - JPackage Convention
  - - Notes and Related Concepts
  TODO
  Cross reference with:
  Define Install Directories
  Create Install Directories
  Set Install Directory Permissions
  - Set Install File Custom Ownership
  - - Example
      ----------------------------------------------------------------------------
      %attr(775,root,tomcat) %
  ----------------------------------------------------------------------------

- Configuration Source

InstallFile.user >> root
InstallFile.group >> tomcat
InstallFile.name >> appdir

- JPackage Convention

- Notes and Related Concepts

TODO
Cross reference with:
Define Install Directories
Create Install Directories
Set Install Directory Permissions

Mark Configuration Files

- Example
  ----------------------------------------------------------------------------
  %config(noreplace) %
  Unknown macro: {confdir}
  /workers2.properties.minimal
  ----------------------------------------------------------------------------
  - - Configuration Source
  InstallFile.isConfiguration = true >> %config(noreplace)
  InstallFile.value >> %
  /workers2.properties.minimal

- JPackage Convention

- Notes and Related Concepts

Mark Documentation Files

- Example
  ----------------------------------------------------------------------------
  %doc %{_javadocdir}/%
  Unknown macro: {name}
  servlet%
  
  Unknown macro: {servletspec}
  
  api%
  
  Unknown macro: {version}
  
  ----------------------------------------------------------------------------
  - - Configuration Source
  InstallFile.isDocumentation = true >> %doc
  InstallFile.value >> %{_javadocdir}/%
  servlet%
  Unknown macro: {servletspec}
  api%
  Unknown macro: {version}
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Summary Header
  - - Example
      ----------------------------------------------------------------------------
      Summary: Apache Servlet/JSP Engine, RI for Servlet 2.4/JSP 2.0 API
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.description.body >> Apache Servlet/JSP Engine, RI for Servlet 2.4/JSP 2.0 API
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Name Header
  - - Example
      ----------------------------------------------------------------------------
      Name: tomcat
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.name.body >> tomcat
  - - JPackage Convention
  TODO
  JPackage uses tomcat55
  Is there a rule we can employ here...
  so that we can just use Maven pom values?
  - - Notes and Related Concepts
  - Set the Version Header
  - - Example
      ----------------------------------------------------------------------------
      Version: 5.5.17
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.version.body >> 5.5.17
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Epoch Header
  - - Example
      ----------------------------------------------------------------------------
      Epoch: 0
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.epoch >> 0
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the License Header
  - - Example
      ----------------------------------------------------------------------------
      License: Apache Software License
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.licenenses.*
  
  Maven supports multiple licenses, so we need to concatenate
  them if there are more than one.
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Vendor Header
  - - Example
      ----------------------------------------------------------------------------
      Vendor: JPackage Project
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.vendor >> JPackage Project
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Distribution Header
  - - Example
      ----------------------------------------------------------------------------
      Distribution: JPackage
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.distribution >> JPackage
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Group Header
  - - Example
      ----------------------------------------------------------------------------
      Group: Networking/Daemons
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.group >> Networking/Daemons
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the URL Header
  - - Example
      ----------------------------------------------------------------------------
      URL: http://tomcat.apache.org/
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.url.body >> http://tomcat.apache.org/
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the BuildArch Header
  - - Example
      ----------------------------------------------------------------------------
      BuildArch: noarch
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.buildArchitecture >> noarch
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the Source0 Header
  - - Example
      ----------------------------------------------------------------------------
      Source0: http://www.apache.org/dist/tomcat/tomcat-5/v%
  /src/%
  Unknown macro: {packdname}
  .tar.gz
  ----------------------------------------------------------------------------
  - - Configuration Source
  MavenProject.protocol >> http
  MavenProject.isArchive >> true
  MavenProject.archiveType >> tar.gz
  MavenProject.path >> www.apache.org/dist/tomcat/tomcat-5/v%
  
  Unknown macro: {version}
  
  /src/%
  .tar.gz

- JPackage Convention

Suggestions:

protocol + path + artifactId + version + "." + archiveType

- Notes and Related Concepts

Set the Patch Headers

- Example
  ----------------------------------------------------------------------------
  Patch0: %
  Unknown macro: {name}
  -%
  
  Unknown macro: {majversion}
  
  .link_admin_jar.patch
  ----------------------------------------------------------------------------
  - - Configuration Source
  - - JPackage Convention
  - - Notes and Related Concepts
  Patches should be kept
  in a related maven project,
  under
  
  /src/main/resources/patches/
  
  Naming convention for this project:
  
  The artifact Id of the project it patches plus Patches:
  
  artifactId + Patches
  
  This way Patches can be fetched from the Maven repository
  the same way other resources are.
  
  Patch Naming Convention?????
  - Set the Requires Headers
  - - Example
      ----------------------------------------------------------------------------
      Requires: jpackage-utils >= 0:1.6.0
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.dependencies.dependency.artifactId.body>> jpackage-utils
  project.dependencies.dependency.version.body >> 0:1.6.0
  project.dependencies.dependency.scope.body >> provided
  - - JPackage Convention
  - - Notes and Related Concepts
  - Set the BuildRequires Headers
  - - Example
      ----------------------------------------------------------------------------
      BuildRequires: xml-commons-apis >= 1.3
      ----------------------------------------------------------------------------
  - - Configuration Source
  project.dependencies.dependency.artifactId.body>> xml-commons-apis
  project.dependencies.dependency.version.body >> 1.3
  project.dependencies.dependency.scope.body = compile
  - - JPackage Convention
  - - Notes and Related Concepts
  - Prepare the Description Section
  - - Example
      ----------------------------------------------------------------------------
      %description
      Blah Blah Blah
      ----------------------------------------------------------------------------
  - - Configuration Source
  Package.description >> Blah Blah Blah
  - - JPackage Convention
  - - Notes and Related Concepts
  - Prepare the Prep Section
  - - Example
      ----------------------------------------------------------------------------
      %prep
      rm -rf $RPM_BUILD_DIR/%
  -%
  Unknown macro: {version}
  %setup -q -c -T -a 0

cd %

Unknown macro: {packdname}

%patch0 -b .p0
%patch1 -b .p1
...
----------------------------------------------------------------------------

- Configuration Source

MavenProject.isArchive = true >> %setup -q -c -T -a 0

- JPackage Convention

- Notes and Related Concepts

Prepare the Build Section

- Example
  ----------------------------------------------------------------------------
  %build

----------------------------------------------------------------------------

- Configuration Source

- JPackage Convention

- Notes and Related Concepts

RPM Archetype

JPackage RPM Archetypes that
provide plugin baseline
configurations will be distributed along side
the plugin. This way the amount of effort
required to generate a JPackage compliant
RPM is minimized.

Each Archetype targets a specific
RPM generation case. See the JPackage RPM
plugin configuration section for more info.

TODO - Put a link here.

Creating a JPackage RPM Project

In order to have their project
packaged with the JPackage RPM
Plugin, a developer must first create
a JPackage RPM Project using
the Archetype provided with the plugin.

The JPackage RPM project created will then have
the main project that the developer is
working on as a dependency.

This is because we want all the test
and verification phases to be run prior
to packaging the project.

So for packaging Apache Directory Server
for instance, we would create the
an ApacheInstaller Project (With the JPackage
Archetype), and add
the ApacheDirectoryServer project
as a dependency.

This ensures that the Apache Directory Server
project gets built and its subprojects installed
in the maven repository before the installer plugin
fetches repository artifacts.

Note that it is also possible to run the
plugin standalone and just let it produce
and run the Spec file.

JPackage RPM Plugin Configuration

The plugin supports specific
RPM generation cases.

One case would be
the generation of an RPM for a
daemon project.

Another case would be the generation
of an RPM for a library projects, etc.

An Archetype is provided for each
RPM generation case.

Plugin Update Lifecycle

The plugin needs to be updated
under the following circumstances:

To support further customization of
the generated spec file.
To support new configuration options.

Plugin Phase

The plugin will be invoked during the
package phase of the maven lifecycle.

Plugin Process

Run the Archetype command

- Daemon Installer Project

- Library Installer Project

Update specmap.xml

In the directory src/main/resources/SPECS/
under the projects root directory there is
a specmap.xml file.

Update this file so that it contains the parameters
necessary to generate the RPM.

The following sections explain
how to go about this task.

Note that the elements listed
are contained inside the
<packageDefinition> root
element.

.

Child pages

JPackage Maven RPM Plugin