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)
