directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ole Ersoy <ole_er...@yahoo.com>
Subject Update on Maven JPackage RPM Plugin
Date Sun, 05 Nov 2006 01:17:18 GMT
Hey Guys,

Here's the latest design documentation on the 
JPackage RPM Plugin.

It's written in Maven APT format, which I need to
convert over to a wiki format.

I'm having company from out of town for a week, so
things will be slow, which is why I'm sending this out
as is.

I'll paste it below, and it's also here on the Apache
Wiki (But looks a little...ok very...wacked because
it's written in APT format):

http://cwiki.apache.org/confluence/display/DIRxSRVx11/JPackage+Maven+RPM+Plugin

					-------------------------------------------
       	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.
     
...Gotta clean up this more before I include....


 
____________________________________________________________________________________
We have the perfect Group for you. Check out the handy changes to Yahoo! Groups 
(http://groups.yahoo.com)


Mime
View raw message