Red Hat Software Collections 3.x

Transcription

1 Red Hat Software Collections 3.x Packaging Guide A guide to packaging Software Collections for Red Hat Enterprise Linux Last Updated:

2

3 Red Hat Software Collections 3.x Packaging Guide A guide to packaging Software Collections for Red Hat Enterprise Linux Petr Kovář Red Hat Customer Content Services pkovar@redhat.com

4 Legal Notice Copyright 2018 Red Hat, Inc. This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. The OpenStack Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract The Packaging Guide provides an explanation of Software Collections and details how to build and package them. Developers and system administrators who have a basic understanding of software packaging with RPM packages, but who are new to the concept of Software Collections, can use this Guide to get started with Software Collections.

5 Table of Contents Table of Contents. CHAPTER INTRODUCING SOFTWARE COLLECTIONS WHY PACKAGE SOFTWARE WITH RPM? WHAT ARE SOFTWARE COLLECTIONS? ENABLING SUPPORT FOR SOFTWARE COLLECTIONS INSTALLING A SOFTWARE COLLECTION LISTING INSTALLED SOFTWARE COLLECTIONS ENABLING A SOFTWARE COLLECTION Running an Application Directly Running a Shell with Multiple Software Collections Enabled Running Commands Stored in a File LISTING ENABLED SOFTWARE COLLECTIONS UNINSTALLING A SOFTWARE COLLECTION 9. CHAPTER PACKAGING SOFTWARE COLLECTIONS CREATING YOUR OWN SOFTWARE COLLECTIONS THE FILE SYSTEM HIERARCHY THE SOFTWARE COLLECTION ROOT DIRECTORY THE SOFTWARE COLLECTION PREFIX SOFTWARE COLLECTION PACKAGE NAMES SOFTWARE COLLECTION SCRIPTLETS PACKAGE LAYOUT Metapackage Creating a Metapackage 15 Example of the Metapackage SOFTWARE COLLECTION MACROS Macros Specific to a Software Collection Macros Not Specific to a Software Collection The nfsmountable Macro COMMONLY USED PATH REDEFINITIONS Language-specific Path Redefinitions Other Path Redefinitions CONVERTING A CONVENTIONAL SPEC FILE Example of the Converted Spec File Converting Tags and Macro Definitions Converting Subpackages Converting RPM Scripts Software Collection Automatic Provides and Requires and Filtering Support Software Collection Macro Files Support Software Collection Shebang Support Making a Software Collection Depend on Another Software Collection UNINSTALLING ALL SOFTWARE COLLECTION DIRECTORIES BUILDING A SOFTWARE COLLECTION Rebuilding a Software Collection without build Subpackages Avoiding debuginfo File Conflicts 30. CHAPTER ADVANCED TOPICS USING SOFTWARE COLLECTIONS OVER NFS Changed Directory Structure and File Ownership Registering and Deregistering Software Collections Using (de)register Scriptlets in a Software Collection Metapackage CONVERTING SOFTWARE COLLECTION SCRIPTLETS INTO ENVIRONMENT MODULES PROVIDING SYSPATHS SUBPACKAGES 36 1

6 Packaging Guide Naming syspaths Subpackages Files Included in syspaths Subpackages Limitations of syspaths Wrappers Symbolic Links in syspaths Subpackages Services Without a Prefix 3.4. MANAGING SERVICES IN SOFTWARE COLLECTIONS Configuring an Environment for Services 3.5. SOFTWARE COLLECTION LIBRARY SUPPORT Using a Library Outside of the Software Collection Prefixing the Library Major soname with the Software Collection Name Software Collection Library Support in Red Hat Enterprise Linux SOFTWARE COLLECTION.PC FILES SUPPORT 3.7. SOFTWARE COLLECTION MANPATH SUPPORT 3.8. SOFTWARE COLLECTION CRONJOB SUPPORT 3.9. SOFTWARE COLLECTION LOG FILE SUPPORT SOFTWARE COLLECTION LOGROTATE SUPPORT SOFTWARE COLLECTION /VAR/RUN/ FILES SUPPORT SOFTWARE COLLECTION LOCK FILE SUPPORT Preventing Programs from Running Concurrently Software Collection SysV init Lock File Support SOFTWARE COLLECTION CONFIGURATION FILES SUPPORT SOFTWARE COLLECTION KERNEL MODULE SUPPORT SOFTWARE COLLECTION SELINUX SUPPORT SELinux Support in Red Hat Enterprise Linux DIFFERENCES BETWEEN RED HAT ENTERPRISE LINUX 6 AND The %license Macro Missing runtime Subpackage Dependencies The scl-package() Provides CHAPTER EXTENDING RED.... HAT.... SOFTWARE COLLECTIONS PROVIDING AN SCLDEVEL SUBPACKAGE Creating an scldevel Subpackage Using an scldevel Subpackage in a Dependent Software Collection EXTENDING THE PYTHON27 AND RH-PYTHON35 SOFTWARE COLLECTIONS The vt191 Software Collection The python-versiontools Package Building the vt191 Software Collection Testing the vt191 Software Collection EXTENDING THE RH-RUBY23 SOFTWARE COLLECTION The rh-ror42 Software Collection The rh-ror42-rubygem-bcrypt Package Building the rh-ror42 Software Collection Testing the rh-ror42 Software Collection EXTENDING THE RH-PERL524 SOFTWARE COLLECTION The h2m144 Software Collection The help2man Package Building the h2m144 Software Collection Testing the h2m144 Software Collection 69. CHAPTER TROUBLESHOOTING SOFTWARE COLLECTIONS ERROR: LINE XX: UNKNOWN TAG: %SCL_PACKAGE SOFTWARE_COLLECTION_NAME SCL COMMAND DOES NOT EXIST UNABLE TO OPEN /ETC/SCL/PREFIXES/SOFTWARE_COLLECTION_NAME 70 2

7 Table of Contents 5.4. SCL_SOURCE: COMMAND NOT FOUND 70. APPENDIX A.... GETTING MORE INFORMATION A.1. RED HAT DEVELOPERS 71 A.2. INSTALLED DOCUMENTATION 71 A.3. ACCESSING RED HAT DOCUMENTATION 71. APPENDIX B.... REVISION HISTORY B.1. ACKNOWLEDGMENTS 74 3

8 Packaging Guide 4

9 CHAPTER 1. INTRODUCING SOFTWARE COLLECTIONS CHAPTER 1. INTRODUCING SOFTWARE COLLECTIONS This chapter introduces you to the concept and usage of Software Collections or SCLs for short WHY PACKAGE SOFTWARE WITH RPM? The RPM Package Manager (RPM) is a package management system that runs on Red Hat Enterprise Linux. RPM makes it easier for you to distribute, manage, and update software that you create for Red Hat Enterprise Linux. Many software vendors distribute their software via a conventional archive file (such as a tarball). However, there are several advantages in packaging software into RPM packages. These advantages are outlined below. With RPM, you can: Install, reinstall, remove, upgrade and verify packages. Users can use standard package management tools (for example Yum or PackageKit) to install, reinstall, remove, upgrade and verify your RPM packages. Use a database of installed packages to query and verify packages. Because RPM maintains a database of installed packages and their files, users can easily query and verify packages on their system. Use metadata to describe packages, their installation instructions, and so on. Each RPM package includes metadata that describes the package's components, version, release, size, project URL, installation instructions, and so on. Package pristine software sources into source and binary packages. RPM allows you to take pristine software sources and package them into source and binary packages for your users. In source packages, you have the pristine sources along with any patches that were used, plus complete build instructions. This design eases the maintenance of the packages as new versions of your software are released. Add packages to Yum repositories. You can add your package to a Yum repository that enables clients to easily find and deploy your software. Digitally sign your packages. Using a GPG signing key, you can digitally sign your package so that users are able to verify the authenticity of the package. For in-depth information on what is RPM and how to use it, see the Red Hat Enterprise Linux 7 System Administrator's Guide, or the Red Hat Enterprise Linux 6 Deployment Guide WHAT ARE SOFTWARE COLLECTIONS? With Software Collections, you can build and concurrently install multiple versions of the same software components on your system. Software Collections have no impact on the system versions of the packages installed by any of the conventional RPM package management utilities. Software Collections: 5

10 Packaging Guide Do not overwrite system files Software Collections are distributed as a set of several components, which provide their full functionality without overwriting system files. Are designed to avoid conflicts with system files Software Collections make use of a special file system hierarchy to avoid possible conflicts between a single Software Collection and the base system installation. Require no changes to the RPM package manager Software Collections require no changes to the RPM package manager present on the host system. Need only minor changes to the spec file To convert a conventional package to a single Software Collection, you only need to make minor changes to the package spec file. Allow you to build a conventional package and a Software Collection package with a single spec file With a single spec file, you can build both the conventional package and the Software Collection package. Uniquely name all included packages With Software Collection's namespace, all packages included in the Software Collection are uniquely named. Do not conflict with updated packages Software Collection's namespace ensures that updating packages on your system causes no conflicts. Can depend on other Software Collections Because one Software Collection can depend on another, you can define multiple levels of dependencies ENABLING SUPPORT FOR SOFTWARE COLLECTIONS To enable support for Software Collections on your system so that you can enable and build Software Collections, you need to have installed the packages scl-utils and scl-utils-build. If the packages scl-utils and scl-utils-build are not already installed on your system, you can install them by typing the following at a shell prompt as root: # yum install scl-utils scl-utils-build The scl-utils package provides the scl tool that lets you enable Software Collections on your system. For more information on enabling Software Collections, see Section 1.6, Enabling a Software Collection. The scl-utils-build package provides macros that are essential for building Software Collections. For more information on building Software Collections, see Section 2.12, Building a Software Collection. 6

11 CHAPTER 1. INTRODUCING SOFTWARE COLLECTIONS IMPORTANT Depending on the subscriptions available to your Red Hat Enterprise Linux system, you may need to enable the Optional channel to install the scl-utils-build package INSTALLING A SOFTWARE COLLECTION To ensure that a Software Collection is on your system, install the so-called metapackage of the Software Collection. Thanks to Software Collections being fully compatible with the RPM Package Manager, you can use conventional tools like Yum or PackageKit for this task. For example, to install a Software Collection with the metapackage named software_collection_1, run the following command: # yum install software_collection_1 This command will automatically install all the packages in the Software Collection that are essential for the user to perform most common tasks with the Software Collection. Software Collections allow you to only install a subset of packages you intend to use. For example, to use the Ruby interpreter from the rh-ruby23 Software Collection, you only need to install a package rhruby23-ruby from that Software Collection. If you install an application that depends on a Software Collection, that Software Collection will be installed along with the rest of the application's dependencies. For detailed information on Software Collection metapackages, see Section 2.7.1, Metapackage. For detailed information on Yum and PackageKit usage, see the Red Hat Enterprise Linux 7 System Administrator's Guide, or the Red Hat Enterprise Linux 6 Deployment Guide LISTING INSTALLED SOFTWARE COLLECTIONS To get a list of Software Collections that are installed on the system, run the following command: scl --list To get a list of installed packages contained within a specified Software Collection, run the following command: scl --list software_collection_ ENABLING A SOFTWARE COLLECTION The scl tool is used to enable a Software Collection and to run applications in the Software Collection environment. General usage of the scl tool can be described using the following syntax: scl action software_collection_1 software_collection_2 command If you are running a command with multiple arguments, remember to enclose the command and its arguments in quotes: 7

12 Packaging Guide scl action software_collection_1 software_collection_2 'command -- argument' Alternatively, use a -- command separator to run a command with multiple arguments: scl action software_collection_1 software_collection_2 -- command -- argument Remember that: When you run the scl tool, it creates a child process (subshell) of the current shell. Running the command again then creates a subshell of the subshell. You can list enabled Software Collections for the current subshell. See Section 1.7, Listing Enabled Software Collections for more information. You have to disable an enabled Software Collection first to be able to enable it again. To disable the Software Collection, exit the subshell created when enabling the Software Collections. When using the scl tool to enable a Software Collection, you can only perform one action with the enabled Software Collection at a time. The enabled Software Collection must be disabled first before performing another action Running an Application Directly For example, to directly run Perl with the --version option in the Software Collection named software_collection_1, execute the following command: scl enable software_collection_1 'perl --version' Alternatively, you can provide a syspaths subpackage that makes it more convenient to run commands in the Software Collection environment. For more information on syspaths subpackages, see Section 3.3, Providing syspaths Subpackages Running a Shell with Multiple Software Collections Enabled To run the Bash shell in the environment with multiple Software Collections enabled, execute the following command: scl enable software_collection_1 software_collection_2 bash The command above enables two Software Collections, named software_collection_1 and software_collection_ Running Commands Stored in a File To execute a number of commands, which are stored in a file, in the Software Collection environment, run the following command: cat cmd scl enable software_collection_1-8

13 CHAPTER 1. INTRODUCING SOFTWARE COLLECTIONS The command above executes commands, which are stored in the cmd file, in the environment of the Software Collection named software_collection_ LISTING ENABLED SOFTWARE COLLECTIONS To get a list of Software Collections that are enabled in the current session, print the $X_SCLS environment variable by running the following command: echo $X_SCLS 1.8. UNINSTALLING A SOFTWARE COLLECTION You can use conventional tools like Yum or PackageKit when uninstalling a Software Collection because Software Collections are fully compatible with the RPM Package Manager. For example, to uninstall all packages and subpackages that are part of a Software Collection named software_collection_1, run the following command: yum remove software_collection_1\* You can also use the yum remove command to remove the scl utility. For detailed information on Yum and PackageKit usage, see the Red Hat Enterprise Linux 7 System Administrator's Guide, or the Red Hat Enterprise Linux 6 Deployment Guide. 9

14 Packaging Guide CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS This chapter introduces you to packaging Software Collections CREATING YOUR OWN SOFTWARE COLLECTIONS In general, you can use one of the following two approaches to deploy an application that depends on an existing Software Collection: install all required Software Collections and packages manually and then deploy your application, or create a new Software Collection for your application. When creating a new Software Collection for your application: Create a Software Collection metapackage Each Software Collection includes a metapackage, which installs a subset of the Software Collection's packages that are essential for the user to perform most common tasks with the Software Collection. See Section 2.7.1, Metapackage for more information on creating metapackages. Consider specifying the location of the Software Collection root directory You are advised to specify the location of the Software Collection root directory by setting the %_scl_prefix macro in the Software Collection spec file. For more information, see Section 2.3, The Software Collection Root Directory. Consider prefixing the name of your Software Collection packages You are advised to prefix the name of your Software Collection packages with the vendor and Software Collection's name. For more information, see Section 2.4, The Software Collection Prefix. Specify all Software Collections and other packages required by your application as dependencies Ensure that all Software Collections and other packages required by your application are specified as dependencies of your Software Collection. For more information, see Section , Making a Software Collection Depend on Another Software Collection. Convert existing conventional packages or create new Software Collection packages Ensure that all macros in your Software Collection package spec files use conditionals. See Section 2.10, Converting a Conventional Spec File for more information on how to convert an existing package spec file. Build your Software Collection After you create the Software Collection metapackage and convert or create packages for your Software Collection, you can build the Software Collection with the rpmbuild utility. For more information, see Section 2.12, Building a Software Collection THE FILE SYSTEM HIERARCHY 10

15 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS The root directory of Software Collections is normally located in the /opt/ directory to avoid possible conflicts between Software Collections and the base system installation. The use of the /opt/ directory is recommended by the Filesystem Hierarchy Standard (FHS). Below is an example of the file system hierarchy layout with two Software Collections, software_collection_1 and software_collection_2: Figure 2.1. The Software Collection File System Hierarchy As you can see above, each of the Software Collections directories contains the Software Collection root directory, and one or more Software Collection scriptlets. For more information on the Software Collection scriptlets, refer to Section 2.6, Software Collection Scriptlets THE SOFTWARE COLLECTION ROOT DIRECTORY You can change the location of the root directory by setting the %_scl_prefix macro in the spec file, as in the following example: %global _scl_prefix /opt/provider where provider is the provider (vendor) name registered, where applicable, with the Linux Foundation and the subordinated Linux Assigned Names and Numbers Authority (LANANA), in conformance with the Filesystem Hierarchy Standard. Each organization or project that builds and distributes Software Collections should use its own provider name, which conforms to the Filesystem Hierarchy Standard (FHS) and avoids possible conflicts between Software Collections and the base system installation. You are advised to make the file system hierarchy conform to the following layout: /opt/provider/prefix-application-version/ For more information on the Filesystem Hierarchy Standard, see 11

16 Packaging Guide For more information on the Linux Assigned Names and Numbers Authority, see THE SOFTWARE COLLECTION PREFIX When naming your Software Collection, you are advised to prefix the name of your Software Collection as described below in order to avoid possible name conflicts with the system versions of the packages that are part of your Software Collection. The Software Collection prefix consists of two parts: the provider part, which defines the provider's name, and the name of the Software Collection itself. These two parts of the Software Collection prefix are separated by a dash (-), as in the following example: myorganization-ruby193 In this example, myorganization is the provider's name, and ruby193 is the name of the Software Collection. While it is ultimately a vendor's or distributor's decision whether to specify the provider's name in the prefix or not, specifying it is highly recommended. A notable exception are Software Collections which were first shipped with Red Hat Software Collections 1.x, they do not specify the provider's name in their prefixes. Newer Software Collections added in Red Hat Software Collections 2.0 and later use rh as the provider's name. For example: rh-ruby SOFTWARE COLLECTION PACKAGE NAMES The Software Collection package name consists of two parts: the prefix part, discussed in Section 2.4, The Software Collection Prefix, and the name and version number of the application that is a part of the Software Collection. These two parts of the Software Collection package name are separated by a dash (-), as in the following example: myorganization-ruby193-foreman-1.1 In this example, myorganization-ruby193 is the prefix, and foreman-1.1 is the name and version number of the application SOFTWARE COLLECTION SCRIPTLETS The Software Collection scriptlets are simple shell scripts that change the current system environment so that the group of packages in the Software Collection is preferred over the corresponding group of conventional packages installed on the system. 12

17 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS To utilize the Software Collection scriptlets, use the scl tool that is part of the scl-utils package. For more information on scl, refer to Section 1.6, Enabling a Software Collection. A single Software Collection can include multiple Software Collection scriptlets. These scriptlets are located in the /opt/provider/software_collection/ directory in your Software Collection package. If you only need to distribute a single scriptlet in your Software Collection, it is highly recommended that you use enable as the name for that scriptlet. When the user runs a command in the Software Collection environment by executing scl enable software_collection command, the /opt/provider/software_collection/enable scriptlet is then used to update search paths, and so on. Note that Software Collection scriptlets can only set the system environment in a subshell that is created by running the scl enable command. The subshell is only active for the time the command is being performed PACKAGE LAYOUT Each Software Collection's layout consists of the metapackage, which installs a subset of other packages, and a number of the Software Collection's packages, which are installed within the Software Collection namespace Metapackage Each Software Collection includes a metapackage, which installs a subset of the Software Collection's packages that are essential for the user to perform most common tasks with the Software Collection. For example, the essential packages can provide the Perl language interpreter, but no Perl extension modules. The metapackage contains a basic file system hierarchy and delivers a number of the Software Collection's scriptlets. The purpose of the metapackage is to make sure that all essential packages in the Software Collection are properly installed and that it is possible to enable the Software Collection. The metapackage produces the following packages that are also part of the Software Collection: The main package: %name The main package in the Software Collection contains dependencies of the base packages, which are included in the Software Collection. The main package does not contain any files. When specifying dependencies for your Software Collection's packages, ensure that no other package in your Software Collection depends on the main package. The purpose of the main package is to install only those packages that are essential for the user to perform most common tasks with the Software Collection. Normally, the main package does not specify any build time dependencies (for instance, packages that are only build time dependencies of another Software Collection's packages). For example, if the name of the Software Collection is myorganization-ruby193, then the main package macro is expanded to: myorganization-ruby193 The runtime subpackage: %name-runtime 13

18 Packaging Guide The runtime subpackage in the Software Collection owns the Software Collection's file system and delivers the Software Collection's scriptlets. This package needs to be installed for the user to be able to use the Software Collection. For example, if the name of the Software Collection is myorganization-ruby193, then the runtime subpackage macro is expanded to: myorganization-ruby193-runtime The build subpackage: %name-build The build subpackage in the Software Collection delivers the Software Collection's build configuration. It contains RPM macros needed for building packages into the Software Collection. The build subpackage is optional and can be excluded from the Software Collection. For example, if the name of the Software Collection is myorganization-ruby193, then the build subpackage macro is expanded to: myorganization-ruby193-build The contents of the myorganization-ruby193-build subpackage are shown below: $ cat /etc/rpm/macros.ruby193-config %scl myorganization-ruby193 The syspaths subpackage: %name-syspaths The syspaths subpackage in the Software Collection provides an optional way to install convenient shell wrappers and symbolic links into the standard path, thus altering the base system installation, but making binary files in the Software Collection packages easier to use. For example, if the name of the Software Collection is myorganization-ruby193, then the syspaths subpackage macro is expanded to: myorganization-ruby193-syspaths For more information about the syspaths subpackage, see Section 3.3, Providing syspaths Subpackages. The scldevel subpackage: %name-scldevel The scldevel subpackage in the %name Software Collection contains development files, which are useful when developing packages of another Software Collection that depends on the %name Software Collection. The scldevel subpackage is optional and can be excluded from the %name Software Collection. For example, if the name of the Software Collection is myorganization-ruby193, then the scldevel subpackage macro is expanded to: myorganization-ruby193-scldevel For more information about the scldevel subpackage, see Section 4.1, Providing an scldevel Subpackage. 14

19 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS Creating a Metapackage When creating a new metapackage: It is recommended to define the following macros at the top of the metapackage spec file: scl_name_prefix that specifies the provider's name to be used as a prefix in your Software Collection's name, for example, myorganization-. This is different from _scl_prefix, which specifies the root of your Software Collection but also uses the provider's name. See Section 2.4, The Software Collection Prefix for more information. scl_name_base that specifies the base name of your Software Collection, for example, ruby. scl_name_version that specifies the version of your Software Collection, for example, 193. You are advised to define a Software Collection macro nfsmountable that changes the location of configuration and state files and makes your Software Collection usable over NFS. For more information, see Section 3.1, Using Software Collections over NFS. Consider specifying all packages in your Software Collection that are essential for the Software Collection run time as dependencies of the metapackage. That way you can ensure that the packages are installed with the Software Collection metapackage. You are advised to add Requires: scl-utils-build to the build subpackage. You are not required to use conditionals for Software Collection-specific macros in the metapackage. Include any path redefinition that the packages in your Software Collection may require in the enable scriptlet. For information on commonly used path redefinitions, see Section 2.9, Commonly Used Path Redefinitions. Always make sure that the metapackage contains the %setup macro in the %prep section, otherwise building the Software Collection will fail. If you do not need to use a particular option with the %setup macro, add the %setup -c -T command to the %prep section. This is because the %setup macro defines and creates the %buildsubdir directory, which is normally used for storing temporary files at build time. If you do not define %setup in your Software Collection packages, files in the %buildsubdir directory will be overwritten, causing the build to fail. Add any macros you need to use to the macros.%{scl}-config file in the build subpackage. Example of the Metapackage To get an idea of what a typical metapackage for a Software Collection named myorganization-ruby193 looks like, see the following example: %global scl_name_prefix myorganization- %global scl_name_base ruby %global scl_name_version 193 %global scl %{scl_name_prefix}%{scl_name_base}%{scl_name_version} 15

20 Packaging Guide # Optional but recommended: define nfsmountable %global nfsmountable 1 %scl_package %scl %global _scl_prefix /opt/myorganization Summary: Package that installs %scl Name: %scl_name Version: 1 Release: 1%{?dist} License: GPLv2+ Requires: %{scl_prefix}less BuildRequires: scl-utils-build %description This is the main package for %scl Software Collection. %package runtime Summary: Package that handles %scl Software Collection. Requires: scl-utils %description runtime Package shipping essential scripts to work with %scl Software Collection. %package build Summary: Package shipping basic build configuration Requires: scl-utils-build %description build Package shipping essential configuration macros to build %scl Software Collection. # This is only needed when you want to provide an optional scldevel subpackage %package scldevel Summary: Package shipping development files for %scl %description scldevel Package shipping development files, especially useful for development of packages depending on %scl Software Collection. %prep %setup -c -T %install %scl_install cat >> %{buildroot}%{_scl_scripts}/enable << EOF export PATH="%{_bindir}:%{_sbindir}\${PATH:+:\${PATH}}" export LD_LIBRARY_PATH="% {_libdir}\${ld_library_path:+:\${ld_library_path}}" export MANPATH="%{_mandir}:\${MANPATH:-}" export PKG_CONFIG_PATH="% {_libdir}/pkgconfig\${pkg_config_path:+:\${pkg_config_path}}" EOF 16

21 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS # This is only needed when you want to provide an optional scldevel subpackage cat >> %{buildroot}%{_root_sysconfdir}/rpm/macros.%{scl_name_base}- scldevel << EOF %%scl_%{scl_name_base} %{scl} %%scl_prefix_%{scl_name_base} %{scl_prefix} EOF # Install the generated man page mkdir -p %{buildroot}%{_mandir}/man7/ install -p -m 644 %{scl_name}.7 %{buildroot}%{_mandir}/man7/ %files %files runtime -f filelist %scl_files %files build %{_root_sysconfdir}/rpm/macros.%{scl}-config %files scldevel %{_root_sysconfdir}/rpm/macros.%{scl_name_base}-scldevel %changelog * Fri Aug John Doe <jdoe@example.com> Initial package 2.8. SOFTWARE COLLECTION MACROS The Software Collection packaging macro scl defines where to relocate the Software Collection's file structure. The relocated file structure is a file system used exclusively by the Software Collection. The %scl_package macro defines files ownership for the Software Collection's metapackage and provides additional packaging macros to use in the Software Collection environment. To be able to build a conventional package and a Software Collection package with a single spec file, prefix the Software Collection macros with %{?scl:macro}, as in the following example: %{?scl:requires: %scl_runtime} In the example above, the %scl_runtime macro is the value of the Requires tag. Both the macro and the tag use the %{?scl: prefix Macros Specific to a Software Collection The table below shows a list of all macros specific to a particular Software Collection. All the macros have default values that you will not need to change in most cases. Table 2.1. Software Collection Specific Macros 17

22 Packaging Guide Macro Description Example value %scl_name name of the Software Collection software_collection_1 %scl_prefix name of the Software Collection with a dash appended at the end %pkg_name name of the original package perl %_scl_prefix root of the Software Collection (not package's root) /opt/provider/ %_scl_scripts location of Software Collection's scriptlets /opt/provider/software_ collection_1/ %_scl_root installation root (install-root) of the package /opt/provider/software_ collection_1/root/ %scl_require_package software_collection_1 package_2 depend on a particular package from a specific Software Collection software_collection_1- software_collection_1- package_ Macros Not Specific to a Software Collection The table below shows a list of macros that are not specific to a particular Software Collection. Because these macros are not relocated and do not point to the Software Collection file system, they allow you to point to the system root file system. These macros use _root as a prefix. All the macros have default values that you will not need to change in most cases. Table 2.2. Software Collection Non-Specific Macros Macro Description Relocated Example value %_root_prefix Software Collection's %_prefix macro no /usr/ %_root_exec_pref ix Software Collection's %_exec_prefix macro no /usr/ %_root_bindir Software Collection's %_bindir macro no /usr/bin/ %_root_sbindir Software Collection's %_sbindir macro no /usr/sbin/ %_root_datadir Software Collection's %_datadir macro no /usr/share/ 18

23 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS Macro Description Relocated Example value %_root_sysconfdi r Software Collection's %_sysconfdir macro no /etc/ %_root_libexecdi r Software Collection's %_libexecdir macro no /usr/libexec/ %_root_sharedsta tedir Software Collection's %_sharedstatedir macro no /usr/com/ %_root_localstat edir Software Collection's %_localstatedir macro no /usr/var/ %_root_includedi r Software Collection's %_includedir macro no /usr/include/ %_root_infodir Software Collection's %_infodir macro no /usr/share/info/ %_root_mandir Software Collection's %_mandir macro no /usr/share/man/ %_root_initddir Software Collection's %_initddir macro no /etc/rc.d/init.d / %_root_libdir Software Collection's %_libdir macro, this macro does not work if Software Collection's metapackage is platform-independent no /usr/lib/ The nfsmountable Macro Using a Software Collection macro nfsmountable allows you to change values for the _sysconfdir, _sharedstatedir, and _localstatedir macros so that your Software Collection can have its state files and configuration files located outside the Software Collection's /opt file system hierarchy. This makes the files easier to manage and is also required when using your Software Collection over NFS. If you do not need support for Software Collections over NFS, using nfsmountable is optional but recommended. For more information, see Section 3.1, Using Software Collections over NFS COMMONLY USED PATH REDEFINITIONS This section lists environment variables commonly used to redefine paths in the enable scriptlet to set up the Software Collection environment. They are also used to specify the location of the Software Collection components in the Software Collection file system hierarchy. 19

24 Packaging Guide Whether you need to specify a path redefinition in the enable scriptlet depends on the packages you choose to include in your Software Collection. The environment variables normally follow this pattern: $ENV_VAR=$SCL_ENV_VAR:$ENV_VAR Language-specific Path Redefinitions GEM_PATH The GEM_PATH environment variable specifies the location of Ruby gems. As such, it is also used in those Software Collections that extend the rh-ruby23 Software Collection. For more information, see Section 4.3, Extending the rh-ruby23 Software Collection. Include the following in the enable scriptlet to redefine the environment variable: export GEM_PATH="\${GEM_PATH:=%{gem_dir}:\`scl enable %{scl_ruby} -- ruby -e "print Gem.path.join(':')"\`}" GOPATH The GOPATH environment variable specifies the location of Go source and binary files. Include the following in the enable scriptlet to redefine the environment variable: export GOPATH="%{gopath}\${GOPATH:+:\${GOPATH}}" JAVACONFDIRS The JAVACONFDIRS environment variable is used to specify the location of the java.conf configuration file. Include the following in the enable scriptlet to redefine the environment variable: export JAVACONFDIRS="% {_sysconfdir}/java\${javaconfdirs:+:}\${javaconfdirs:-}" PERL5LIB The PERL5LIB environment variable is used to specify the location of custom Perl modules so that they can be installed with the %{?_scl_root} prefix. Include the following in the enable scriptlet to redefine the environment variable: export PERL5LIB="%{_scl_root}% {perl_vendorlib}\${perl5lib:+:\${perl5lib}}" PYTHONPATH The PYTHONPATH environment variable specifies the location of custom Python libraries. Include the following in the enable scriptlet to redefine the environment variable: export PYTHONPATH="%{_scl_root}%{python_sitearch}:%{_scl_root}% {python_sitelib}\${pythonpath:+:}\${pythonpath:-}" Other Path Redefinitions CPATH 20

25 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS The CPATH environment variable specifies include paths for the GCC compiler to use. Include the following in the enable scriptlet to redefine the environment variable: export CPATH="%{_includedir}\${CPATH:+:\${CPATH}}" INFOPATH The INFOPATH environment variable specifies directories that contain Info files. Include the following in the enable scriptlet to redefine the environment variable: export INFOPATH="%{_infodir}\${INFOPATH:+:\${INFOPATH}}" LD_LIBRARY_PATH The LD_LIBRARY_PATH environment variable specifies the location of libraries. For more information, see Section 3.5, Software Collection Library Support. Include the following in the enable scriptlet to redefine the environment variable: export LD_LIBRARY_PATH="% {_libdir}\${ld_library_path:+:\${ld_library_path}}" LIBRARY_PATH The LIBRARY_PATH environment variable specifies the location of special linker files or ordinary libraries for GCC to use. Include the following in the enable scriptlet to redefine the environment variable: export LIBRARY_PATH="%{_libdir}\${LIBRARY_PATH:+:\${LIBRARY_PATH}}" MANPATH The MANPATH environment variable specifies the location of man pages. For more information, see Section 3.7, Software Collection MANPATH Support. Include the following in the enable scriptlet to redefine the environment variable: export MANPATH="%{_mandir}:\${MANPATH:-}" PATH The PATH environment variable specifies the location of binary files. Include the following in the enable scriptlet to redefine the environment variable: export PATH="%{_bindir}:%{_sbindir}\${PATH:+:\${PATH}}" PCP_DIR The PCP_DIR environment variable specifies the location of files and directories used by PCP. Include the following in the enable scriptlet to redefine the environment variable: export PCP_DIR="%{_scl_root}" PKG_CONFIG_PATH 21

26 Packaging Guide The PKG_CONFIG_PATH environment variable specifies the location of.pc files used by the pkgconfig program. For more information, see Section 3.6, Software Collection.pc Files Support. Include the following in the enable scriptlet to redefine the environment variable: export PKG_CONFIG_PATH="% {_libdir}/pkgconfig\${pkg_config_path:+:\${pkg_config_path}}" XDG_CONFIG_DIRS The XDG_CONFIG_DIRS environment variable specifies the location of desktop configuration files according to the freedesktop.org specification. Include the following in the enable scriptlet to redefine the environment variable: export XDG_CONFIG_DIRS="%{_sysconfdir}/xdg:\${XDG_CONFIG_DIRS:- /etc/xdg}" XDG_DATA_DIRS The XDG_DATA_DIRS environment variable specifies the location of desktop data files according to the freedesktop.org specification. It is used in some Software Collections to locate the Software Collection-specific scripts or to enable bash completion. Include the following in the enable scriptlet to redefine the environment variable: export XDG_DATA_DIRS="%{_datadir}:\${XDG_DATA_DIRS:-/usr/local/share:% {_root_datadir}}" CONVERTING A CONVENTIONAL SPEC FILE This section discusses converting a conventional spec file into a Software Collection spec file so that the converted spec file can be used in both the conventional package and the Software Collection Example of the Converted Spec File To see what the diff file comparing a conventional spec file with a converted spec file looks like, refer to the following example: --- a/less.spec ,10 +%{?scl:%scl_package less} +%{!?scl:%global pkg_name %{name}} + Summary: A text file browser similar to more, but better -Name: less +Name: %{?scl_prefix}less Version: 444 Release: 7%{?dist} License: GPLv3+ Group: Applications/Text -Source: +Source: 22

27 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS {version}.tar.gz Source1: lesspipe.sh Source2: less.sh Source3: less.csh -19,6 +22,7 URL: Requires: groff BuildRequires: ncurses-devel BuildRequires: autoconf automake libtool -Obsoletes: lesspipe < 1.0 +Obsoletes: %{?scl_prefix}lesspipe < 1.0 +%{?scl:requires: %scl_runtime} %description The less utility is a text file browser that resembles more, but -31,7 You should install less because it is a basic utility for viewing text files, and you'll use it frequently. %prep -%setup -q +%setup -q -n %{pkg_name}-%{version} %patch1 -p1 -b.foption %patch2 -p1 -b.search %patch4 -p1 -51,16 make CC="gcc $RPM_OPT_FLAGS -D_GNU_SOURCE - D_LARGEFILE_SOURCE -D_LARGEFILE64_SOU %install rm -rf $RPM_BUILD_ROOT make DESTDIR=$RPM_BUILD_ROOT install -mkdir -p $RPM_BUILD_ROOT/etc/profile.d +mkdir -p $RPM_BUILD_ROOT%{_sysconfdir}/profile.d install -p -c -m 755 %{SOURCE1} $RPM_BUILD_ROOT/%{_bindir} -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT/etc/profile.d -install -p -c -m 644 %{SOURCE3} $RPM_BUILD_ROOT/etc/profile.d -ls -la $RPM_BUILD_ROOT/etc/profile.d +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{_sysconfdir}/profile.d +install -p -c -m 644 %{SOURCE3} $RPM_BUILD_ROOT%{_sysconfdir}/profile.d +ls -la $RPM_BUILD_ROOT%{_sysconfdir}/profile.d %files %defattr(-,root,root,-) %doc LICENSE -/etc/profile.d/* +%{_sysconfdir}/profile.d/* %{_bindir}/* %{_mandir}/man1/* Converting Tags and Macro Definitions The following steps show how to convert tags and macro definitions in a conventional spec file into a Software Collection spec file. Procedure 2.1. Converting tags and macro definitions 23

28 Packaging Guide 1. Add the %scl_package macro to the spec file. Place the macro in front of the spec file preamble as follows: %{?scl:%scl_package package_name} 2. You are advised to define the %pkg_name macro in the spec file preamble in case the package is not built for the Software Collection: %{!?scl:%global pkg_name %{name}} Consequently, you can use the %pkg_name macro to define the original name of the package wherever it is needed in the spec file that you can then use for building both the conventional package and the Software Collection. 3. Change the Name tag in the spec file preamble as follows: Name: %{?scl_prefix}package_name 4. If you are building or linking with other Software Collection packages, then prefix the names of those Software Collection packages in the Requires and BuildRequires tags with %{? scl_prefix} as follows: Requires: %{?scl_prefix}ifconfig When depending on the system versions of packages, you should avoid using versioned Requires or BuildRequires. If you need to depend on a package that could be updated by the system, consider including that package in your Software Collection, or remember to rebuild your Software Collection when the system package updates. 5. To check that all essential Software Collection's packages are dependencies of the main metapackage, add the following macro after the BuildRequires or Requires tags in the spec file: %{?scl:requires: %scl_runtime} 6. Prefix the Obsoletes, Conflicts and BuildConflicts tags with %{?scl_prefix}. This is to ensure that the Software Collection can be used to deploy new packages to older systems without having the packages specified, for example, by Obsolete removed from the base system installation. For example: Obsoletes: %{?scl_prefix}lesspipe < Prefix the Provides tag with %{?scl_prefix}, as in the following example: Provides: %{?scl_prefix}more Converting Subpackages For any subpackages that define their name with the -n option, prefix their name with %{? scl_prefix}, as in the following example: 24

29 CHAPTER 2. PACKAGING SOFTWARE COLLECTIONS %package -n %{?scl_prefix}more Prefixing applies not only to the %package macro, but also for %description and %files. For example: %description -n %{?scl_prefix}rubygems RubyGems is the Ruby standard for publishing and managing third party libraries. In case the subpackage requires the main package, make sure to also adjust the Requires tag in that subpackage so that the tag uses %{?scl_prefix}%{pkg_name}. For example: Requires: %{?scl_prefix}%{pkg_name} = %{version}-%{release} Converting RPM Scripts This section describes general rules for converting RPM scripts that can often be found in the %prep, %build, %install, %check, %pre, and %post sections of a conventional spec file. Replace all occurrences of %name with %pkg_name. Most importantly, this includes adjusting the %setup macro. Adjust the %setup macro in the %prep section of the spec file so that the macro can deal with a different package name in the Software Collection environment: %setup -q -n %{pkg_name}-%{version} Note that the %setup macro is required and that you must always use the macro with the - n option to successfully build your Software Collection. If you are using any of the %_root_ macros to point to the system file system hierarchy, you must use conditionals for these macros so that you can then use the spec file for building both the conventional package and the Software Collection. Edit the macros as in the following example: mkdir -p %{?scl:%_root_sysconfdir}%{?!scl:%_sysconfdir} When building Software Collection packages that depend on other Software Collection packages, it is often important to ensure that the scl enable functionality links properly or run proper binaries, and so on. One of the examples where this is needed is compiling against a Software Collection library or running an interpreted script with the interpreter in the Software Collection. Wrap the script using the %{?scl: prefix, as in the following example: %{?scl:scl enable %scl - << \EOF} set -e ruby example.rb RUBYOPT="-Ilib" ruby bar.rb # The rest of the script contents goes here. %{?scl:eof} 25