From e42331a03546da8fc1d024b1b01555a3e1e33674 Mon Sep 17 00:00:00 2001 From: Petr Kovar Date: Sep 18 2013 15:39:56 +0000 Subject: Fedora updates --- diff --git a/en-US/Advanced_Topics.xml b/en-US/Advanced_Topics.xml new file mode 100644 index 0000000..cade611 --- /dev/null +++ b/en-US/Advanced_Topics.xml @@ -0,0 +1,306 @@ + + + + Advanced Topics + This chapter discusses advanced topics on packaging &DSCL;s. +
+ &DSCL; Initscript Support + Ensure that users can directly manage any services provided by the &DSCL; or one of the associated applications with the system default tools, like service or chkconfig. + To avoid possible name conflicts with the system versions of the services that are part of the &DSCL;, make sure to adjust the %install section of the spec file as follows: + +%install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/rc.d/init.d/%{?scl_prefix}service_name + + With this configuration in place, you can then refer to the version of the service included in the &DSCL; as follows: + %{?scl_prefix}service_name +
+
+ &DSCL; Library Support + In case you distribute libraries that you intend to use only in the &DSCL; environment or in addition to the libraries available on the system, adjust the LD_LIBRARY_PATH environment variable in the spec file as follows: + export LD_LIBRARY_PATH=%{_libdir}${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} + This configuration ensures that the version of the library in the &DSCL; is preferred over the version of the library available on the system if the &DSCL; is enabled. + + + In case you distribute a private shared library in the &DSCL;, consider using the DT_RUNPATH attribute instead of the LD_LIBRARY_PATH environment variable to make the private shared library accessible in the &DSCL; environment. + + +
+ Using a Library Outside of the &DSCL; + If you distribute libraries that you intend to use outside of the &DSCL; environment, you can use the directory /etc/ld.so.conf.d/ for this purpose. + + Do not use /etc/ld.so.conf.d/ for libraries already available on the system. Using /etc/ld.so.conf.d/ is only recommended for a library that is not available on the system, as otherwise the version of the library in the &DSCL; might get preference over the system version of the library. That could lead to undesired behavior of the system versions of the applications, including unexpected termination and data loss. + + + Using /etc/ld.so.conf.d/ for libraries in the &DSCL; + + Create a file named libs.conf and adjust the spec file configuration accordingly: + +SOURCE2: %{?scl_prefix}libs.conf + + + + In the libs.conf file, include a list of directories where the versions of the libraries associated with the &DSCL; are located. For example: + /&OPT;/&RH;/software_collection_1/root/usr/lib64/ + + In the example above, the /usr/lib64/ directory that is part of the &DSCL; software_collection_1 is included in the list. + + + Edit the %install section of the spec file, so the libs.conf file is installed as follows: + %install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/ld.so.conf.d/ + + + +
+
+ Prefixing the Library Major soname with the &DSCL; Name + + When using libraries included in the &DSCL;, always remember that a library with the same major soname can already be available on the system as a part of the base system installation. It is thus important not to forget to use the scl enable command when building an application against a library included in the &DSCL;. Failing to do so may result in the application being executed in an incorrect environment, linked against the incorrect system version of the library. + + Keep in mind that executing your application in an incorrect environment (for example in the system environment instead of the &DSCL; environment) as well as linking your application against an incorrect library can lead to undesired behavior of your application, including unexpected termination and data loss. + +To ensure that your application is not linked against an incorrect library even if the LD_LIBRARY_PATH environment variable has not been set properly, change the major soname of the library included in the &DSCL;. The recommended way to change the major soname is to prefix the major soname version number with the &DSCL; name. + + + Below is an example of the MySQL client library with the mysql55- prefix: + + +$ rpm -ql mysql55-mysql-libs | grep 'lib.*so' +/usr/lib64/mysql/libmysqlclient.so.mysql55-18 +/usr/lib64/mysql/libmysqlclient.so.mysql55-18.0.0 + + + On the same system, the system version of the MySQL client library is listed below: + + +$ rpm -ql mysql-libs | grep 'lib.*so' +/usr/lib64/mysql/libmysqlclient.so.18 +/usr/lib64/mysql/libmysqlclient.so.18.0.0 + +
+
+
+ &DSCL; .pc Files Support + The .pc files are special metadata files used by the pkg-config program to store information about libraries available on the system. In case you distribute .pc files that you intend to use only in the &DSCL; environment or in addition to the .pc files installed on the system, adjust the PKG_CONFIG_PATH environment variable. Depending on what is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable for the %{_libdir} macro (which expands to the library directory, typically /usr/lib/ or /usr/lib64/), or for the %{_datadir} macro (which expands to the share directory, typically /usr/share/). + If the library directory is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable in the spec file as follows: + +export PKG_CONFIG_PATH=%{_libdir}/pkgconfig:\$PKG_CONFIG_PATH + + If the share directory is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable in the spec file as follows: + +export PKG_CONFIG_PATH=%{_datadir}/pkgconfig:\$PKG_CONFIG_PATH + + This configuration ensures that the .pc files in the &DSCL; are preferred over the .pc files available on the system if the &DSCL; is enabled. + The &DSCL; can provide a wrapper script that is visible to the system to enable the &DSCL;, for example in the /usr/bin/ directory. In this case, ensure that the .pc files are visible to the system even if the &DSCL; is disabled. + To allow your system to use .pc files from the disabled &DSCL;, update the PKG_CONFIG_PATH environment variable with the paths to the .pc files associated with the &DSCL;. Depending on what is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable for the %{_libdir} macro (which expands to the library directory), or for the %{_datadir} macro (which expands to the share directory). +Updating the PKG_CONFIG_PATH environment variable for %{_libdir} +To update the PKG_CONFIG_PATH environment variable for the %{_libdir} macro, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. +For example, create the following file: + %{?scl_prefix}pc-libdir.sh +Use the pc-libdir.sh short script that modifies the PKG_CONFIG_PATH variable to refer to your .pc files: + export PKG_CONFIG_PATH=%{_libdir}/pkgconfig:/&OPT;/&RH;/software_collection/path/to/your/pc_files +Add the file to your &DSCL; package's spec file: +SOURCE2: %{?scl_prefix}pc-libdir.sh + Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: + %install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ + + +Updating the PKG_CONFIG_PATH environment variable for %{_datadir} +To update the PKG_CONFIG_PATH environment variable for the %{_datadir} macro, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. +For example, create the following file: + %{?scl_prefix}pc-datadir.sh +Use the pc-datadir.sh short script that modifies the PKG_CONFIG_PATH variable to refer to your .pc files: + export PKG_CONFIG_PATH=%{_datadir}/pkgconfig:/&OPT;/&RH;/software_collection/path/to/your/pc_files +Add the file to your &DSCL; package's spec file: +SOURCE2: %{?scl_prefix}pc-datadir.sh + Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: + %install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ + + +
+
+ &DSCL; manpath Support + To allow the man command on the system to display manual pages from the enabled &DSCL;, update the MANPATH environment variable with the paths to the manual pages that are associated with the &DSCL;. + To update the MANPATH environment variable, add the following line to the spec file: + export MANPATH=%{_mandir}:\${MANPATH} + This update relocates the %{_mandir} macro to the &DSCL; path. So that the manual pages associated with the &DSCL; are not visible as long as the &DSCL; is not enabled. + The &DSCL; can provide a wrapper script that is visible to the system to enable the &DSCL;, for example in the /usr/bin/ directory. In this case, ensure that the manual pages are visible to the system even if the &DSCL; is disabled. + To allow the man command on the system to display manual pages from the disabled &DSCL;, update the MANPATH environment variable with the paths to the manual pages associated with the &DSCL;. +Updating the MANPATH environment variable for the disabled &DSCL; +To update the MANPATH environment variable, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. +For example, create the following file: + %{?scl_prefix}manpage.sh + + Use the manpage.sh short script that modifies the MANPATH variable to refer to your man path directory: + export MANPATH=/&OPT;/&RH;/software_collection/path/to/your/man_pages:${MANPATH} + + Add the file to your &DSCL; package's spec file: + SOURCE2: %{?scl_prefix}manpage.sh + Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: + %install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ + + +
+
+ &DSCL; cronjob Support + With your &DSCL;, you can run regular tasks on the system either with a dedicated service or with cronjobs. If you intend to use a dedicated service, refer to on how to work with initscripts in the &DSCL; environment. + + Running regular tasks with cronjobs + + To use cronjobs for running regular tasks, place a crontab file for your &DSCL; in the /etc/cron.d/ directory with the &DSCL;'s name. + For example, create the following file: + %{?scl_prefix}crontab + + + Ensure that the contents of the crontab file follow the standard crontab file format, as in the following example: + 0 1 * * Sun root /&OPT;/&RH;/software_collection/architecture/usr/bin/cron_job_name + + + Add the file to your spec file of the &DSCL; package: + SOURCE2: %{?scl_prefix}crontab + + + Install the file into the system directory /etc/cron.d/ by adjusting the %install section of the &DSCL; package's spec file: + %install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/cron.d/ + + + +
+
+ &DSCL; Log File Support + + By default, programs packaged in a &DSCL; create log files in the /&OPT;/&RH;/software_collection/root/var/log/ directory. Consider creating the log files outside of the &DSCL; file system hierarchy, that is in the /var/log/ system directory. When using the system directory, all log files are stored in the same location, which makes it easier for users to locate and manage them. + +
+
+ &DSCL; logrotate Support + With your &DSCL; or an application associated with your &DSCL;, you can manage log files with the logrotate program. + + Managing log files with logrotate + + To manage your log files with logrotate, place a custom logrotate file for your &DSCL; in the system directory for the logrotate jobs /etc/logrotate.d/. + For example, create the following file: + %{?scl_prefix}logrotate + + + Ensure that the contents of the logrotate file follow the standard logrotate file format as follows: + /&OPT;/&RH;/software_collection/var/log/your_application_name.log { + missingok + notifempty + size 30k + yearly + create 0600 root root + } + + + Add the file to your spec file of the &DSCL; package: + SOURCE2: %{?scl_prefix}logrotate + + + Install the file into the system directory /etc/logrotate.d/ by adjusting the %install section of the &DSCL; package's spec file: + %install +install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/logrotate.d/ + + +
+
+ &DSCL; Lock File Support + If you store your &DSCL;'s lock files within the /&OPT;/&RH;/software_collection/ file system hierarchy, you can avoid any possible conflicts with the system versions of the applications or services that can be on the system. + If you want to prevent &DSCL;'s applications or services from running while the system version of the respective application or service is running, make sure that your applications or services, which require a lock, write the lock to the system directory /var/lock/ instead of the &DSCL;'s directory /&OPT;/&RH;/software_collection/var/lock/. In this way, your applications or services' lock file will not be overwritten. The lock file will not be renamed and the name stays the same as the system version. + If you want your &DSCL;'s version of the application or service to run concurrently with the system version (when the &DSCL; version's resources will not conflict with the system version's resources), ensure that the applications or services write the lock to the &DSCL;'s directory /&OPT;/&RH;/software_collection/var/lock/. +
+
+ &DSCL; Configuration Files Support + If you store your &DSCL;'s configuration files within the /&OPT;/&RH;/software_collection/ file system hierarchy, you can avoid any possible conflicts with the system versions of the configuration files that can be present on the system. + If you cannot store the configuration files within /&OPT;/&RH;/software_collection/, then ensure that you properly configure an alternative location for the configuration files. For many programs, this can be usually done at build or installation time. +
+
+ &DSCL; Kernel Module Support + Because Linux kernel modules are normally tied to a particular version of the Linux kernel, you must be careful when you package kernel modules into a &DSCL;. This is because the package management system on &MAJOROS; does not automatically update or install an updated version of the kernel module if an updated version of the Linux kernel is installed. To make packaging the kernel modules into the &DSCL; easier, see the following recommendations. Ensure that: + + + the name of your kernel module package includes the kernel version, + + + the tag Requires, which can be found in your kernel module spec file, includes the kernel version and revision (in the format kernel-version-revision). + + +
+
+ &DSCL; SELinux Support + Because &DSCL;s are designed to install the &DSCL; packages in an alternate directory, set up the necessary SELinux labels so that SELinux is aware of the alternate directory. + If the file system hierarchy of your &DSCL; package imitates the file system hierarchy of the corresponding conventional package, you can run the semanage fcontext and restorecon commands to set up the SELinux labels. + For example, if the /&OPT;/&RH;/software_collection_1/x86_64/root/usr/ directory in your &DSCL; package imitates the /usr/ directory of your conventional package, set up the SELinux labels as follows: + + semanage fcontext -a -e /usr /&OPT;/&RH;/software_collection_1/x86_64/root/usr + + + restorecon -R -v /&OPT;/&RH;/software_collection_1/x86_64/root/usr + + The commands above ensure that all directories and files in the /&OPT;/&RH;/software_collection_1/x86_64/root/usr/ directory are labeled by SELinux as if they were located in the /usr/ directory. + +
+
+ &DSCL; Macro Files Support + + In some cases, you may need to ship macro files with your &DSCL; packages. They are located in the %{?scl:%{_root_sysconfdir}}%{!?scl:%{_sysconfdir}} 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 &DSCL; mypython that depends on a &DSCL; python26. The python26 &DSCL; defines the %{__python2} macro as in the above sample. This macro will evaluate to /&OPT;/&RH;/mypython/root/usr/bin/python2, but the python2 binary is only available in the python26 &DSCL; (/&OPT;/&RH;/python26/root/usr/bin/python2). + + + To be able to build software in the mypython &DSCL; environment, ensure that: + + + + + The macros.python.python26 macro file, which is a part of the python26-python-devel package, contains the following line: + + %__python26_python2 /&OPT;/&RH;/python26/root/usr/bin/python2 + + + + And the macro file in the python26-build subpackage, and also the build subpackage in any depending &DSCL;, 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 &DSCL; is present, which usually means that you want to build software for that &DSCL;. + +
+
+ Packaging Wrappers for &DSCL;s + + Using wrappers is an easy way to shorten commands that the user runs in the &DSCL; environment. + The following is an example of a wrapper from the ruby193 &DSCL; that is installed as /usr/bin/ruby193-ruby and allows the user to run ruby193-ruby command instead of scl enable ruby193 'ruby command': + + #!/bin/bash + +COMMAND="ruby $@" +scl enable ruby193 "$COMMAND" + + + It is important to package these wrappers as subpackages of the &DSCL; package that will use them. That way, you can make installation of these wrappers optional, allowing the user not to install them, for example, on systems with read-only access to the /usr/bin/ directory where the wrappers would otherwise be installed. + +
+ diff --git a/en-US/Getting_More_Information.xml b/en-US/Getting_More_Information.xml index e8c6a56..8dcf688 100644 --- a/en-US/Getting_More_Information.xml +++ b/en-US/Getting_More_Information.xml @@ -24,17 +24,14 @@ The following is a brief list of documents that are directly or indirectly relevant to this book: - - Fedora 18 Installation Guide – The Installation Guide for Fedora 18 provides more details on getting, installing, and updating the system. + Fedora 19 Installation Guide – The Installation Guide for Fedora 19 provides more details on getting, installing, and updating the system. - Fedora 17 System Administrator's Guide – The System Administrator's Guide for Fedora 17 documents relevant information regarding the deployment, configuration, and administration of Fedora 17. + Fedora 18 System Administrator's Guide – The System Administrator's Guide for Fedora 18 documents relevant information regarding the deployment, configuration, and administration of Fedora. diff --git a/en-US/Introducing_Software_Collections.xml b/en-US/Introducing_Software_Collections.xml index c263496..915232b 100644 --- a/en-US/Introducing_Software_Collections.xml +++ b/en-US/Introducing_Software_Collections.xml @@ -2,7 +2,7 @@ Introducing &DSCL;s - This chapter introduces you to the concept of &DSCL;s or &DSC;s for short. + This chapter introduces you to the concept and usage of &DSCL;s or &DSC;s for short.
Why Package Software with RPM? The RPM Package Manager (RPM) is a package management system that runs on &MAJOROS;. RPM makes it easier for you to distribute, manage, and update software that you create for &MAJOROS;. 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. @@ -34,7 +34,7 @@ - For in-depth information on what is RPM and how to use it, refer to the Fedora 17 System Administrator's Guide. + For in-depth information on what is RPM and how to use it, refer to the Fedora 18 System Administrator's Guide.
@@ -105,143 +105,31 @@ Enabling Support for &DSCL;s To enable support for &DSCL;s on your system so that you can enable and build &DSCL;s, 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 -y scl-utils scl-utils-build +yum install scl-utils scl-utils-build The scl-utils package provides the scl tool that lets you enable &DSCL;s on your system. For more information on enabling &DSCL;s, refer to . The scl-utils-build package provides macros that are essential for building &DSCL;s. For more information on building &DSCL;s, refer to .
-
- The File System Hierarchy - The root directory of &DSCL;s is normally located in the /&OPT;/ directory to avoid possible conflicts between &DSCL;s and the base system installation. The use of the /&OPT;/ directory is recommended by the Filesystem Hierarchy Standard (FHS). - You can change the location of the root directory by setting the %_scl_prefix macro in the spec file, as in the following example: - %_scl_prefix /opt/provider - where provider is the provider (vendor) name registered 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 &DSCL;s should use its own provider name, which conforms to the Filesystem Hierarchy Standard (FHS) and avoids possible conflicts between &DSCL;s and the base system installation. - You are advised to make the file system hierarchy conform to the following layout: - /opt/provider/application-version/ - For more information on the Filesystem Hierarchy Standard, refer to http://www.pathname.com/fhs/. - For more information on the Linux Assigned Names and Numbers Authority, refer to http://www.lanana.org/. - Below is an example of the file system hierarchy layout with two &DSCL;s, &DSCL; 1 and &DSCL; 2: - &OPT; -`-- &RH; - |-- &DSCL; 1 - | |-- &DSCL; root directory - | `-- &DSCL; scriptlets - | - `-- &DSCL; 2 - |-- &DSCL; root directory - `-- &DSCL; scriptlets - - As you can see in the example above, each of the &DSCL;s directories contains two subdirectories: the &DSCL; root directory and a directory containing the &DSCL; scriptlets. For more information on the &DSCL; scriptlets, refer to . -
-
- &DSCL; Scriptlets - The &DSCL; scriptlets are simple shell scripts that change the current system environment so that the group of packages in the &DSCL; is preferred over the corresponding group of conventional packages installed on the system. - To utilize the &DSCL; scriptlets, use the scl tool. For more information on scl, refer to . +
+ Installing a &DSCL; + To ensure that a &DSCL; is on your system, install the so-called metapackage of the &DSCL;. You can use conventional tools like Yum or PackageKit for this task because &DSCL;s are fully compatible with the RPM Package Manager. + + For example, to install a &DSCL; with the metapackage named software_collection_1, run the following command: + + yum install software_collection_1 + + This command will automatically install all the packages that are part of the &DSCL;. Also, if you install an application that depends on a &DSCL;, the &DSCL; will be installed along with the rest of the application's dependencies. + + For detailed information on &DSCL; metapackages, see . + +For detailed information on Yum and PackageKit usage, see the Fedora 18 System Administrator's Guide.
-
- Package Layout - Each &DSCL;'s layout consists of the meta package, which installs a subset of other packages, and a number of the &DSCL;'s packages, which are installed within the &DSCL; namespace. -
- Meta Package - Each &DSCL; includes a meta package, which installs a minimal subset of essential packages. For example, the essential packages can provide the Perl language interpreter, but no Perl extension modules. The meta package contains a basic file system hierarchy and delivers a number of the &DSCL;'s scriptlets. - The purpose of the meta package is to make sure that all essential packages in the &DSCL; are properly installed and that it is possible to enable the &DSCL;. - The meta package produces the following packages that are also part of the &DSCL;: - - - The main package: %scl - - The main package in the &DSCL; contains dependencies of the base packages, which are included in the &DSCL;. The main package does not contain any files. - For example, if the name of the &DSCL; is ruby-1.8.7, then the main package macro is expanded to: - ruby-1.8.7 - - - - The runtime subpackage: name-runtime - - The runtime subpackage in the &DSCL; owns the &DSCL;'s file system and delivers the &DSCL;'s scriptlets. - For example, if the name of the &DSCL; is ruby-1.8.7, then the runtime subpackage macro is expanded to: - ruby-1.8.7-runtime - - - - The build subpackage: name-build - - The build subpackage in the &DSCL; delivers the &DSCL;'s build configuration. The build subpackage is optional and can be excluded from the &DSCL;. - For example, if the name of the &DSCL; is ruby-1.8.7, then the build subpackage macro is expanded to: - ruby-1.8.7-build - - - -Example of the Meta Package -To get an idea of what a typical &DSCL; meta package looks like, see the following example: - %{!?scl:%global scl example} -%scl_package %scl - -Summary: Package that installs %scl -Name: %scl_name -Version: 1 -Release: 1%{?dist} -BuildArch: noarch -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 - -%description build -Package shipping essential configuration macros to build %scl Software Collection. - -%prep -%setup -c -T - -%install -rm -rf %{buildroot} -mkdir -p %{buildroot}%{_scl_scripts}/root -cat >> %{buildroot}%{_scl_scripts}/enable << EOF -export PATH=%{_bindir}:\$PATH -EOF -%scl_install - -%files - -%files runtime -%scl_files - -%files build -%{_root_sysconfdir}/rpm/macros.%{scl}-config - -%changelog -* Thu Jan 07 2012 John Doe <jdoe@example.com> 1-1 -- Initial package - -
-
- Packages in the &DSCL; Namespace - Besides the minimal subset of packages installed by the meta package, the &DSCL; also installs a number of packages that are part of the package collection itself. - - - &DSCL; package: name-pkgname - - The &DSCL; can contain a number of packages, which are included in the &DSCL; namespace and relocated to the &DSCL;'s file system hierarchy. - For example, if the name of the &DSCL; is ruby-1.8.7, then the &DSCL;'s package name for the ruby-1.8.7.352-2.1.&PKGOS;.x86_64.rpm package is: - ruby-1.8.7-ruby-1.8.7.352-2.1.&PKGOS;.x86_64.rpm - - - - +
+ Listing Installed &DSCL;s + To get a list of &DSCL;s that are currently installed on the system, run the following command: + + scl --list +
-
Enabling a &DSCL; The scl tool is used to enable a &DSCL; and to run applications in the &DSCL; environment. @@ -259,6 +147,9 @@ EOF scl enable software_collection_1 'perl --version' + + Alternatively, you can create a wrapper script that shortens the commands for running applications in the &DSCL; environment. For more information on wrappers, see . +
Running a Shell with Multiple &DSCL;s Enabled @@ -266,7 +157,8 @@ EOF scl enable software_collection_1 software_collection_2 bash - The command above enables two &DSCL;s named software_collection_1 and software_collection_2. + The command above enables two &DSCL;s, named software_collection_1 and software_collection_2, and runs a child process (subshell) of the shell. Running the command again then creates a subshell of the subshell. + See for information on how to list enabled &DSCL;s for the current subshell.
Running Commands Stored in a File @@ -277,4 +169,24 @@ EOF The command above executes commands, which are stored in the cmd file, in the environment of the &DSCL; named software_collection_1.
+
+ Listing Enabled &DSCL;s + + To get a list of &DSCL;s that are enabled in the current session, print the $X_SCLS environment variable by running the following command: + + echo $X_SCLS + +
+
+ Uninstalling a &DSCL; + + You can use conventional tools like Yum or PackageKit when uninstalling a &DSCL; because &DSCL;s are fully compatible with the RPM Package Manager. For example, to uninstall all packages and subpackages that are part of a &DSCL; 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, refer to the Fedora 18 System Administrator's Guide. +
diff --git a/en-US/Packaging_Software_Collections.xml b/en-US/Packaging_Software_Collections.xml index ab8e480..dad2508 100644 --- a/en-US/Packaging_Software_Collections.xml +++ b/en-US/Packaging_Software_Collections.xml @@ -3,19 +3,303 @@ Packaging &DSCL;s This chapter introduces you to packaging &DSCL;s. -
- Building a &DSCL; Locally - To build a &DSCL; 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 -bb package.spec) is that you have to append the option to the rpmbuild command when building a &DSCL;. - The option defines the scl macro, which uses the &DSCL; configured in the &DSCL; spec file. +
+ Creating Your Own &DSCL;s + In general, you can use one of the following two approaches to deploy an application that depends on an existing &DSCL;: + + + + + 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 &DSCL; for your application: + + Create a &DSCL; metapackage + + + Each &DSCL; includes a metapackage, which installs a minimal subset of essential packages. See for more information on creating metapackages. + + + + + Specify the location of the &DSCL; root directory + + + Ensure that the location of the &DSCL; root directory is specified by setting the %_scl_prefix macro in the &DSCL; spec file. For more information, see . + + + + + Prefix the name of your &DSCL; packages + + + Ensure that the name of your &DSCL; packages is prefixed with the vendor and &DSCL;'s name. For more information, see . + + + + + Specify all &DSCL;s and other packages required by your application as dependencies + + + Ensure that all &DSCL;s and other packages required by your application are specified as dependencies of your &DSCL;. For more information, see . + + + + + Convert existing conventional packages or create new &DSCL; packages + + + Ensure that all macros in your &DSCL; package spec files use conditionals. See for more information on how to convert an existing package spec file. + + + + + Build your &DSCL; + + + After you create the &DSCL; metapackage and convert or create packages for your &DSCL;, you can build the &DSCL; with the rpmbuild utility. For more information, see . + + + + +
+
+ The File System Hierarchy + The root directory of &DSCL;s is normally located in the /&OPT;/ directory to avoid possible conflicts between &DSCL;s 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 &DSCL;s, &DSCL; 1 and &DSCL; 2: + &OPT; +`-- &RH; + |-- &DSCL; 1 + | |-- &DSCL; root directory + | `-- &DSCL; scriptlets + | + `-- &DSCL; 2 + |-- &DSCL; root directory + `-- &DSCL; scriptlets + + As you can see in the example above, each of the &DSCL;s directories contains two subdirectories: the &DSCL; root directory and a directory containing the &DSCL; scriptlets. For more information on the &DSCL; scriptlets, refer to . +
+
+ The &DSCL; 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: + %_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 &DSCL;s should use its own provider name, which conforms to the Filesystem Hierarchy Standard (FHS) and avoids possible conflicts between &DSCL;s 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/. +
+
+ The &DSCL; Prefix + + When naming your &DSCL;, it is important to prefix the name of your &DSCL; as described below in order to avoid possible name conflicts with the system versions of the packages that are part of your &DSCL;. + + + The &DSCL; prefix consists of two parts: + + + + + the provider part, which defines the provider name, and + + + + + the name of the &DSCL; itself. + + + + These two parts of the &DSCL; prefix are separated by an underscore (_), as in the following example: + myorganization_ruby193 + In this example, myorganization is the provider name, and ruby193 is the name of the &DSCL;. + +
+
+ &DSCL; Package Names + + The &DSCL; package name consists of two parts: + + + + + the prefix part, discussed in , and + + + + + the name and version number of the application that is a part of the &DSCL;. + + + + These two parts of the &DSCL; 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. +
+
+ &DSCL; Scriptlets + The &DSCL; scriptlets are simple shell scripts that change the current system environment so that the group of packages in the &DSCL; is preferred over the corresponding group of conventional packages installed on the system. + To utilize the &DSCL; scriptlets, use the scl tool. For more information on scl, refer to . +
+
+ Package Layout + Each &DSCL;'s layout consists of the metapackage, which installs a subset of other packages, and a number of the &DSCL;'s packages, which are installed within the &DSCL; namespace. +
+ Metapackage + Each &DSCL; includes a metapackage, which installs a minimal subset of essential packages. 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 &DSCL;'s scriptlets. + The purpose of the metapackage is to make sure that all essential packages in the &DSCL; are properly installed and that it is possible to enable the &DSCL;. + The metapackage produces the following packages that are also part of the &DSCL;: + + + The main package: %scl + + The main package in the &DSCL; contains dependencies of the base packages, which are included in the &DSCL;. The main package does not contain any files. + For example, if the name of the &DSCL; is myorganization_ruby193, then the main package macro is expanded to: + myorganization_ruby193 + + + + The runtime subpackage: name-runtime + + The runtime subpackage in the &DSCL; owns the &DSCL;'s file system and delivers the &DSCL;'s scriptlets. + For example, if the name of the &DSCL; is myorganization_ruby193, then the runtime subpackage macro is expanded to: + myorganization_ruby193-runtime + + + + The build subpackage: name-build + + The build subpackage in the &DSCL; delivers the &DSCL;'s build configuration. The build subpackage is optional and can be excluded from the &DSCL;. + For example, if the name of the &DSCL; is myorganization_ruby193, then the build subpackage macro is expanded to: + myorganization_ruby193-build + + + +
+
+Creating a Metapackage + + When creating a new metapackage: + + + You are advised to add Requires: scl-utils-build to the build subpackage. + + + + + Add any macros you need to use to the macros.%{scl}-config file in the build subpackage. + + + + + You are not required to use conditionals for &DSCL;-specific macros in the metapackage. + + + + + Consider specifying all packages in your &DSCL; that are essential for the &DSCL; run time as dependencies of the metapackage. That way you can ensure that the packages are installed with the &DSCL; metapackage. + + + + + Include any path redefinition that the packages in your &DSCL; may require in the enable scriptlet. + + + For example, to run &DSCL; binary files, add PATH=%{_bindir}\${PATH:+:\${PATH}} to the enable scriptlet. + + + + + Always make sure that the metapackage spec file contains the %setup -c -T command in the %prep section, otherwise building the metapackage will fail. + + + This is because the %setup command 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 metapackage spec file, files in the %buildsubdir directory will be overwritten, causing the build to fail. + + + +Example of the Metapackage +To get an idea of what a typical &DSCL; metapackage looks like, see the following example: + %global scl software_collection +%scl_package %scl +%_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. + +%prep +%setup -c -T + +%install +rm -rf %{buildroot} +mkdir -p %{buildroot}%{_scl_scripts}/root +cat >> %{buildroot}%{_scl_scripts}/enable << EOF +export PATH=%{_bindir}\${PATH:+:\${PATH}} +EOF +%scl_install + +%files + +%files runtime +%scl_files + +%files build +%{_root_sysconfdir}/rpm/macros.%{scl}-config + +%changelog +* Fri Aug 30 2013 John Doe <jdoe@example.com> 1-1 +- Initial package + +
+
&DSCL; Macros The &DSCL; packaging macro scl relocates the file structure, which is part of the &DSCL;, to a file system that is used exclusively by the &DSCL;. - The scl macro also defines files ownership for the &DSCL;'s meta package and provides additional packaging macros to use in the &DSCL; environment. + The scl macro also defines files ownership for the &DSCL;'s metapackage and provides additional packaging macros to use in the &DSCL; environment. When using &DSCL; macros in the spec file, you must prefix them with %{?scl:macro}, as in the following example: %{?scl:Requires:%scl_runtime} @@ -61,6 +345,21 @@ + %scl_prefix + + + + name of the &DSCL; with a dash appended at the end + + + + software_collection_1- + + + + + + %pkg_name @@ -402,7 +701,7 @@ %_root_libdir - &DSCL;'s %_libdir macro, this macro does not work if &DSCL;'s meta package is platform-independent + &DSCL;'s %_libdir macro, this macro does not work if &DSCL;'s metapackage is platform-independent no @@ -438,13 +737,37 @@ Software Collection macros simply relocate package to non-conflicting namespaced Name: %{?scl_prefix}package_name - To check that all essential &DSCL;'s packages are dependencies of the main meta package, add the following macro after the BuildRequires or Requires tags in the spec file: + To check that all essential &DSCL;'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} + + Prefix the Obsoletes, Conflicts and BuildConflicts tags with %{?scl_prefix}. This is to ensure that the &DSCL; 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 < 1.0 + + + + Prefix the Provides tag with %{?scl_prefix}, as in the following example: + + Provides: %{?scl_prefix}more + + + + For any subpackages that define their name with the option, prefix their name with %{?scl_prefix}, as in the following example: + + %package -n %{?scl_prefix}more + + Edit the %setup macro in the %prep section of the spec file so that the macro can deal with a different package name in the &DSCL; environment: %setup -q -n %{pkg_name}-%{version} + Example of the Converted Spec File To see what the diff file comparing a conventional spec file with a converted spec file looks like, see the following example: @@ -470,6 +793,8 @@ Software Collection macros simply relocate package to non-conflicting namespaced Requires: groff BuildRequires: ncurses-devel BuildRequires: autoconf automake libtool +-Obsoletes: lesspipe < 1.0 ++Obsoletes: %{?scl_prefix}lesspipe < 1.0 +%{?scl:Requires: %scl_runtime} %description @@ -506,292 +831,53 @@ Software Collection macros simply relocate package to non-conflicting namespaced %{_mandir}/man1/*
+
+ Uninstalling all &DSCL; directories + + Keep in mind that the yum remove command does not uninstall directories provided by those &DSCL; packages and subpackages that are removed after the &DSCL; 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 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. + +
Using a &DSCL; in Your Application To use a &DSCL; in your application, you need to adjust the BuildRequires and Requires tags in your application's spec file so that these tags properly define dependencies on &DSCL;s. For example, to define dependencies on two &DSCL;s 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 +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 &DSCL;. + + + You can also use the %scl_require_package macro to define dependencies on a particular package from a specific &DSCL;, as in the following example: + + BuildRequires: scl-utils-build +Requires: %scl_require_package software_collection_1 package_name
-
- Installing a &DSCL; - To ensure that a &DSCL; is on your system, install the main meta package of the &DSCL;. You can use conventional tools like Yum or PackageKit for this task because &DSCL;s are fully compatible with the RPM Package Manager. For example, to install a &DSCL; named software_collection_1 with Yum, run the following command: - - yum install -y software_collection_1 - - This command will automatically install all the packages that are part of the &DSCL;. Also, if you install an application that depends on a &DSCL;, the &DSCL; will be installed along with the rest of the application's dependencies. -For detailed information on Yum and PackageKit usage, refer to the Fedora 17 System Administrator's Guide. -
-
- Listing Installed &DSCL;s - To get a list of &DSCL;s that are currently installed on the system, run the following command: +
+ Building a &DSCL; + To build a &DSCL; on your system, run the following command: - scl --list + 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 option to the rpmbuild command when building a &DSCL;. + The option defines the scl macro, which uses the &DSCL; configured in the &DSCL; spec file (package.spec). +
+ Rebuilding a &DSCL; without build subpackages + + If you wish to rebuild a &DSCL; that is distributed without build subpackages (software_collection-build) and you do not want or cannot use the rpmbuild -ba package.spec --define 'scl name' command to build the &DSCL;, you can have the build subpackages created by rebuilding the &DSCL; metapackage. Note that you need to have the scl-utils-build package installed on your system, otherwise rebuilding the &DSCL; metapackage with the rpmbuild command will fail. +
- -
- &DSCL; Initscript Support - Ensure that users can directly manage any services provided by the &DSCL; or one of the associated applications with the system default tools, like service or chkconfig. - To avoid possible name conflicts with the system versions of the services that are part of the &DSCL;, make sure to adjust the %install section of the spec file as follows: - -%install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/rc.d/%{?scl_prefix}service_name - - With this configuration in place, you can then refer to the version of the service included in the &DSCL; as follows: - %{?scl_prefix}service_name -
-
- &DSCL; Library Support - In case you distribute libraries that you intend to use only in the &DSCL; environment or in addition to the libraries available on the system, adjust the LD_LIBRARY_PATH environment variable in the spec file as follows: - -export LD_LIBRARY_PATH=%{_libdir}:$LD_LIBRARY_PATH - - This configuration ensures that the version of the library in the &DSCL; is preferred over the version of the library available on the system if the &DSCL; is enabled. - - - In case you distribute a private shared library in the &DSCL;, consider using the DT_RUNPATH attribute instead of the LD_LIBRARY_PATH environment variable to make the private shared library accessible in the &DSCL; environment. - - -
- Using a Library Outside of the &DSCL; - If you distribute libraries that you intend to use outside of the &DSCL; environment, you can use the directory /etc/ld.so.conf.d/ for this purpose. - - - Do not use /etc/ld.so.conf.d/ for libraries already available on the system. Using /etc/ld.so.conf.d/ is only recommended for a library that is not available on the system, as otherwise the version of the library in the &DSCL; might get preference over the system version of the library. That could lead to undesired behavior of the system versions of the applications, including unexpected termination and data loss. - - - Using /etc/ld.so.conf.d/ for libraries in the &DSCL; - - Create a file named libs.conf and adjust the spec file configuration accordingly: - -SOURCE2: %{?scl_prefix}libs.conf - - - - In the libs.conf file, include a list of directories where the versions of the libraries associated with the &DSCL; are located. For example: - /&OPT;/&RH;/software_collection_1/root/usr/lib64/ - - In the example above, the /usr/lib64/ directory that is part of the &DSCL; software_collection_1 is included in the list. - - - Edit the %install section of the spec file, so the libs.conf file is installed as follows: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/ld.so.conf.d/ - - - -
-
- Prefixing the Library Major soname with the &DSCL; Name - - When using libraries included in the &DSCL;, always remember that a library with the same major soname can already be available on the system as a part of the base system installation. It is thus important not to forget to use the scl enable command when building an application against a library included in the &DSCL;. Failing to do so may result in the application being executed in an incorrect environment, linked against the incorrect system version of the library. - - Keep in mind that executing your application in an incorrect environment (for example in the system environment instead of the &DSCL; environment) as well as linking your application against an incorrect library can lead to undesired behavior of your application, including unexpected termination and data loss. - -To ensure that your application is not linked against an incorrect library even if the LD_LIBRARY_PATH environment variable has not been set properly, change the major soname of the library included in the &DSCL;. The recommended way to change the major soname is to prefix the major soname version number with the &DSCL; name. - - - Below is an example of the MySQL client library with the mysql55- prefix: - - -$ rpm -ql mysql55-mysql-libs | grep 'lib.*so' -/usr/lib64/mysql/libmysqlclient.so.mysql55-18 -/usr/lib64/mysql/libmysqlclient.so.mysql55-18.0.0 - - - On the same system, the system version of the MySQL client library is listed below: - - -$ rpm -ql mysql-libs | grep 'lib.*so' -/usr/lib64/mysql/libmysqlclient.so.18 -/usr/lib64/mysql/libmysqlclient.so.18.0.0 - -
-
-
- &DSCL; .pc Files Support - The .pc files are special metadata files used by the pkg-config program to store information about libraries available on the system. In case you distribute .pc files that you intend to use only in the &DSCL; environment or in addition to the .pc files installed on the system, adjust the PKG_CONFIG_PATH environment variable. Depending on what is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable for the %{_libdir} macro (which expands to the library directory, typically /usr/lib/ or /usr/lib64/), or for the %{_datadir} macro (which expands to the share directory, typically /usr/share/). - If the library directory is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable in the spec file as follows: - -export PKG_CONFIG_PATH=%{_libdir}/pkgconfig:\$PKG_CONFIG_PATH - - If the share directory is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable in the spec file as follows: - -export PKG_CONFIG_PATH=%{_datadir}/pkgconfig:\$PKG_CONFIG_PATH - - This configuration ensures that the .pc files in the &DSCL; are preferred over the .pc files available on the system if the &DSCL; is enabled. - The &DSCL; can provide a wrapper script that is visible to the system to enable the &DSCL;, for example in the /usr/bin/ directory. In this case, ensure that the .pc files are visible to the system even if the &DSCL; is disabled. - To allow your system to use .pc files from the disabled &DSCL;, update the PKG_CONFIG_PATH environment variable with the paths to the .pc files associated with the &DSCL;. Depending on what is defined in your .pc files, adjust the PKG_CONFIG_PATH environment variable for the %{_libdir} macro (which expands to the library directory), or for the %{_datadir} macro (which expands to the share directory). -Updating the PKG_CONFIG_PATH environment variable for %{_libdir} -To update the PKG_CONFIG_PATH environment variable for the %{_libdir} macro, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. -For example, create the following file: - %{?scl_prefix}pc-libdir.sh -Use the pc-libdir.sh short script that modifies the PKG_CONFIG_PATH variable to refer to your .pc files: - export PKG_CONFIG_PATH=%{_libdir}/pkgconfig:/&OPT;/&RH;/software_collection/path/to/your/pc_files -Add the file to your &DSCL; package's spec file: -SOURCE2: %{?scl_prefix}pc-libdir.sh - Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ - - -Updating the PKG_CONFIG_PATH environment variable for %{_datadir} -To update the PKG_CONFIG_PATH environment variable for the %{_datadir} macro, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. -For example, create the following file: - %{?scl_prefix}pc-datadir.sh -Use the pc-datadir.sh short script that modifies the PKG_CONFIG_PATH variable to refer to your .pc files: - export PKG_CONFIG_PATH=%{_datadir}/pkgconfig:/&OPT;/&RH;/software_collection/path/to/your/pc_files -Add the file to your &DSCL; package's spec file: -SOURCE2: %{?scl_prefix}pc-datadir.sh - Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ - - -
-
- &DSCL; manpath Support - To allow the man command on the system to display manual pages from the enabled &DSCL;, update the MANPATH environment variable with the paths to the manual pages that are associated with the &DSCL;. - To update the MANPATH environment variable, add the following line to the spec file: - export MANPATH=${MANPATH}:%{_mandir} - This update relocates the %{_mandir} macro to the &DSCL; path. So that the manual pages associated with the &DSCL; are not visible as long as the &DSCL; is not enabled. - The &DSCL; can provide a wrapper script that is visible to the system to enable the &DSCL;, for example in the /usr/bin/ directory. In this case, ensure that the manual pages are visible to the system even if the &DSCL; is disabled. - To allow the man command on the system to display manual pages from the disabled &DSCL;, update the MANPATH environment variable with the paths to the manual pages associated with the &DSCL;. -Updating the MANPATH environment variable for the disabled &DSCL; -To update the MANPATH environment variable, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. -For example, create the following file: - %{?scl_prefix}manpage.sh -Use the manpage.sh short script that modifies the MANPATH variable to refer to your man path directory: - export MANPATH=${MANPATH}:/&OPT;/&RH;/software_collection/path/to/your/man_pages -Add the file to your &DSCL; package's spec file: -SOURCE2: %{?scl_prefix}manpage.sh - Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ - - -
-
- &DSCL; SystemTap Support - SystemTap is a useful instrumentation platform for probing running processes and kernel activity on the Linux system. In case you distribute the SystemTap data directory for cached SystemTap data files that you intend to use only in the &DSCL; environment or in addition to the SystemTap data files available on the system, adjust the XDG_DATA_DIRS environment variable in the spec file as follows: - -export XDG_DATA_DIRS=%{_datadir}:\$XDG_DATA_DIRS - - This configuration ensures that the SystemTap data files in the &DSCL; are preferred over the SystemTap data files available on the system if the &DSCL; is enabled. - The &DSCL; can provide a wrapper script that is visible to the system to enable the &DSCL;, for example in the /usr/bin/ directory. In this case, ensure that the SystemTap data files are visible to the system even if the &DSCL; is disabled. - To allow your system to use SystemTap data files from the disabled &DSCL;, update the XDG_DATA_DIRS environment variable with the paths to the SystemTap data files associated with the &DSCL;. -Updating the XDG_DATA_DIRS environment variable for the disabled &DSCL; -To update the XDG_DATA_DIRS environment variable, create a custom script /etc/profile.d/name.sh. The script is preloaded when a shell is started on the system. -For example, create the following file: - %{?scl_prefix}systemtap.sh -Use the systemtap.sh short script that modifies the XDG_DATA_DIRS variable to refer to your SystemTap data files directory: - export XDG_DATA_DIRS=${XDG_DATA_DIRS}:/&OPT;/&RH;/software_collection/path/to/your/systemtap_data_files -Add the file to your &DSCL; package's spec file: -SOURCE2: %{?scl_prefix}systemtap.sh - Install this file into the system /etc/profile.d/ directory by adjusting the %install section of the &DSCL; package's spec file: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/profile.d/ - - -
-
- &DSCL; cronjob Support - With your &DSCL;, you can run regular tasks on the system either with a dedicated service or with cronjobs. If you intend to use a dedicated service, refer to on how to work with initscripts in the &DSCL; environment. - - Running regular tasks with cronjobs - - To use cronjobs for running regular tasks, place a crontab file for your &DSCL; in the /etc/cron.d/ directory with the &DSCL;'s name. - For example, create the following file: - %{?scl_prefix}crontab - - - Ensure that the contents of the crontab file follow the standard crontab file format, as in the following example: - 0 1 * * Sun root /&OPT;/&RH;/software_collection/architecture/usr/bin/cron_job_name - - - Add the file to your spec file of the &DSCL; package: - SOURCE2: %{?scl_prefix}crontab - - - Install the file into the system directory /etc/cron.d/ by adjusting the %install section of the &DSCL; package's spec file: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/cron.d/ - - - -
-
- &DSCL; logrotate Support - With your &DSCL; or an application associated with your &DSCL;, you can manage log files with the logrotate program. - - Managing log files with logrotate - - To manage your log files with logrotate, place a custom logrotate file for your &DSCL; in the system directory for the logrotate jobs /etc/logrotate.d/. - For example, create the following file: - %{?scl_prefix}logrotate - - - Ensure that the contents of the logrotate file follow the standard logrotate file format as follows: - /&OPT;/&RH;/software_collection/var/log/your_application_name.log { - missingok - notifempty - size 30k - yearly - create 0600 root root - } - - - Add the file to your spec file of the &DSCL; package: - SOURCE2: %{?scl_prefix}logrotate - - - Install the file into the system directory /etc/logrotate.d/ by adjusting the %install section of the &DSCL; package's spec file: - %install -install -p -c -m 644 %{SOURCE2} $RPM_BUILD_ROOT%{?scl:%_root_sysconfdir}%{!?scl:%_sysconfdir}/logrotate.d/ - - -
-
- &DSCL; Lock File Support - If you store your &DSCL;'s lock files within the /&OPT;/&RH;/software_collection/ file system hierarchy, you can avoid any possible conflicts with the system versions of the applications or services that can be on the system. - If you want to prevent &DSCL;'s applications or services from running while the system version of the respective application or service is running, make sure that your applications or services, which require a lock, write the lock to the system directory /var/lock/ instead of the &DSCL;'s directory /&OPT;/&RH;/software_collection/var/lock/. In this way, your applications or services' lock file will not be overwritten. The lock file will not be renamed and the name stays the same as the system version. - If you want your &DSCL;'s version of the application or service to run concurrently with the system version (when the &DSCL; version's resources will not conflict with the system version's resources), ensure that the applications or services write the lock to the &DSCL;'s directory /&OPT;/&RH;/software_collection/var/lock/. -
-
- &DSCL; Configuration Files Support - If you store your &DSCL;'s configuration files within the /&OPT;/&RH;/software_collection/ file system hierarchy, you can avoid any possible conflicts with the system versions of the configuration files that can be present on the system. - If you cannot store the configuration files within /&OPT;/&RH;/software_collection/, then ensure that you properly configure an alternative location for the configuration files. For many programs, this can be usually done at build or installation time. -
-
- &DSCL; Kernel Module Support - Because Linux kernel modules are normally tied to a particular version of the Linux kernel, you must be careful when you package kernel modules into a &DSCL;. This is because the package management system on &MAJOROS; does not automatically update or install an updated version of the kernel module if an updated version of the Linux kernel is installed. To make packaging the kernel modules into the &DSCL; easier, see the following recommendations. Ensure that: - - - the name of your kernel module package includes the kernel version, - - - the tag Requires, which can be found in your kernel module spec file, includes the kernel version and revision (in the format kernel-version-revision). - - -
-
- &DSCL; SELinux Support - Because &DSCL;s are designed to install the &DSCL; packages in an alternate directory, set up the necessary SELinux labels so that SELinux is aware of the alternate directory. - If the file system hierarchy of your &DSCL; package imitates the file system hierarchy of the corresponding conventional package, you can run the semanage fcontext and restorecon commands to set up the SELinux labels. - For example, if the /&OPT;/&RH;/software_collection_1/x86_64/root/usr/ directory in your &DSCL; package imitates the /usr/ directory of your conventional package, set up the SELinux labels as follows: - - semanage fcontext -a -e /usr /&OPT;/&RH;/software_collection_1/x86_64/root/usr - - - restorecon -R -v /&OPT;/&RH;/software_collection_1/x86_64/root/usr - - The commands above ensure that all directories and files in the /&OPT;/&RH;/software_collection_1/x86_64/root/usr/ directory are labeled by SELinux as if they were located in the /usr/ directory. - To use the semanage fcontext and restorecon commands in your &DSCL;, add the commands to the %post post-installation scriptlet in the &DSCL; spec file.
diff --git a/en-US/Preface.xml b/en-US/Preface.xml index cde4efa..fb92a3c 100644 --- a/en-US/Preface.xml +++ b/en-US/Preface.xml @@ -9,7 +9,7 @@
Acknowledgments - The author of this book would like to thank the following people for their valuable contributions: Jindřich Nový, Marcela Mašláňová, Bohuslav Kabrda, Honza Horák, Jan Zelený, Langdon White, Florian Nadge, Stephen Wadeley, Douglas Silas, and Vít Ondruch, among many others. + The author of this book would like to thank the following people for their valuable contributions: Jindřich Nový, Marcela Mašláňová, Bohuslav Kabrda, Honza Horák, Jan Zelený, Martin Čermák, Langdon White, Florian Nadge, Stephen Wadeley, Douglas Silas, and Vít Ondruch, among many others.
diff --git a/en-US/Revision_History.xml b/en-US/Revision_History.xml index cedd6ab..87a3247 100644 --- a/en-US/Revision_History.xml +++ b/en-US/Revision_History.xml @@ -6,6 +6,20 @@ + 1-2 + Wed Sep 18 2013 + + Petr + Kovář + pkovar@redhat.com + + + + 1-2 release of the Software Collections Guide. + + + + 1-1 Mon Feb 18 2013 diff --git a/en-US/Software_Collections_Guide.ent b/en-US/Software_Collections_Guide.ent index e63ccb1..b3075f5 100644 --- a/en-US/Software_Collections_Guide.ent +++ b/en-US/Software_Collections_Guide.ent @@ -2,11 +2,11 @@ - + - + - + diff --git a/en-US/Software_Collections_Guide.xml b/en-US/Software_Collections_Guide.xml index aba66f4..ecee9e4 100644 --- a/en-US/Software_Collections_Guide.xml +++ b/en-US/Software_Collections_Guide.xml @@ -10,6 +10,8 @@ xmlns:xi="http://www.w3.org/2001/XInclude" /> +