| unmigrated-wiki-markup |
|---|
{note:title=Work in progress} This site is in the process of being reviewed and updated. {note} ----------------------------------------- |
...
-- JPackage RPM Plugin Design ------------------------------------------- ----------------- |
...
Objective
The Objective of the JPackage Maven RPM Plugin
is to enable generation RPMs that comply
with JPacakge standards.
The plugin should enable the generation of
an RPM for all maven builds.
Initial priority has been the packaging of
daemons and libraries.
RPM Archetype
An RPM Archetype that
provides a plugin baseline
configuration will be distributed along side
the plugin. This way the amount of effort
required to generate JPackage compliant
RPM is minimized.
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.
In the configuration section for the JPackage
RPM plugin in the ApacheInstaller project
(Inside the pom.xml file) we would specify the
packaging target being the ApacheDirectoryServer
using the project's artifactId and group id.
If the ApacheDirectoryServer project that the
configuration points to is a parent project,
then the JPackage RPM Plugin will generate
RPMs for all the children of that project.
This does require further configuration
in terms of the types of projects
that the child projects are.
For instance some of them may just be libraries
and others may be servers.
JPackage RPM Plugin Configuration
The plugin will support specific
RPM generation cases.
For instance 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.
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
- Requirements
The plugin requires that
the project that is its target
generate a .gz source archive and
place it in the maven local maven
repository.
- Steps
The plugin pulls the source archive
from the repository and places it in the
rpm build environment's SOURCE folder.
It then generates the spec file
and puts it in the SPEC folder
of the RPM build environment.
It then builds the RPM according
to the instructions in the generated
spec file.
Plugin Architecture
- Spec file generation
A JET (Java Emitter Template) template supports
the generation of the spec file.
There will be one template for each RPM case.
Thus daemons will have a template specific
to daemon RPM generation, etc.
See http://www.eclipse.org/emft/projects/jet/
- POM 2 Spec mapping
The plugin sources as many parameters
as possible from the target project's
pom.xml file.
The parameters that it sources can
be overridden in the configuration
of the plugin.
In order to map the pom to the spec
annotations have been placed in the
maven pom xml schema indicating
how maven pom elements map to the
spec file.
Thus the plugin uses the schema
to for as the source of the pom 2 spec
map.
http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd
-------------------------------------------------------------------------
POM 2 Spec Mapping Start
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:jpp="http://jpackage.org/maven/plugins/">
<xsd:element name="name" type="xsd:string">
<xsd:annotation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:header>name</jpp:header>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
<xsd:element name="version" type="xsd:string">
<xsd:annotation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:header>Version</jpp:header>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
<xsd:element name="licenses" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
Maven supports many license elements,
so as a rule we could just grab the first one,
or concatenate the licenses into a string.
</xsd:documentation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:header>License</jpp:header>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
<xsd:element name="dependencies" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
Dependencies with the
scope attribute set to runtime
should map to the Requires Header.
Dependencies with
scope attribute set to compile
should map to the BuildRequires Header
TODO - Remember to put something
about the (post) thing on
Requires...
</xsd:documentation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:header>Requires</jpp:header>
<jpp:depends>//dependency@scope='runtime'</jpp:depends>
</jpp:specmapping>
<jpp:specmapping>
<jpp:header>BuildRequires</jpp:header>
<jpp:depends>//dependency@scope='compile'</jpp:depends>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
<xsd:element name="dependencies" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
</xsd:documentation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:header>BuildRequires</jpp:header>
<jpp:depends>BuildRequires</jpp:depends>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
<xsd:element name="url" type="xsd:string">
<xsd:annotation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:header>url</jpp:header>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
</xsd:schema>
<xsd:element name="description" type="xsd:string">
<xsd:annotation>
<xsd:documentation source="version">
Maybe the Maven POM description should map to
to the Summary header.
</xsd:documentation>
<xsd:appinfo>
<jpp:specmapping>
<jpp:section>%description</jpp:section>
</jpp:specmapping>
</xsd:appinfo>
</xsd:annotation>
</xsd:element>
</xsd:schema>
...
--------------------------
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}/%{name}
----------------------------------------------------------------------------
** Configuration Source
InstallFile.name >> confdir
InstallFile.value >> %{_sysconfdir}/%{name}
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 %{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) %{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) %{appdir}
----------------------------------------------------------------------------
** 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) %{confdir}/workers2.properties.minimal
----------------------------------------------------------------------------
** Configuration Source
InstallFile.isConfiguration = true >> %config(noreplace)
InstallFile.value >> %{confdir}/workers2.properties.minimal
** JPackage Convention
** Notes and Related Concepts
* Mark Documentation Files
** Example
----------------------------------------------------------------------------
%doc %{_javadocdir}/%{name}-servlet-%{servletspec}-api-%{version}
----------------------------------------------------------------------------
** Configuration Source
InstallFile.isDocumentation = true >> %doc
InstallFile.value >> %{_javadocdir}/%{name}-servlet-%{servletspec}-api-%{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%{version}/src/%{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%{version}/src/%{packdname}.tar.gz
** JPackage Convention
Suggestions:
protocol + path + artifactId + version + "." + archiveType
** Notes and Related Concepts
* Set the Patch Headers
** Example
----------------------------------------------------------------------------
Patch0: %{name}-%{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/%{name}-%{version}
%setup -q -c -T -a 0
cd %{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.
.
|