.. _rpm-plugin: Rpm Plugin ========== RedHat ``rpm`` files support a number of very advanced features. To take full advantage of this environment, it's best to understand how the ``rpm`` package system works. `How to create an RPM package`_ on the fedora project wiki is a good tutorial, but it focuses on building packages from *source.* The sbt-native-packager assumes that SBT has built your source and generated *binary* packages. .. note:: The rpm plugin depends on the :ref:`linux-plugin`. .. _How to create an RPM package: http://fedoraproject.org/wiki/How_to_create_an_RPM_package Requirements ------------ You need the following applications installed * rpm * rpm-build Build ----- .. code-block:: bash sbt rpm:packageBin Required Settings ~~~~~~~~~~~~~~~~~ A rpm package needs some mandatory settings to be valid. Make sure you have these settings in your build: .. code-block:: scala rpmVendor := "typesafe" 1.0 or higher ~~~~~~~~~~~~~ Enables the rpm plugin .. code-block:: scala enablePlugins(RpmPlugin) 0.8 or lower ~~~~~~~~~~~~ For this versions rpm packaging is automatically activated. See the :doc:`Getting Started ` page for information on how to enable sbt native packager. Configuration ------------- Settings and Tasks inherited from parent plugins can be scoped with ``Rpm``. .. code-block:: scala linuxPackageMappings in Rpm := linuxPackageMappings.value Settings -------- Informational Settings ~~~~~~~~~~~~~~~~~~~~~~ ``packageName in Rpm`` The name of the package for the rpm. Its value defines the first component of the rpm file name (``packageName-version-rpmRelease.packageArchitecture.rpm``), as well as the ``Name:`` tag in the spec file. Its default value is drawn from ``packageName in Linux``. ``version in Rpm`` The version of the package for rpm. Takes the form ``x.y.z``, and note that there can be no dashes in this version string. It defines the second component of the rpm file name (``packageName-version-rpmRelease.packageArchitecture.rpm``), as well as the ``Version:`` tag in the spec file. Its default value is drawn from the project defined ``version``. ``rpmRelease`` The release number is the package's version. When the sofware is first packaged at a particular version, the release should be ``"1"``. If the software is repackaged at the same version, the release number should be incremented, and dropped back to ``"1"`` when the software version is new. Its value defines the third component of the rpm file name (``packageName-version-rpmRelease.packageArchitecture.rpm``), as well as the ``Release:`` tag in the spec file. Its default value is ``"1"``. ``packageArchitecture in Rpm`` The build architecture for the binary rpm. Its value defines the fourth component of the rpm file name (``packageName-version-rpmRelease.packageArchitecture.rpm``), as well as the ``BuildArch:`` tag in the spec file. Its default value is ``"noarch"``. ``packageSummary in Rpm`` A brief, one-line summary of the package. Note: the summary **must not** contain line separators or end in a period. Its value defines the ``Summary:`` tag in the spec file, and its default value is drawn from ``packageSummary in Linux``. ``packageDescription in Rpm`` A longer, multi-line description of the package. Its value defines the ``%description`` block in the spec file, and its default value is drawn from ``packageDescription in Linux``. ``rpmVendor`` The name of the company/user generating the RPM. ``rpmUrl`` A url associated with the software in the RPM. ``rpmLicense`` The license associated with software in the RPM. ``rpmEpoch`` The epoch is the most significant number used when resolving different versions for the same RPM. For a given package, packages with the highest epoch will be used, and in the event of a tie it will fall back to comparing the version and release. ``artifactPath in (Rpm, packageBin)`` The location of the generated RPM. Dependency Settings ~~~~~~~~~~~~~~~~~~~ ``rpmAutoreq`` Enable or disable the automatic processing of required packages. Takes the form ``"yes"`` or ``"no"``, defaults to ``"yes"``. Defines the ``AutoReq:`` tag in the spec file. ``rpmRequirements`` The RPM packages that are required to be installed for this RPM to work. ``rpmAutoprov`` Enable or disable the automatic processing of provided packages. Takes the form ``"yes"`` or ``"no"``, defaults to ``"yes"``. Defines the ``AutoProv:`` tag in the spec file. ``rpmProvides`` The RPM package names that this RPM provides. ``rpmPrerequisites`` The RPM packages this RPM needs before installation ``rpmObsoletes`` The packages this RPM allows you to remove ``rpmConflicts`` The packages this RPM conflicts with and cannot be installed with. ``rpmSetarch[SettingKey[Option[String]]]`` Run rpmbuild via Linux ``setarch`` command. Use this for cross-platform builds. Meta Settings ~~~~~~~~~~~~~ ``rpmPrefix`` The path passed set as the base for the revocable package ``rpmChangelogFile`` External file to be imported and used to generate the changelog of the RPM. Scriptlet Settings ~~~~~~~~~~~~~~~~~~ ``maintainerScripts in Rpm`` Contains the scriptlets being injected into the specs file. Currently supports all previous scriptlets: ``%pretrans``, ``%pre``, ``%verifyscript%``, ``%post``, ``%posttrans``, ``%preun`` and ``%postun`` ``rpmBrpJavaRepackJars`` appends ``__os_install_post`` scriptlet to ``rpmPre`` avoiding jar repackaging SystemV Start Script Settings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``rpmDaemonLogFile`` File name of the log generated by application daemon. Tasks ----- The Rpm plugin support grants the following commands: ``rpm:package-bin`` Generates the ``.rpm`` package for this project. ``rpm:rpm-lint`` Generates the ``.rpm`` file and runs the ``rpmlint`` command to look for issues in the package. Useful for debugging. Customize --------- Rpm Prefix ~~~~~~~~~~ The rpm prefix allows you to create a relocatable package as defined by http://www.rpm.org/max-rpm/s1-rpm-reloc-prefix-tag.html. This optional setting with a handful of overrides to scriptlets and templates will allow you to create a working java_server archetype that can be relocated in the file system. Example Settings: .. code-block:: scala defaultLinuxInstallLocation := "/opt/package_root", rpmPrefix := Some(defaultLinuxInstallLocation), linuxPackageSymlinks := Seq.empty, defaultLinuxLogsLocation := defaultLinuxInstallLocation + "/" + name rpmChangelogFile ~~~~~~~~~~~~~~~~ The rpmChangelogFile property allows you to set a source that will be imported and used on the RPM generation. So if you use rpm commands to see the changelog it brings that information. You have to create the content in the changelog file using the RPM conventions that are available here http://fedoraproject.org/wiki/Packaging:Guidelines#Changelogs. Example Settings: .. code-block:: scala changelog := "changelog.txt" rpmChangelogFile := Some(changelog) .. code-block:: bash * Sun Aug 24 2014 Team - 1.1.0 -Allow to login using social networks * Wed Aug 20 2014 Team - 1.0.1 -Vulnerability fix. * Tue Aug 19 2014 Team - 1.0.0 -First version of the system Scriptlet Changes ~~~~~~~~~~~~~~~~~ Changing scriptlets can be done in two ways: 1. Override the ``maintainerScripts in Rpm``, or 2. Place new scripts in the ``src/rpm/scriptlets`` To **override the ``maintainerScripts in Rpm``** you can override the command string explicitly, create a command string using appends and/or replacements, or even get a command string from a file source. For example: .. code-block:: scala // overriding import RpmConstants._ maintainerScripts in Rpm := Map( Pre -> Seq("""echo "pre-install""""), Post -> Seq("""echo "post-install""""), Pretrans -> Seq("""echo "pretrans""""), Posttrans -> Seq("""echo "posttrans""""), Preun -> Seq("""echo "pre-uninstall""""), Postun -> Seq("""echo "post-uninstall"""") ) // appending with strings and replacements import RpmConstants._ maintainerScripts in Rpm := maintainerScriptsAppend((maintainerScripts in Rpm).value)( Pretrans -> "echo 'hello, world'", Post -> s"echo 'installing ${(packageName in Rpm).value}'" ) // appending from a different file import RpmConstants._ maintainerScripts in Rpm := maintainerScriptsAppendFromFile((maintainerScripts in Rpm).value)( Pretrans -> (sourceDirectory.value / "rpm" / "pretrans"), Post -> (sourceDirectory.value / "rpm" / "posttrans") ) The helper methods can be found in `MaintainerScriptHelper Scaladocs`_. To **place new scripts in the src/rpm/scriptlets folder** you simply put the commands into the appropriate scriptlet file. (The scriptlet file names can be found in the `RPM Scaladocs`_.) ``src/rpm/scriptlets/preinst`` .. code-block:: bash ... echo "PACKAGE_PREFIX=${RPM_INSTALL_PREFIX}" > /etc/sysconfig/${{app_name}} ... ``src/rpm/scriptlets/preun`` .. code-block:: bash ... rm /etc/sysconfig/${{app_name}} ... Using scriptlet files like this *will override all previous contents.* Scriptlet Migration from 1.0.x ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before .. code-block:: scala rpmPostun := rpmPost.value.map { content => s"""|$content |echo "I append this to the current content |""".stripMargin }.orElse { Option("""echo "There wasn't any previous content" """.stripMargin) } After .. code-block:: scala // this gives you easy access to the correct keys import RpmConstants._ // in order to append you have to pass the initial maintainerScripts map maintainerScripts in Rpm := maintainerScriptsAppend((maintainerScripts in Rpm).value)( Pretrans -> "echo 'hello, world'", Post -> s"echo 'installing ${(packageName in Rpm).value}'" ) Jar Repackaging ~~~~~~~~~~~~~~~ RPM repackages jars by default in order to optimize jars. Repacking is turned off by default. In order to enable it, set: .. code-block:: scala rpmBrpJavaRepackJars := true Note that this *appends* content to your ``Pre`` definition, so make sure not to override it. For more information on this topic follow these links: * `issue #195`_ * `pullrequest #199`_ * `OpenSuse issue`_ .. _issue #195: https://github.com/sbt/sbt-native-packager/issues/195 .. _pullrequest #199: https://github.com/sbt/sbt-native-packager/pull/199 .. _OpenSuse issue: https://github.com/sbt/sbt-native-packager/issues/215 .. _RPM Scaladocs: http://www.scala-sbt.org/sbt-native-packager/latest/api/#com.typesafe.sbt.packager.rpm.RpmPlugin$$Names$ .. _MaintainerScriptHelper Scaladocs: http://www.scala-sbt.org/sbt-native-packager/latest/api/#com.typesafe.sbt.packager.MaintainerScriptHelper$ Marking config files as ``noreplace`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, rpm replaces config files on disk when the content has changed between two version. Often, this is not desirable as configurations are often customized and should not change during updates. rpm provides a means to turn of the default behaviour by marking config files as ``noreplace`` in the spec file. In order to enable this for the build, we provide a helper method that can be used to modify all config file mappings: .. code-block:: scala linuxPackageMappings in Rpm := configWithNoReplace((linuxPackageMappings in Rpm).value) This will mark all config files as ``noreplace`` and prevent them from being changed during updates. Please note that the ``linuxPackageMappings`` are scoped to the ``Rpm`` plugin. This is necessary in order to catch all config files relevant to the rpm package and mark them correctly.