Chapter 2. Packaging Software Collections
- 2.1. Creating Your Own Software Collections
- 2.2. The File System Hierarchy
- 2.3. The Software Collection Root Directory
- 2.4. The Software Collection Prefix
- 2.5. Software Collection Package Names
- 2.6. Software Collection Scriptlets
- 2.7. Package Layout
- 2.8. Software Collection Macros
- 2.9. Commonly Used Path Redefinitions
- 2.10. Converting a Conventional Spec File
- 2.10.1. Example of the Converted Spec File
- 2.10.2. Converting Tags and Macro Definitions
- 2.10.3. Converting Subpackages
- 2.10.4. Converting RPM Scripts
- 2.10.5. Software Collection Automatic Provides and Requires and Filtering Support
- 2.10.6. Software Collection Macro Files Support
- 2.10.7. Software Collection Shebang Support
- 2.10.8. Making a Software Collection Depend on Another Software Collection
- 2.11. Uninstalling All Software Collection Directories
- 2.12. Building a Software Collection
This chapter introduces you to packaging Software Collections.
2.1. 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_prefixmacro 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 2.10.8, “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”.
2.2. The File System Hierarchy
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:
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”.
2.3. 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 http://www.pathname.com/fhs/.
For more information on the Linux Assigned Names and Numbers Authority, see http://www.lanana.org/.
2.4. 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-ruby23
2.5. 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.
2.6. 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.
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.
2.7. 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.
2.7.1. 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
- 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 themyorganization-ruby193-buildsubpackage 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”.
2.7.2. 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_prefixthat 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_basethat specifies the base name of your Software Collection, for example, ruby.scl_name_versionthat specifies the version of your Software Collection, for example, 193.
- You are advised to define a Software Collection macro
nfsmountablethat 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-buildto 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
enablescriptlet.For information on commonly used path redefinitions, see Section 2.9, “Commonly Used Path Redefinitions”. - Always make sure that the metapackage contains the
%setupmacro in the%prepsection, otherwise building the Software Collection will fail. If you do not need to use a particular option with the%setupmacro, add the%setup -c -Tcommand to the%prepsection.This is because the%setupmacro defines and creates the%buildsubdirdirectory, which is normally used for storing temporary files at build time. If you do not define%setupin your Software Collection packages, files in the%buildsubdirdirectory will be overwritten, causing the build to fail. - Add any macros you need to use to the
macros.%{scl}-configfile 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} # 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 # 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 30 2013 John Doe <jdoe@example.com> 1-1 - 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.
2.8.1. 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
|
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
| software_collection_1-
|
%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-package_2
|
2.8.2. 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_prefix
|
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/
|
%_root_sysconfdir
|
Software Collection's
%_sysconfdir macro
|
no
| /etc/
|
%_root_libexecdir
|
Software Collection's
%_libexecdir macro
|
no
| /usr/libexec/
|
%_root_sharedstatedir
|
Software Collection's
%_sharedstatedir macro
|
no
| /usr/com/
|
%_root_localstatedir
|
Software Collection's
%_localstatedir macro
|
no
| /usr/var/
|
%_root_includedir
|
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/
|
2.8.3. 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”.
2.9. 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.
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
2.9.1. Language-specific Path Redefinitions
- GEM_PATH
- The
GEM_PATHenvironment 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 theenablescriptlet to redefine the environment variable:export GEM_PATH="\${GEM_PATH:=%{gem_dir}:\`scl enable %{scl_ruby} -- ruby -e "print Gem.path.join(':')"\`}"
- GOPATH
- The
GOPATHenvironment variable specifies the location of Go source and binary files. Include the following in theenablescriptlet to redefine the environment variable:export GOPATH="%{gopath}\${GOPATH:+:\${GOPATH}}"
- JAVACONFDIRS
- The
JAVACONFDIRSenvironment variable is used to specify the location of thejava.confconfiguration file. Include the following in theenablescriptlet to redefine the environment variable:export JAVACONFDIRS="%{_sysconfdir}/java\${JAVACONFDIRS:+:}\${JAVACONFDIRS:-}"
- PERL5LIB
- The
PERL5LIBenvironment 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 theenablescriptlet to redefine the environment variable:export PERL5LIB="%{_scl_root}%{perl_vendorlib}\${PERL5LIB:+:\${PERL5LIB}}"
- PYTHONPATH
- The
PYTHONPATHenvironment variable specifies the location of custom Python libraries. Include the following in theenablescriptlet to redefine the environment variable:export PYTHONPATH="%{_scl_root}%{python_sitearch}:%{_scl_root}%{python_sitelib}\${PYTHONPATH:+:}\${PYTHONPATH:-}"
2.9.2. Other Path Redefinitions
- CPATH
- The
CPATHenvironment variable specifies include paths for the GCC compiler to use. Include the following in theenablescriptlet to redefine the environment variable:export CPATH="%{_includedir}\${CPATH:+:\${CPATH}}"
- INFOPATH
- The
INFOPATHenvironment variable specifies directories that contain Info files. Include the following in theenablescriptlet to redefine the environment variable:export INFOPATH="%{_infodir}\${INFOPATH:+:\${INFOPATH}}"
- LD_LIBRARY_PATH
- The
LD_LIBRARY_PATHenvironment variable specifies the location of libraries. For more information, see Section 3.5, “Software Collection Library Support”.Include the following in theenablescriptlet to redefine the environment variable:export LD_LIBRARY_PATH="%{_libdir}\${LD_LIBRARY_PATH:+:\${LD_LIBRARY_PATH}}"
- LIBRARY_PATH
- The
LIBRARY_PATHenvironment variable specifies the location of special linker files or ordinary libraries for GCC to use. Include the following in theenablescriptlet to redefine the environment variable:export LIBRARY_PATH="%{_libdir}\${LIBRARY_PATH:+:\${LIBRARY_PATH}}"
- MANPATH
- The
MANPATHenvironment variable specifies the location of man pages. For more information, see Section 3.7, “Software Collection MANPATH Support”.Include the following in theenablescriptlet to redefine the environment variable:export MANPATH="%{_mandir}:\${MANPATH:-}"
- PATH
- The
PATHenvironment variable specifies the location of binary files. Include the following in theenablescriptlet to redefine the environment variable:export PATH="%{_bindir}:%{_sbindir}\${PATH:+:\${PATH}}"
- PCP_DIR
- The
PCP_DIRenvironment variable specifies the location of files and directories used by PCP. Include the following in theenablescriptlet to redefine the environment variable:export PCP_DIR="%{_scl_root}"
- PKG_CONFIG_PATH
- The
PKG_CONFIG_PATHenvironment variable specifies the location of.pcfiles used by the pkg-config program. For more information, see Section 3.6, “Software Collection .pc Files Support”.Include the following in theenablescriptlet to redefine the environment variable:export PKG_CONFIG_PATH="%{_libdir}/pkgconfig\${PKG_CONFIG_PATH:+:\${PKG_CONFIG_PATH}}"
- XDG_CONFIG_DIRS
- The
XDG_CONFIG_DIRSenvironment variable specifies the location of desktop configuration files according to the freedesktop.org specification. Include the following in theenablescriptlet to redefine the environment variable:export XDG_CONFIG_DIRS="%{_sysconfdir}/xdg:\${XDG_CONFIG_DIRS:-/etc/xdg}"
- XDG_DATA_DIRS
- The
XDG_DATA_DIRSenvironment 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 theenablescriptlet to redefine the environment variable:export XDG_DATA_DIRS="%{_datadir}:\${XDG_DATA_DIRS:-/usr/local/share:%{_root_datadir}}"
2.10. 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.
2.10.1. 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 +++ b/less.spec @@ -1,10 +1,13 @@ +%{?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: http://www.greenwoodsoftware.com/less/%{name}-%{version}.tar.gz +Source: http://www.greenwoodsoftware.com/less/%{pkg_name}-%{version}.tar.gz Source1: lesspipe.sh Source2: less.sh Source3: less.csh @@ -19,6 +22,7 @@ URL: http://www.greenwoodsoftware.com/less/ 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 has @@ -31,7 +35,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 -b .time @@ -51,16 +55,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/*
2.10.2. 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
- Add the
%scl_packagemacro to the spec file. Place the macro in front of the spec file preamble as follows:%{?scl:%scl_package package_name}
- You are advised to define the
%pkg_namemacro 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_namemacro 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. - Change the
Nametag in the spec file preamble as follows:Name: %{?scl_prefix}package_name
- If you are building or linking with other Software Collection packages, then prefix the names of those Software Collection packages in the
RequiresandBuildRequirestags with%{?scl_prefix}as follows:Requires: %{?scl_prefix}ifconfig
When depending on the system versions of packages, you should avoid using versionedRequiresorBuildRequires. 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. - To check that all essential Software Collection's packages are dependencies of the main metapackage, add the following macro after the
BuildRequiresorRequirestags in the spec file:%{?scl:Requires: %scl_runtime}
- Prefix the
Obsoletes,ConflictsandBuildConflictstags 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, byObsoleteremoved from the base system installation. For example:Obsoletes: %{?scl_prefix}lesspipe < 1.0
- Prefix the
Providestag with%{?scl_prefix}, as in the following example:Provides: %{?scl_prefix}more
2.10.3. Converting Subpackages
For any subpackages that define their name with the
-n option, prefix their name with %{?scl_prefix}, as in the following example:
%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}
2.10.4. 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
%namewith%pkg_name. Most importantly, this includes adjusting the%setupmacro.- Adjust the
%setupmacro in the%prepsection 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%setupmacro is required and that you must always use the macro with the-noption 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 enablefunctionality 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}
It is important to specifyset -ein the script so that the script behavior is consistent regardless of whether the script is executed in therpmshell or thesclenvironment. - Pay attention to any scripts that are executed during the Software Collection package installation, such as:
%pretrans,%pre,%post,%postun,%posttrans,%triggerin,%triggerun, and%triggerpostun.
If you use thescl enablefunctionality in those scripts, you are advised to start with an empty environment to avoid any unintentional collisions with the base system installation.To do so, useenv -i -before enabling the Software Collection, as in the following example:%posttrans %{?scl:env -i - scl enable %{scl} - << \EOF} %vagrant_plugin_register %{vagrant_plugin_name} %{?scl:EOF}
- All hardcoded paths found in RPM scripts must be replaced with proper macros. For example, replace all occurrences of
/usr/sharewith%{_datadir}. This is needed because the$RPM_BUILD_ROOTvariable and the%{build_root}macro are not relocated by thesclmacro.
2.10.5. Software Collection Automatic Provides and Requires and Filtering Support
Important
The functionality described in this section is not available in Red Hat Enterprise Linux 6.
RPM in Red Hat Enterprise Linux 7 features support for automatic
Provides and Requires and filtering. For example, for all Python libraries, RPM automatically adds the following Requires:
Requires: python(abi) = (version)
As explained in Section 2.10, “Converting a Conventional Spec File”, you should prefix this
Requires with %{?scl_prefix} when converting your conventional RPM package:
Requires: %{?scl_prefix}python(abi) = (version))
Keep in mind that the scripts searching for these dependencies must sometimes be rewritten for your Software Collection, as the original RPM scripts are not extensible enough, and, in some cases, filtering is not usable. For example, to rewrite automatic Python
Provides and Requires, add the following lines in the macros.%{scl}-config macro file:
%__python_provides /usr/lib/rpm/pythondeps-scl.sh --provides %{_scl_root} %{scl_prefix} %__python_requires /usr/lib/rpm/pythondeps-scl.sh --requires %{_scl_root} %{scl_prefix}
The
/usr/lib/rpm/pythondeps-scl.sh file is based on a pythondeps.sh file from the conventional package and adjusts search paths.
If there are
Provides or Requires that you need to adjust, for example, a pkg_config Provides, there are two ways to do it:
- Add the following lines in the
macros.%{scl}-configmacro file so that it applies to all packages in the Software Collection:%_use_internal_dependency_generator 0 %__deploop() while read FILE; do /usr/lib/rpm/rpmdeps -%{1} ${FILE}; done | /bin/sort -u %__find_provides /bin/sh -c "%{?__filter_prov_cmd} %{__deploop P} %{?__filter_from_prov}" %__find_requires /bin/sh -c "%{?__filter_req_cmd} %{__deploop R} %{?__filter_from_req}" # Handle pkgconfig's virtual Provides and Requires %__filter_from_req | %{__sed} -e 's|pkgconfig|%{?scl_prefix}pkgconfig|g' %__filter_from_prov | %{__sed} -e 's|pkgconfig|%{?scl_prefix}pkgconfig|g'
- Or, alternatively, add the following lines after tag definitions in every spec file for which you want to filter
ProvidesorRequires:%{?scl:%filter_from_provides s|pkgconfig|%{?scl_prefix}pkgconfig|g} %{?scl:%filter_from_requires s|pkgconfig|%{?scl_prefix}pkgconfig|g} %{?scl:%filter_setup}
Important
When using filters, you need to pay attention to the automatic dependencies you change. For example, if the conventional package contains
Requires: pkgconfig(package_1) and Requires: pkgconfig(package_2), and only package_2 is included in the Software Collection, ensure that you do not filter the Requires tag for package_1.
2.10.6. Software Collection Macro Files Support
In some cases, you may need to ship macro files with your Software Collection packages. They are located in the
%{?scl:%{_root_sysconfdir}}%{!?scl:%{_sysconfdir}}/rpm/ directory, which corresponds to the /etc/rpm/ directory for conventional packages. When shipping macro files, ensure that:
- You rename the macro files by appending
.%{scl}to their names so that they do not conflict with the files from the base system installation. - The macros in the macro files are either not expanded, or they are using conditionals, as in the following example:
%__python2 %{_bindir}/python %python2_sitelib %(%{?scl:scl enable %scl '}%{__python2} -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"%{?scl:'})
As another example, there may be a situation where you need to create a Software Collection mypython that depends on a Software Collection python26. The python26 Software Collection defines the
%{__python2} macro as in the above sample. This macro will evaluate to /opt/provider/mypython/root/usr/bin/python2, but the python2 binary is only available in the python26 Software Collection (/opt/provider/python26/root/usr/bin/python2).
To be able to build software in the mypython Software Collection environment, ensure that:
- The
macros.python.python26macro file, which is a part of the python26-python-devel package, contains the following line:%__python26_python2 /opt/provider/python26/root/usr/bin/python2
- And the macro file in the python26-build subpackage, and also the build subpackage in any depending Software Collection, contains the following line:
%scl_package_override() {%global __python2 %__python26_python2}
This will redefine the
%{__python2} macro only if the build subpackage from a corresponding Software Collection is present, which usually means that you want to build software for that Software Collection.
2.10.7. Software Collection Shebang Support
A shebang is a sequence of characters at the beginning of a script that is used as an interpreter directive. The shebang is processed by the automatic dependency generator and it points to a certain location, possibly in the system root file system.
When the automatic dependency generator processes the shebang, it adds dependencies according to the interpreters they point to. From the Software Collection point of view, there are two types of shebangs:
#!/usr/bin/env example- This shebang instructs the
/usr/bin/envprogram to run the interpreter.The automatic dependency generator will create a dependency on the/usr/bin/envprogram, as expected.If the$PATHenvironment variable is redefined properly in theenablescriptlet, the example interpreter is found in the Software Collection file system hierarchy, as expected.You are advised to rewrite the shebang in your Software Collection package so that the shebang specifies the full path to the interpreter located in the Software Collection file system hierarchy. #!/usr/bin/example- This shebang specifies the direct path to the interpreter.The automatic dependency generator will create a dependency on the
/usr/bin/exampleinterpreter located outside the Software Collection file system hierarchy. However, when building a package for your Software Collection, you often want to create a dependency on the%{?_scl_root}/usr/bin/exampleinterpreter located in the Software Collection file system hierarchy.Keep in mind that even when you properly redefine the$PATHenvironment variable, this has no effect on what interpreter is used. The system version of the interpreter located outside the Software Collection file system hierarchy is always used. In most cases, this is not desired.If you are using this type of shebang and you want the shebang to point to the Software Collection file system hierarchy when building your Software Collection package, use a command like the following:find %{buildroot} -type f | \ xargs sed -i -e '1 s"^#!/usr/bin/example"#!%{?_scl_root}/usr/bin/example"'
where /usr/bin/example is the interpreter you want to use.
2.10.8. Making a Software Collection Depend on Another Software Collection
To make one Software Collection depend on a package from another Software Collection, you need to adjust the
BuildRequires and Requires tags in the dependent Software Collection's spec file so that these tags properly define the dependency.
For example, to define dependencies on two Software Collections named software_collection_1 and software_collection_2, add the following three lines to your application's spec file:
BuildRequires: scl-utils-build Requires: %scl_require software_collection_1 Requires: %scl_require software_collection_2
Ensure that the spec file also contains the
%scl_package macro in front of the spec file preamble, for example:
%{?scl:%scl_package less}
Note that the
%scl_package macro must be included in every spec file of your Software Collection.
You can also use the
%scl_require_package macro to define dependencies on a particular package from a specific Software Collection, as in the following example:
BuildRequires: scl-utils-build Requires: %scl_require_package software_collection_1 package_name
2.11. Uninstalling All Software Collection Directories
Keep in mind that the
yum remove command does not uninstall directories provided by those Software Collection packages and subpackages that are removed after the Software Collection runtime subpackage is removed.
To ensure that all directories are uninstalled, make those packages and subpackages depend on the runtime subpackage. To do so, add the following line with the
%scl_runtime macro to the spec file of each of those packages and subpackages:
%{?scl:Requires: %scl_runtime}
Adding the above line ensures that all directories provided by those packages and subpackages are removed correctly as long as the runtime subpackage does not depend on any of those packages and subpackages.
2.12. Building a Software Collection
If you have correctly converted a conventional spec file for your Software Collection as documented in Section 2.10, “Converting a Conventional Spec File”, you will be able to build the resulting package in both the Software Collection and conventional build roots. Building the converted package in a conventional build root will produce a conventional base system RPM package, while building in a Software Collection build root that contains %{scl}-build will produce a Software Collection package.
To build a Software Collection on your system, run the following command:
rpmbuild -ba package.spec --define 'scl name'
The difference between the command shown above and the standard command to build conventional packages (
rpmbuild -ba package.spec) is that you have to append the --define option to the rpmbuild command when building a Software Collection.
The
--define option defines the scl macro, which uses the Software Collection configured in the Software Collection spec file (package.spec).
Alternatively, to be able to use the standard command
rpmbuild -ba package.spec to build the Software Collection, specify the following in the package.spec file:
BuildRequires: software_collection-build
where software_collection is the name of the Software Collection.
2.12.1. Rebuilding a Software Collection without build Subpackages
When you want to rebuild a Software Collection that comes with no build subpackage (software_collection-build), you can create the build subpackage by rebuilding the Software Collection metapackage, and thus avoid using the
rpmbuild -ba package.spec --define 'scl name' command.
Note that you need to have the scl-utils-build package installed on your system, otherwise rebuilding the Software Collection metapackage with the
rpmbuild command will fail.
For more information about the scl-utils-build package, see Section 1.3, “Enabling Support for Software Collections”.
2.12.2. Avoiding debuginfo File Conflicts
When you build two Software Collection packages (or a conventional RPM package and a Software Collection package) that specify the same
Source tag, and thus unpack source files into the same directory underneath the %_builddir directory, their debuginfo packages will have file conflicts. Due to these conflicts, the user will be unable to install both packages on the same system at the same time.
To avoid these file conflicts, the spec file of one of the packages has to be altered to unpack its upstream source into a uniquely named top directory. This adds one more directory level to the build tree underneath the
%_builddir directory. By doing so, the debuginfo package generation script produces debuginfo files that do not conflict with files from the other debuginfo package.
To see what the diff file comparing an original spec file with an altered spec file looks like, refer to the following example:
--- a/tbb.spec +++ b/tbb.spec @@ -66,11 +66,13 @@ PDF documentation for the user of the Threading Building Block (TBB) C++ library. %prep -%setup -q -n %{sourcebasename} +%setup -q -c -n %{name} +cd %{sourcebasename} %patch1 -p1 %patch2 -p1 %build +cd %{sourcebasename} %{?scl:scl enable %{scl} - << \EOF} make %{?_smp_mflags} CXXFLAGS="$RPM_OPT_FLAGS" tbb_build_prefix=obj %{?scl:EOF} @@ -81,6 +83,7 @@ done %install rm -rf $RPM_BUILD_ROOT +cd %{sourcebasename} mkdir -p $RPM_BUILD_ROOT/%{_libdir} mkdir -p $RPM_BUILD_ROOT/%{_includedir} @@ -108,20 +111,20 @@ done %files %defattr(-,root,root,-) -%doc COPYING doc/Release_Notes.txt +%doc %{sourcebasename}/COPYING %{sourcebasename}/doc/Release_Notes.txt %{_libdir}/*.so.2 %files devel %defattr(-,root,root,-) -%doc CHANGES +%doc %{sourcebasename}/CHANGES %{_includedir}/tbb %{_libdir}/*.so %{_libdir}/pkgconfig/*.pc %files doc %defattr(-,root,root,-) -%doc doc/Release_Notes.txt -%doc doc/html +%doc %{sourcebasename}/doc/Release_Notes.txt +%doc %{sourcebasename}/doc/html %changelog * Wed Nov 13 2013 John Doe <jdoe@example.com> - 4.1-5.20130314