rpm-maven-plugin
http://mojo.codehaus.org/rpm-maven-plugin/usage.html
Usage Scenarios
Listed below are the various scenarios where the RPM plugin can be used along with the proper way to configure the project(s) involved.
RPM on Demand
In this scenario, an RPM is generated from the project on demand by executing the goal "rpm:rpm" within a project. The project itself may be configured to produce any sort of packaging, since the RPM is not the primary artifact produced by the project.
If you want the project's artifacts packaged in the RPM, you must generate the RPM as a side effect of the standard lifecycle.
Things which do not work as I envision the 1.0 release working:
- If this goal is run on a project with modules, it will run the "rpm:rpm" goal on each module, rather than packaging the modules into a single RPM.
RPM as Side Effect
In this scenario, an RPM is generated from the project whenever the project is packaged. This must be done whenever the project's primary artifact is intended to be part of the RPM package but can be done anytime. To set up this configuration, include the following lines in the plugin definition in the project's POM file (see the sample configuration for an example of this):
<executions>
<execution>
<goals>
<goal>rpm</goal>
</goals>
</execution>
</executions>
RPM as Secondary Artifact
In this scenario, the rpm is not the primary artifact, but will be deployed as a secondary artifact.
<executions>
<execution>
<goals>
<goal>attached-rpm</goal>
</goals>
</execution>
</executions>
RPM as Primary Artifact
In this scenario, the RPM is the primary artifact of the project and is created by executing the phase "package" within the project. If properly configured, this allows the user to execute "mvn package" on a top-level project (which has the items to build and the RPM project as modules) and have Maven package the items to build into jars, wars, ears, etc. and them assemble the RPM of those items for distribution.
The packaging value should be set to "rpm".
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd ">
<modelVersion>4.0.0</modelVersion>
...
<packaging>rpm</packaging>
...
</project>
The extensions tag for this plugin should be marked true.
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>rpm-maven-plugin</artifactId>
<version>2.1-alpha-2</version>
<extensions>true</extensions>
...
</plugin>
</plugins>
</build>
＝＝＝＝＝＝＝＝＝＝＝＝＝
http://mojo.codehaus.org/rpm-maven-plugin/params.html
Identification Parameters
The parameters described in this page provide the identification of the RPM package. This information will be present in the package file and can be viewed with the "rpm -i" command.
version
The version number to use for the RPM package. By default, this is the project version. This value cannot contain a dash (-) due to contraints in the RPM file naming convention. Any specified value will be truncated at the first dash.
changelogFile
The file whose content will be put after %changelog in SPEC file. The content will not be validated and must follow the syntax for RPM:
* [dow mon dd yyyy] [packager [email address]] [RPM version] -list of changes
The list of changes can be as long as is necessary, but this is intended to be a list of changes for the RPM itself and not for the package.
release
The release number of the RPM.
Beginning with release 2.0-beta-2, this is an optional parameter. By default, the release will be generated from the modifier portion of theproject version using the following rules:
- If no modifier exists, the release will be 1.
- If the modifier ends with SNAPSHOT, the timestamp (in UTC) of the build will be appended to end.
- All instances of '-' in the modifier will be replaced with'_'.
- If a modifier exists and does not end with SNAPSHOT,"_1" will be appended to end.
copyright
The copyright information for the RPM. This is a one-line identifier of the copyright, like "GPL".
distribution
A one-line string identifying the distribution of which this RPM is a part.
group
A string which identifies the software group for this package. This can be used by GUI tools to group packages for display. Check the RPM documentation (installed in/usr/share/doc/rpm-version/GROUPS on most Linuxes) for a list of current groups.
icon
The file (GIF or XPM) with an icon for the package. This can be used by GUI tools to display an icon for the package.
needarch
The target architecture for the rpm. The default value isnoarch.
For passivity purposes, a value of true orfalse will indicate whether the architecture of the build machine will be used. Any other value will set the target architecture of the rpm.
In general, this should only be necessary in the case of compiled code from languages such as C or C++, and should not be specified if the executable content of the package consists only of scripts (such as shell, perl, or python) and/or Java code.
This can be used in conjunction with Source targetArchitecture to flex the contents of the rpm based on the architecture.
targetOS
The target os for building the RPM. By default, this will be populated to the System propertyos.name.
This can be used in conjunction with Source targetOSName to flex the contents of the rpm based on operating system.
targetVendor
The target vendor for building the RPM. By default, this will be populated to the result ofrpm -E %{_host_vendor}.
packager
The name of the person or group which is creating the package. By default, this will be taken from the name specified in the POM's organization information.
Operation Parameters
The parameters described in this page control the operation of the plugin.
workarea
The directory to use to build the RPM. By default, this is a directory namedrpm in the project's build directory.
NOTE: The absolute path to the workareaMUST NOT have a space in any of the directory names.
Beginning with release 2.0-beta-3, sub-directories will be created within the workarea for each execution of the plugin within a life cycle.
defineStatements
A list of %define statements that should be included in the top of the spec file
<plugin> ... <configuration> ... <defineStatements> <defineStatement>_unpackaged_files_terminate_build 0</defineStatement> </defineStatements> ... </configuration> ...</plugin>
Mapping Parameters
The parameters described in this page specify the mapping between the files and directories that exist in the project and the files and directories installed when the RPM package is installed on a system. The RPM build program requires one mapping element for each file to be installed. If the mapping element points to a directory the RPM build program will use the specifications of the mapping for every file in the entire tree starting at the specified directory.
The set of parameters which define a single mapping are contained within amapping tag. The set of allmapping tags are contained within amappings tag. A minimal mapping configuration looks like:
<plugin> ... <configuration> ... <mappings> <mapping> <directory>/tmp</directory> </mapping> </mappings> ... </configuration> ...</plugin>
directory
(required)This is the directory where the files in this mapping will be installed when the package is installed. This value must start with/.
configuration
If present or populated with the value true, the files in this mapping are marked as configuration files. These files get special treatment during package installation to ensure that local changes to the configuration are not lost.
If populated with any value other than false, the value will be used as a modifier to the%config declaration in the spec file. As an example, "<configuration>noreplace</configuration>", would lead to%config(noreplace) being generated in the spec file.
documentation
If given the value true, the file(s) are marked as documentation files. The RPM command installs documentation files into a directory (usually under/usr/share/doc) named the same as the RPM package.
filemode
(recommended)This is UNIX permissions (file mode) to assign to the files when installed. This value consists of three octal digits representing the access for the owner, the group, and the world. Each digit represents the access allowed and is the sum of 4 for read, 2 for write, and 1 for execute. A common value to use is "644" which provides the owner read/write access and read-only access to everyone else. For more information on this subject, readFile Security, section 3.4 of the Introduction to Linux maintained by the Linux Documentation Project. If not specified, the files retain the filemode assigned to them when copied to the RPM work area.
If none of the file attributes (filemode, username, and groupname) are populated, the defaults (defaultFileMode,defaultUsername,defaultGroupname, anddefaultDirmode) will be used.
username
(recommended)This is the UNIX username to assign to the files when installed. If the named user does not exist when the package is installed, the userroot will be used. If not specified, the files will be owned by the user used to create the package.
If none of the file attributes (filemode, username, and groupname) are populated, the defaults (defaultFileMode,defaultUsername,defaultGroupname, anddefaultDirmode) will be used.
groupname
(recommended)This is the UNIX groupname to assign to the files when installed. If the named group does not exist when the package is installed, the grouproot will be used. If not specified, the files will be owned by the group used to create the package.
If none of the file attributes (filemode, username, and groupname) are populated, the defaults (defaultFileMode,defaultUsername,defaultGroupname, anddefaultDirmode) will be used.
directoryIncluded
If the value is true then the attribute string will be written for thedirectory if thesources identify all of the files in the directory (that is, no other mapping contributed files to thedirectory). This is the default behavior.
If the value is false, the files in this mapping will be listed individually in the spec file.
recurseDirectories
Indicates if sub-directories contained in the sources should be explicitly listed in %files. This includes listing thedestination ifdirectoryIncluded is true.
artifact
If present, then the project's artifact should be included in this mapping. This file will be installed in the directory specified in thedirectory parameter. If the project creates more than one artifact and you do not want all of the artifacts installed with this mapping, you need to specify the classifier(s) which should be included with this mapping; this is done by including a "<classifiers>" tag which holds one or more "<classifier>" tags holding a single classifier (use "<classifier></classifier>" for the primary project artifact).
dependency
If present, then some or all of the project's transitive runtime dependencies should be included in this mapping. The dependencies to be included are those which are specified withcompile orruntime scope, and all of the dependencies of those artifacts which are similarly defined. These files will be installed in the directory specified in thedirectory parameter.
If the tag is empty ("<dependency/>"), then all dependencies will be included in the mapping. To limit the dependencies to include in the mapping, you must specify "<includes>", "<excludes>", or both. Each of these elements contains a list of items; for example, the "<includes>" element will have a list of "<include>" items. Each item specifies a single dependency to include or exclude with a string in one of the following two formats:
- "group:artifact" which specifies the group ID and artifact ID of the dependency; the version and type are taken from the actual dependency definition in the project
- "group:artifact:versionrange" which extends the above to limit the specification to particular versions of the artifact; note that this will not cause a different version of the dependency to be packaged than what was used to build the project
If no include items are specified, then all dependencies not explicitly excluded are included.
sources
The location(s) to find the files to be packaged. If no sources are specified, thedirectory will be created using the mapping specification but no contents will be selected for packaging; this allows an empty directory to be specified. The content of this parameter is discussed in aseparate file.
softlinkSources
Provides the opportunity to link to item(s) in the package. The location, therefore, must be a location that exists after all the mappings with traditional sources have been created in thebuildroot directory.
Source Parameters
The parameters described in this page specify the set of files to be copied into the work area for inclusion in the RPM package. By default, files which are related to source control and editor temporary files are excluded.
The set of parameters which define a single file set are contained within asource tag. The set of all source tags are contained within a sources tag. A minimal source configuration looks like:
<plugin> ... <configuration> ... <mappings> <mapping> ... <sources> <source> <location>target/classes</location> </source> </sources> ... </mapping> </mappings> ... </configuration> ...</plugin>
location
(required)The file or directory to include. If a directory is specified, all files and subdirectories are also included. If the path does not start with/, it is taken to be relative to the project's base directory.
Note that the entire source specification is optional, but each source specification that is present must have this parameter.
noDefaultExcludes
If given the value true, the default exclusions are not used.
includes
Contains one or more include elements with a wildcard filename expression which identifies the files to be included.
excludes
Contains one or more exclude elements with a wildcard filename expression which identifies the files to be excluded. IfnoDefaultExcludes is not specified, the default exclusions are added to this list.
destination
(optional)If the location is a file (not a directory), this is the name of the file in the rpm. If this value is not provided, the name of thefile will be used.
filter
(optional)Will filter the file(s) and replace special values with properties.
targetArchitecture
(optional)If this is populated, the contents defined by this source will only be included if the value for targetArchitecture matches the target architecture of the rpm.
Beginning with 2.0-beta-3, this is a regular expression. In order to provide backward compatibility, both the architecture (defined for MOJO) and this value will be converted to lower case to make comparison case insensitive.
This can be used to flex the contents of the rpm based on thearchitecture:
<build> <plugins> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>rpm-maven-plugin</artifactId> ... <configuration> ... <needarch>true</needarch> ... <mapping> ... <sources> <source> <location>src/main/native/x86_64</location> <targetArchitecture>x86_64</targetArchitecture> </source> <source> <location>src/main/native/i586</location> <targetArchitecture>i586</targetArchitecture> </source> </sources> ... </mapping> ... </configuration> </plugin> ... </plugins> ... <build>
targetOSName
(optional)A regular expression that, if populated, indicates that the files defined are only applicable if the expression matches theMOJO.targetOS value.
<build> <plugins> <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>rpm-maven-plugin</artifactId> ... <configuration> <mapping> ... <sources> <source> <location>src/main/native/x86_64</location> <targetArchitecture>x86_64</targetArchitecture> </source> <source> <location>src/main/native/x86</location> <targetArchitecture>i.86</targetArchitecture> </source> </sources> ... </mapping> ... </configuration> </plugin> ... </plugins> ... <build>
Advanced Parameters
The parameters described in this page are parameters which enable advanced RPM features. Before using these parameters, it ishighly recommended that you readMaximum RPM to gain an understanding of what these parameters do.
RPM Package Dependency Management
These parameters relate to the dependencies between RPM packages, not to the dependencies required to build the RPM package contents.
There are three RPM spec file tags related to dependency management:
- provides defines a virtual package which is provided by the package being built
- requires identifies a package that is required to be installed for the package being built to operate correctly
- conflicts identifies a package which must not be installed if the package being built is installed
All three of these tags can appear multiple times in the spec file. To configure these tags in the plugin configuration, specify an element for each instance of the tag in the spec file; the content of the element is the exact text to be placed in the spec file. Please be careful to ensure that version comparison specifications such as<and > are properly specified in the XML file. Here is an example:
<provides> <provide>dump</provide></provides><requires> <require>trash-truck > 1.0</require></requires><conflicts> <conflict>incinerator</conflict></conflicts>
Relocation
If you specify the prefix parameter to the RPM plugin, you can create a package that can be installed in a user-specified location. Before doing this, read and understand Maximum RPMChapter 15 since there are a number of kinks and quirks that must be addressed.
Scripts
There are a number of scripts that can be included in the RPM package which are executed as part of the installation, removal, or verification of the package.
Each of the scripts can be configured as a Scriptlet, which allows the content of the script to be provided either as a String or File. If both parameters are specified for a script, the external file will be ignored. Before writing scripts for RPM packages, understand thescript docs in Maximum RPM since the operation of the scripts must be done correctly or major problems can occur while installing or removing the package.
Here are examples of passing the content of the script in the pom (using<script>) and in a file (using<scriptFile>):
<prepareScriptlet> <script>echo "prepare"</script></prepareScriptlet><preinstallScriptlet> <scriptFile>/src/main/bin/preinstall.sh</scriptFile> <fileEncoding>utf-8</fileEncoding></preinstallScriptlet>
prepareScriptlet
This script specifies commands to prepare the build. It corresponds to the%prep tag in the spec file.
preinstallScriptlet
This script is run before the package is installed. It corresponds to the%pre tag in the spec file.
installScriptlet
This script is run as a part of installing the package. It corresponds to the%install tag in the spec file.
postinstallScriptlet
This script is run after the package is installed. It corresponds to the%post tag in the spec file.
preremoveScriptlet
This script is run before the package is removed. It corresponds to the%preun tag in the spec file.
postremoveScriptlet
This script is run after the package is removed. It corresponds to the%postun tag in the spec file.
verifyScriptlet
This script is run when the package is being verified. It corresponds to the%verifyScript tag in the spec file.
cleanScriptlet
This script is run after the package is installed to clean up installation files. It corresponds to the%clean tag in the spec file.
pretransScriptlet
This script is run at the beginning of the transaction. It corresponds to the%pretrans tag in the spec file.
posttransScriptlet
This script is run at the end of the transaction. It corresponds to the%posttrans tag in the spec file.
Triggers
Triggers are scripts which can be included in an RPM package to execute based on the action of other packages in a system. Before writing triggers for RPM packages, understand thetriggers in the RPM documentation since the operation of the scripts must be done correctly or major problems can occur while installing or removing other packages.
Signatures
RPM packages may be signed using GPG or PGP. Currently the plugin only supports generating GPG signatures.
keyname
This parameter sets the name of the GPG key used to sign the package, and also turns on the signature. Setting this parameter is equivalent to defining the%_gpg_name macro and adding the--sign option to rpmbuild.
keyPassphrase
This parameter sets the passphrase for the key to sign the rpm. The use of this attribute requiresexpect to be available on the PATH.
==========
example:
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>rpm-maven-plugin</artifactId>
<version>2.1x</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>rpm</goal>
</goals>
</execution>
</executions>
<configuration>
<release>uscpstp</release>
<copyright>2012, Citigroup</copyright>
<distribution>ShortTerm etrading Platform</distribution>
<group>Application</group>
<packager>Citigroup</packager>
<version>${project.version}</version>
<prefix>${rpm-install-location}</prefix>
<mappings>
<mapping>
<directory>${rpm-install-location}/bin</directory>
<filemode>755</filemode>
<username>${rpm-user}</username>
<groupname>${rpm-group}</groupname>
<sources>
<source>
<location>${project.build.directory}/bin</location>
<includes>
<include>*.*sh</include>
</includes>
</source>
</sources>
</mapping>
<mapping>
<directory>${rpm-install-location}/config</directory>
<filemode>755</filemode>
<username>${rpm-user}</username>
<groupname>${rpm-group}</groupname>
<sources>
<source>
<location>${project.build.directory}/config</location>
</source>
</sources>
</mapping>
<mapping>
<directory>${rpm-install-location}/lib</directory>
<filemode>755</filemode>
<username>${rpm-user}</username>
<groupname>${rpm-group}</groupname>
<dependency />
<sources>
<source>
<location>
${project.build.directory}/lib/${project.artifactId}-${project.version}.jar
</location>
</source>
</sources>
</mapping>
<mapping>
<directory>${rpm-install-location}/pkg</directory>
<filemode>755</filemode>
<username>${rpm-user}</username>
<groupname>${rpm-group}</groupname>
<sources>
<source>
<location>${project.build.directory}/pkg</location>
<includes>
<include>*.sh</include>
</includes>
</source>
</sources>
</mapping>
</mappings>
<preinstallScript>src/main/scripts/preinstall.sh</preinstallScript>
<postinstall><![CDATA[$RPM_INSTALL_PREFIX/pkg/postinstall.sh < /dev/tty]]></postinstall>
<postremoveScript>src/main/scripts/postuninstall.sh</postremoveScript>
</configuration>
</plugin>