Packaging HowTo

What links here (5) →

This HOWTO Tutorial is aimed at helping people who want to produce software packages which should integrate well in the ROSA distribution of GNU/Linux. In particular, it will stress in what way the packages are slightly different from the packages anyone would write for other rpm-based distributions. This document should be useful to ROSA developers, but also to external people.

Caution!

Building RPM's as root is dangerous, because the binary files are installed on the system before being packaged, thus you must always build as normal user so you won't accidentally pollute your system.

Foreword

It is assumed in this document that the reader is "linux-ready". He/she already knows the basic commands, directory structure and has already used rpm, at least for installing packages.

This document is constructed as a step-by-step recipe to create an rpm package, that can integrate well into the ROSA distribution of GNU/Linux, from either a previous source rpm or from a tar source.

RPM roughly means three things:

• a program intended to install or create packages,
• a format used in packages (source or binary) created by the program rpm,
• a file called package which contains either a binary or sources along with an information header about how to install/uninstall the program.

The program rpm is, from the user's point of view, a powerful package manager. It acts as a "conductor" for any action on rpm packages. Amongst other things, it can:

• install or upgrade a package and verify dependencies,
• while installing a package, perform actions in order to make the installed program ready to use,
• restore accidentally erased files belonging to a package,
• check if a package is already installed,
• find to which package a particular file belongs,
• verify the current installation as to the fulfilment of dependency requirements of installed packages,
• ....

From the programmer's point of view, the rpm program is a packager which encapsulates, in a single rpm file, all the information needed to install a program on a given platform.

It is important to distinguish from the beginning, the difference between source ( .src.rpm ) and binary (.<archtype>.rpm) packages.

The first one contains (yes you guessed) the complete source tree from the original programmer, plus all the stuff the packager added in order to configure, compile and install the program. It generally consists of a spec file (the file used to instruct rpm which operations it has to perform, in order to create the package) along with patches, if any.

The second one contains the compiled binary, and all the files (documentation, config files, icons,...) that will be installed on the target system. It also contains the procedure used to place the files in their correct location and the actions to perform in order to make the program operable.

Preparing the software

The basics

Although RPM was originally designed to work with Red Hat Linux, it also works on other rpm-based distributions: ROSA, Mandriva Linux, Suse, etc ; rpm is already installed on these systems.

ROSA uses an offspring of Red Hat's RPM, RPM5. You can get the vanilla rpm5 distribution here.

Rpm5 is backwards compatible with rpm4, and the specs prepared for rpm4, which most rpm-based distributions use, should work with rpm5; of course, they must also comply to ROSA policy.

Building for ROSA

Building packages for the development version of ROSA is always subject to small patches and enhancements to the rpm program in use. To use the very exact rpm build tools used at our build system, download the development version of ROSA first. Then, install through your package manager (see Installing and removing software) the following packages:

• The package rpm which is our patched version of RPM5 (should already be installed);
• The package rpm-build which contains scripts used to build packages;
• The package rpmlint which is used to check the validity of the generated src.rpm.

In the rest of this howto, "rpm" means the rpm5 version shipped with ROSA.

Preliminary actions

Create required folders

To build packages, rpm needs a special tree in your home directory. This tree can be created with the following command: mkdir -p ~/rpmbuild/{BUILD,BUILDROOT,RPMS/i586,RPMS/x86_64,RPMS/noarch,SOURCES,SRPMS,SPECS,tmp} .

Make sure that the tree is of the form:

• ~/rpmbuild/BUILD: The directory where the sources are built.
• ~/rpmbuild/BUILDROOT: The directory where the install will be simulated
• ~/rpmbuild/RPMS: Contains the directories, one for each architecture, that will receive the binary packages after.
• ~/rpmbuild/RPMS/i586: The directory where rpm packages for i586 processors will be stored.
• ~/rpmbuild/RPMS/x86_64: The directory where rpm packages for AMD64 processors will be stored.
• ~/rpmbuild/RPMS/noarch: Idem for noarch (processor-independent) packages.
• ~/rpmbuild/SOURCES: The source files (mypackage.tar.bz2, for example, and patches).
• ~/rpmbuild/SPECS: The spec files we will have to construct.
• ~/rpmbuild/SRPMS: The source rpm after building.
• ~/rpmbuild/tmp: For temporary stuff that rpm will create when building your packages, you can find the script which are generated to actually build and package your package here, they are generated from the spec file and can be handy for debugging.

Note:

The architecture directories under ~/rpmbuild/RPMS are necessary to rpm. If they are not present, you'll get an error message.

Do not create .rpmmacros file

Guides for some distributions say that you should create an ~/.rpmmacros file to add some personal information to your packages, such as %packager, %vendor, etc. Do not do this. The build scripts run inside the build system assign these fields automatically.

Building an RPM package

From a source package

This is generally the case for the packages which are already included in the distribution.

The latest rpm files from cooker are available on many mirrors whose list is available at Cooker Mirrors. There you will find under TODO: verify mirror list:

• SRPMS for source rpms (main, contrib, jpackage, others) and under the cpu architecture (e.g. i586, x86_64, ...):
• media/main for main binary rpms.
• media/contrib for contrib binary rpms.
• media/jpackage for noarch binary rpms.

When you find the source rpm you want to modify for ROSA, just issue rpm -ivh mypackage.src.rpm; it will install all source files into your RPM directory. You can also use urpmi to download the source.

For example:

[camille@kenobi ~/rpmbuild]$ rpm -i /cooker/SRPMS/ktron-1.0.1-rosa2012.src.rpm 
[camille@kenobi ~/rpmbuild]$ ls -R * 
SRPMS:
SPECS:
ktron.spec
SOURCES:
ktron-1.0.1.tar.bz2
RPMS:
noarch/ i686/ i586/ i386/
BUILD: 

We see that rpm has installed in our RPM tree the source file ktron-1.0.1.tar.bz2 and the spec file. Even before building a newer version of a package, it might be very interesting for you to rebuild the current package in order to understand how it is compiled and if it compiles. The magic command for doing this is rpmbuild with the option buildall:

[camille@kenobi ~/rpmbuild]$ cd ~/rpmbuild/SPECS
[camille@kenobi ~/rpmbuild]$ rpmbuild -ba ktron.spec
[camille@kenobi ~/rpmbuild]$ ls -l ~/rpmbuild/RPMS/i586/ktron-1.0.1-rosa2012.i586.rpm
[camille@kenobi ~/rpmbuild]$ ls -l ~/rpmbuild/SRPMS/ktron-1.0.1-rosa2012.src.rpm

If the build finished (it can last hours for some packages like kernels) without errors, you will get the binary rpm and the src rpm into your ~/rpmbuild/RPMS/i586 and ~/rpmbuild/SRPMS/ subdirectories respectively. If you want to install the binary rpm, you must act as 'root' which you can access to by typing su (and exit by typing exit). But in order to build an rpm, and to expand an src.rpm, you do not have to, and must not be root.

The log of the build might be very long, and it's a good practice to store it for later browsing. You may use tee for that.

In the ~/rpmbuild/BUILD sub-directories you will usually access to the patched sources (if one or more patches were given in ~/rpmbuild/SOURCES), to the binaries, compiled libraries, man pages etc. The spec file describes the source and patch files, how to build the package and how to install the package.

Modifying src.rpm is not how existing packages are modified. ROSA sources do not store src.rpm files. It stores .spec files and the accompanying sources in a Git repository, and the src.rpm files are generated from them during the package build on the build system.

From raw (tarball) sources

For example, if you find an interesting program at github or SourceForge, or created one on your own, you may want to make it available to all ROSA users. The best way to do that is to create a project in ABF, and create an RPM spec file that conforms to ROSA standards and guidelines.

First, download the tarball with sources, and place it in the ~/rpmbuild/SOURCES directory.

Preliminary checks

License

Despite the prevalence of GPL licenses, there are still a number of non-GPL licenses in use today. Check the license of the software carefully to determine whether or not it may be incorporated in the distribution. We do not accept non-free software, but some exceptions exist for the club. Also, we cannot accept software that does not allow us to freely distribute it. Watch out for these programs. A list of licenses and acceptable software may be found on ROSA Licensing Policy

Tarball Compression

To save efforts to maintain in the future, it is recommended to use the original tarball without any modifications. If sources are provided in various compression methods, we often choose .tar.bz2. Avoid compressing text format patches (as produced by diff and the likes) and other configuration/scripts/etc. (text) files, as it usually saves very little space, while making harder to see the changes in Git diffs (which already uses some form of compression). Note: For high-risk security-critical packages we recommend that you don't modify the original source distribution at all, as it will change the checksum/signature. For these kinds of packages we recommend that you leave it in the original form, so that when someone runs md5sum/gpg on it, it will match the values as listed at the download location. One such example where this exception may apply would be OpenSSH.

Inside the spec file

Here we are. This is the important section of this document. The spec file contains all the information needed by rpm to:

1. compile the program and build source and binary rpms,
2. install, uninstall, and update the program on the final user's machine.

The fact that these two types of information are combined into one single file may be quite confusing for the beginner. Actually, this is due to the source tar tree, which contains already this information. As installation procedure is extracted from the installation process generally run by make install into the source tree, both parts are tightly linked.

In a nutshell, the spec file describes a "simulated" compilation and installation, tells rpm which files resulting from this installation are to be packed, and how to finally install these files onto the user's system. Commands there are executed using the /bin/sh shell, so things like [ -f configure.in ] && autoconf are valid.

This part is not intended to explain in detail all the features of a spec file. The book Maximum RPM (see Section 7) explains it in depth. All we are going to do here is quickly check all of the features used in one standard example ROSA spec file.

This is an example from the cooker repository. You may also consider our template spec files to start one from scratch.

As you build more and more RPMs,you will find that there are some options that we have not told you about. RPM is extremely extensible, so, finding out all of those is left as an exercise to the reader. It is always good practice to open up some spec files to take a look at them and see how they work.

%define name    gif2png 
%define version 2.0.1 

Name:           %{name} 
Summary:        Tools for converting websites from using GIFs to using PNGs 
Version:        %{version} 
Release:        1
Source0:        http://www.tuxedo.org/~esr/gif2png/%{name}-%{version}.tar.bz2 
Source1:        %{name}-%{version}-rosa-addon.tar.bz2 
Patch0:         gif2png-2.0.1-bugfix.patch
URL:            http://www.tuxedo.org/~esr/gif2png/ 

Group:          Applications/Multimedia 
License:        MIT-like 
Requires:       python 

%description
Tools for converting GIFs to PNGs. The program gif2png converts GIF files
to PNG files. The Python script web2png converts an entire web tree, also
patching HTML pages to keep IMG SRC references correct.

%prep 
%setup -q -a 1 
%patch -p1 

%build 
%configure 
%make

%install
%makeinstall

%files 
%defattr(0755,root,root) 
%doc README NEWS COPYING AUTHORS 
%{_mandir}/man1/gif2png.1*
%{_mandir}/man1/web2png.1*
%{_bindir}/gif2png 
%{_bindir}/web2png 

# Omit %changelog when you're creating RPM packages for ROSA!  This is only an example!
%changelog 
* Mon Nov 02 1999 Camille Begnis <camille@mandrakesoft.com> 2.0.1-rosa2012
- Upgraded to 2.0.1 

* Mon Oct 25 1999 Camille Begnis <camille@mandrakesoft.com> 2.0.0-rosa2012
- Specfile adaptations for Mandrake
- add python requirement
- gz to bz2 compression

Let's then analyze in detail each line of this file:

Be careful, a % at the beginning of a line may tell different things :

• the beginning of a section (prep, build, install, files)
• a built-in shell script macro (setup, patch)
• a directive used by a special section (defattr, doc, ...)

Header section

The header section should contain standard name, version and release tags:

Name:           gif2png
Version:        2.0.1
Release:        1

These three lines automatically define macros that may be used in many following sections of the spec file, named %{name} , %{version} and %{release} . Note that some packages can have obsolete call to %mkrel macro which simply returns its argument in ROSA.

The name of the package as used in the package's name and in the package database on the user's machine. This is the string users will see in the package manager as a name of your package.

At this point we must explain how the name of a package is formed. It is important to always respect this standard in order to make your work understandable to others.

There are also some tags that you might want to know about, but which are not in the spec file example. There are some that you might encounter. It is not expected that you remember all of this if you just started building rpms, but after some time, this list makes good reference!

• A binary package is named as: name-version-release-rosa2012.arch.rpm (rosa2012 designates DISTTAG and DISTEPOCH and is automatically added by rpmbuild)
• A source package is named as: name-version-release.src.rpm (i.e. gif2png-2.0.1.src.rpm in our example)

The name is generally chosen to be the name of the main binary of the package, though with adequate reason you can get away with another name.

The version is the number from the unpatched sources. It is the version number in the name of the original archive file: name-version.tar.gz.

The release is a number which is incremented at each new build of the package. This may be due to a patch applied to the sources, a modification to the spec file, the addition of an icon, etc.

The name of the package is automatically generated from Release:, Version:, and Name: fields.

Summary: tools for converting websites from using GIFs to using PNGs

This line is a one-liner of the package description. It should be less than 80 characters long (see RPM spec file syntax).

Source0:        http://www.tuxedo.org/~esr/gif2png/%{name}-%{version}.tar.bz2 

This line tells rpm what source file to use for building this package. Note that the filename is preceded by a complete URL (which is optional) pointing to the site where the original source is available; rpm will remove the url, keep the filename only, and search in the SOURCES directory. Although we say that the complete URL is optional, it is highly recommended so people will know where to find new sources should they take a liking to upgrading the source and do a recompilation. This will also allow automated tools like Updates Tracker to automatically check for new versions.

When there is more than one source file, use other lines with Source1: ..., then Source2: ..., etc.

Patch0:         gif2png-2.0.1-bugfix.patch

Two reasons for this optional tag:

1. You fixed a bug on the program sources. So you generated a patch file to be applied to the sources before compilation.
2. You've been warned of the existence of a patch for your software's version somewhere on the net and downloaded it, or you cherry-picked it.

Note:

The patch file must be placed into the SOURCES directory; as for the sources, there can be several patches, they will be named Patch1, Patch2, etc.

The patches you list under Patch0:-like sections will not be applied automatically; see below how to apply them.

URL:            http://www.tuxedo.org/~esr/gif2png/

This line (optional but highly recommended) points to the home page of the program.

Group:          Multimedia

This is to tell rpm in which part of the general package tree to place this package. This feature is used with package managers front-ends such as rpmdrake.

The complete group structure to use, which may be different from the one ROSA uses, can be found on the page Packaging Groups. It is mandatory to follow it, otherwise your package will mess with the other ones, in the package tree selection of the system installer, or in package manager front-ends.

License:        MIT-like

This tag (superceding Copyright) defines the license chosen by the copyright holder that will apply to the software being packed. In most cases it is GPL. See Licensing Policy for complete valid licenses list

Requires:       python

This line was added because one of the programs included in the package is a python script. It then needs python to be executed. You can put optional minimum (or equal) version, for example: Requires: python >= 2.7.

If your package contains executable files linked against C or C++ libraries, such "requires" are generated by rpmbuild automatically.

%description
Tools for converting GIFs to PNGs. The program gif2png converts GIF files
to PNG files. The Python script web2png converts an entire web tree, also
patching HTML pages to keep IMG SRC references correct.

This is a quite special tag inside the header of the spec file, because it is a complete text made up of various lines and paragraphs, if needed. It contains the full description of the software being installed in order to help the user to decide whether he wants to install the package or not.

You may be asking yourself at this point: "And what about translations?" Actually, to improve readability of spec files, translations of summary and description tags are stored in a special file called <package>.po.

This method implies that all text inside a .spec file is written in English. With the exception, however, of packages intended for a particular language (ispell-de for example). In that case it is recommended to have the text in two languages: English and in the language of that particular package. You will use special tags for this: Summary(de): .. and %description -l de.

Prep section

%prep  
%setup -q -a 1
%patch0 -p1

Into this section, is written the first script being executed by rpm. Its role is to:

• create the top-level build directory (into BUILD),
• unpack the original sources into the build directory,
• apply optional patches to the sources.

It may then be followed by any command the packager wants in order to get the sources into a ready-to-build state.

%setup -q -a 1 

This is a buit-in script macro which

• cd's into the build tree,
• extract the source(s) (quietly, -q)
• change ownership and permissions of source files.

By default it extracts the first source; you have to use parameters for any other sources, in our example -a 1 tells that we also want the extraction from source number 1.

There are other interesting switches which can be used with %setup macro:

• -c name - switch -c wrote that upper directory is created first; then cd into this directory and then unpack Source0. This is useful if an archive is extracted without a parent directory.
• -D - does not delete the directory before unpacking. This is only useful if you have more than one setup macro. It should only be used in setup macros after the first one (but never in the first one).
• -T - this option overrides the default action of untarring the Source and requires a -b 0 or -a 0 to get the main source file untarred. You need this when there are secondary sources.
• -n name - if the name of the rpm is something other than what the Source unpacks to, use this switch. For example: if the rpm name is program-version-revision and the Source unpacks to the program-version-date, the rpm build process will not be able to cd into the directory program-version, so use -n program-version-date, so rpm will know the new directory in which to continue.

%patch0 -p1

The macro responsible for applying the patch to the sources; its parameter "-p<num>" is passed to the patch program. Imagine if you had another patch declared Patch1: .. in the header section, you would add another line: %patch1 -p1. Adding a -b .your_suffix would also be nice, as you can let others know what your patch does, or who did the patch. For example, if Fred did the patch, then he could do %patch -p1 -b .fred, or if Barney did the patch then it could be %patch -p1 -b .barney

Build section

%build 

This section will contain the script responsible for the actual build of the software.

It consists of the commands being issued when building a package from an untarred source tree.

%configure

This is the line used for configuring autoconf'ed sources. %configure issues a ./configure with many add-ons such as

export CFLAGS="$RPM_OPT_FLAGS"

before the configure, and options such as

i586-mandrake-linux --prefix=/usr --datadir=/usr/share

etc.

Sometimes these arguments are not supported by the configure script. In such case, you have to discover the reason, and issue the ./configure with appropriate parameters. Give the target platform to the configure call, if supported, with %{targetplatform} ; of course, specification of an architecture must be avoided in specfiles; on ix86, this will expand to i586-mandrake-linux, as shown in the example above.

Note:

You will need the libtool package to use %configure with packages building shared libraries.

When building, and when testing your package, you should verify that the target host is actually an i586 ; in particular, when compiling on a higher processor type, the default behaviour of the configure script is to discover your processor, and optimize for it. The target of the %configure macro is to avoid this behaviour.

%make

This is a simple macro that basically performs a make with the appropriate multiprocessor parameter -j<num> for your system.

For sources using xmkmf, you should replace the next make with:

make CDEBUGFLAGS="$RPM_OPT_FLAGS" CXXDEBUGFLAGS="$RPM_OPT_FLAGS" 

For other packages, in many (but not all) cases a simple make will do.

Install section

%install 

This section will contain the script responsible for actually installing the package in the simulation installation dir.: %{buildroot}.

It will contain all commands necessary to make the software ready to run on the user's system.

%makeinstall

This line finally installs the software into the simulation installation directory for autoconf'ed sources. This macro will expand to "make install" with many options in order to install in the simulation directory %{buildroot}, e.g.

prefix=%{buildroot}/%{_prefix} bindir=%{buildroot}/%{_bindir}

etc.

In some cases the configure script will be partially broken and you may need to lurk in the Makefiles to guess the additional parameters to have it install correctly. One of the most common ones is that sometimes you have to use make DESTDIR=%{buildroot} install.

To save both disk space and download time, ROSA uses lzma to compress man- and info-pages. However, this aspect is handled directly by the ROSA custom rpm program.

To install additional files with proper permissions, the install command comes handy.

In this section, you must also remove from the %buildroot the files you're not going to install. Here's an excerpt from a spec file:

 # Don't install READMEs twice
 rm -f %{buildroot}%{perl_vendorlib}/urpm/README*

After the %build section has completed its execution, only the files that will be installed to the system, should remain. All other files MUST be removed.

Now the files to be ready to be packed.

Clean section

DO NOT add %clean into your ROSA packages. Use rpmbuild --clean ... option instead.

Files section

%files 

This section consists of a list of files that will be installed onto a system when the user installs the package. These files are picked from our simulation directory tree where the package was "installed" during the build. Each file from that install directory should be listed exactly once under the %files section.

The file list must be written by hand in the spec file. It may be constructed by listing all files created by rpm in the build directory tree. In order to do that, issue a rpmbuild -bi mypackage.spec in order to stop the building process just after the simulated install. Then, look in the simulated installation directory, ~/rpmbuild/BUILDROOT/gif2png in our case, to see which files you want to put in your package (most of the time, you will put them all).

Note that you should never use find to build a list of files to include but explicitly list all files (this will show up bugs in new versions). The only exceptions is for locales for which you should use %find_lang %{name} in the %install section and replace %files by %files -f %{name}.lang (see Appendix B).

Note:

About directory structure : The files being installed by your package "should" follow the FHS recommendations at http://www.pathname.com/fhs

%defattr(0755,root,root)

This tag defines the attributes to be applied to each file being copied to the user's system. The four arguments given mean:

• -: all the attributes for regular files are remaining unchanged,
• root: the owner of the file is root,
• root: the group of the file is root,
• 0755: the attributes applied to all directories owned by this package are 0755 ( rwxr-xr-x ).

%doc README NEWS COPYING AUTHORS

The special tag %doc designates files being part of the documentation of the package. The said files will be placed in /usr/share/doc/gif2png-2.0.1/. This directory will be also automatically created. Files specified by %doc are relative to your untarred source (not install!) directory in BUILD.

%{_mandir}/man1/gif2png.1*
%{_mandir}/man1/web2png.1*

It is recommended to list here also each man or info file separately.

Also you may wonder why gif2png.1* was used instead of gif2png.1.lzma. This is done to decouple manpage archiving type from the file name in the spec, and to preserve compatibility with other systems that could use gzip compression instead. If you find such references to any specific kind of compression in spec files, change them to a wildcard. Most of the time you can even use %{_mandir}/man1/*, this will take all the files it can find.

%{_bindir}/gif2png
%{_bindir}/web2png

As you can see, you have macros for every kind of path you need. Here are the most useful ones (look at the file /usr/lib/rpm/macros and /usr/lib/rpm/macros.d and /etc/rpm/macros.d directories) : %{_prefix} , %{_bindir} , %{_sbindir} , %{_datadir} , %{_libdir} , %{_sysconfdir} , %{_mandir} , %{_infodir} . For games, use %{_gamesbindir} and %{_gamesdatadir} .

There are also subsystem-specific macros useful when packaging application from a certain software stack. Such macros available in ROSA are described in appropriate packaging policies on this wiki - for example, macros useful when packaging KDE applications can be found at the KDE4 Packaging Policy page.

Changelog section

NOTE: This is just a general information on changelog section. You MUST NOT add it to your spec file, as it will be automatically generated from commit messages in the revision control system.

Changelogs in general

%changelog 

This section is to keep track of different changes made to the package. Every new release build of the package must correspond to a paragraph in this section as well as an increase in the release number (if not in the version number). The structure of these paragraphs have to be respected as following:

* Mon Nov 02 1999 Camille Begnis <camille@mandrakesoft.com> 2.0.1-1

• The first line of the paragraph begins with * and, in order, each one separated by a space:
• three letters for the day of the week,
• three letters for the month,
• two figures for the day of the month,
• four figures for the year,
• First name of the packager,
• Last name of the packager,
• e-mail of the packager between <>.
• version and release of current modifs.

- Upgraded to 2.0.1

Then follows one line per modification applied to the package beginning with a -.

These are examples:

- spec file stolen from korganizer. 
- last snapshot before release 
- ROSA adaptations. 
- Fix bug in /etc/zsh use USERNAME instead of USER. 
- Remove petit bouchon which annoys other players. 
- Improve /etc/z* to source the /etc/profile.d/ files. 
- fix typo in examples directory name 
- fixed QT libs version requirements 
- add patch to hab>don't modify the original source distribution at allndle Earl Grey tea 

Note that by default only entries younger than 1 year will be preserved in the built package. To change this behaviour modify the value of %_changelog_truncate

Commit logs

The information in this section is automatically generated from SVN commit logs. Each line of the log becomes a line that begins with a dash (it's added automatically), and describes the matter of the change brought by this commit (see examples above). The commits will be automatically grouped by your name and e-mail address associated with your SVN account entry.

To make a line not appear in the log, add "SILENT: " at the beginning of it. Blank linkes are also ignored.

The build

Our spec file is finally complete. Take a long breath, sit down and type rpmbuild -ba mypackage.spec

You may also add the --clean option which cleans the BUILD directory after package building completes. This is useful if you have little disk space.

There are then two possibilities for the last line of your process:

• 0.01% probabilities: + exit 0
• 99.99% probabilities for other cases.

You are in the second case? Congratulations you passed the test, you are not an alien.

Good luck, so long, have a look to rpm building options (man rpmbuild ) to debug your work, look at other persons' specfiles, etc..

There is a very clean way to build packages: use rpmbuild -bs --rmspec --rmsource (in order to remove anything from the original build) and then do a rpmbuild --rebuild.

Optimize the build

When you launch the command to build your package, you certainly noticed message like "foo-devel is necessary for foo2".

This means that it needs informations from other packages used for development (usually files named foo.h). If you don't have these, compilation will stop or features will be missing in your package.

The place where all official packages are built (build system at ROSA) have a lot of these devel packages preinstalled. If one is not declared in your SPEC file and is mandatory, the package will be built anyway on the cluster. It will work, but the lack of this information prevents building on machines missing the devel package, making debugging/upgrading more difficult.

Look at the website of the package, it will give information about needed components (but not always)

An idea to hunt down these "missing BuildRequires" is to start packaging with only basics devel packages installed :

• glibc-devel
• libncurses5-devel
• libstdc++6-devel

After that, only install the package's relative devel package that is asked for by the rpm build command.

When launching the build, watch for "checking for.." messages.

If you see something like "checking for foo... foo.h not found", this means that a header needed has not been found on your system. Search for the devel package containing "foo.h", but be careful: you can find more than one package containing what you seek. So choose the more obvious package. Don't choose a network related package when you build a sound application (for example).

Then install it on your system, and don't forget to add its name in the BuildRequires section of your SPEC file.

Missing headers can also be found during compilation itself. If it stops, check for others missing "foo.h" and apply the same recipe.

If you want to install all BuildRequires of a ready rpm package (for testing purposes, for instance), issue urpmi --buildrequires package.rpm.

Testing an RPM

Basic tests

The first steps to perform are:

• Are the rpms created in the corresponding directories with the correct names? (into ~/rpmbuild/SRPMS/ and ~/rpmbuild/RPMS/i586/)
• Is the information obtained from issuing the command rpm -qlivp --changelog mypackage.(src.)rpm correct?

Linting the package

Next, you MUST use Rpmlint which will test various things on the package. Before running rpmlint, make sure you have rpmlint-mandriva-policy package installed which contains rpmlint configuration for ROSA. If rpmlint reports errors, the package will be rejected from the distribution, and if there are too many warnings of certain types, it will not pass either. But even if the warnings do not make your package fail, you should pay attention to them, and try to fix as many as possible.

To run the check, type rpmlint mypackage.<archtype>.rpm and a report on the specified package will be issued. For more precision, use the -i switch. You should check the rpm and the src.rpm. More information on the errors, and on how to fix them can be found on Problems and issues with packaging.

Install test

On any machine - but preferably on a different one than that used for compilation - do an upgrade or an install, and then check:

• Are all the expected files created at their expected places with the expected rights and owners?
• Are all the installation modifications (if any) effective?
• Are all binaries executable, and is the documentation accessible to the intended users?

Perfectionists should try various different installs and uninstalls to check whether all expected features are implemented correctly, for example without required packages.

If all of these tests are passed successfully, you are almost done, and should go to the last step of the process: submitting packages.

Something's going wrong?

Well, it appears that you have been reading this HowTo, which is a good beginning. If you couldn't find your answer right here, you should try in the given order:

1. The official RPM-HOWTO (installed along with the rpm program on your system);
2. The book from Red Hat "Maximum RPM", which is available at http://www.redhat.com/docs/books/max-rpm/max-rpm-html/;
3. Take a look at how spec files for the similar packages are written;
4. Post a question in the development mailing list you subscribed to when you started to participate in ROSA project.

If you feel that the information you found may be useful to others, in the scope of that document, feel free to submit your proposal to the maintainer of that document.

Of Pre- and Post-installation scripts

Basics

The RPM package is in fact a bit more than a simple archive containing files to be expanded in specific directories of the host client system.

The system offers to the programmer a great feature: pre- and post-installation scripts. They allow the packager to write a piece of code which will be executed on the client machine while installing or erasing the package.

These scripts are made of any sh valid commands. There are four of them:

There are certain caveats about these scripts which you should take into account. Number one, each must fit inside a 8192 buffer, and number two, they should be non-interactive. Anything which requires manual input from the user is wrong, as this will break non-interactive RPM installation procedures.

• %pre - This script is executed just before the package is installed on the system.
• %post - This script is executed just after the package is installed on the system.
• %preun - This script is executed just before the package is uninstalled from the system.
• %postun - This script is executed just after the package is uninstalled on the system.

The scope of such scripts may be very large, and they have to be designed with much care not to harm the host system. One has to remember that these scripts will be run as root... They correspond to the tasks a system administrator would have to accomplish when installing a new program on a system. For example:

• Add a cron job running the program at fixed intervals
• Run chkconfig to run the daemon at boot time
• ...

Dealing with upgrades

The fact that a package may be upgraded, and not simply installed or removed, makes the thing a little bit tougher... The problem is that the %postun script of the update is run after the %post of the old version. So all %post stuff is lost...

It is often useful to ensure that an action occurs only during an install and not during an upgrade. Likewise for an action that only occurs during an uninstall and not during an upgrade. RPM's mechanism for dealing with this is the argument that is passed to the %pre, %preun, %post and %postun scripts by default.

This argument indicates the number of instances of this RPM that will be installed on the machine after the current script has completed. For example, if a new package is installed then 1 will be passed to %pre and 1 passed to %post. When the package is upgraded, 2 will be passed to %pre of the new RPM, 2 will be passed to %post of the new RPM, 1 will be passed to %preun of the old RPM and 1 will be passed to %postun of the old package.

Table A-1. Value of the parameter passed to pre and post scripts

Parameter \ Script	%pre	%post	%preun	%postun
for a first time install	1	1	N/C	N/C
for an upgrade	2	2	1	1
for a removal	N/C	N/C	0	0

This will allow the programmer to distinguish different attitudes of his scripts depending on the operation: install or upgrade.

• For install scripts ( %post, %pre ) check if $1 is equal to "1" then it is a first time install, not an update.
• For uninstall scripts ( %postun, %preun ) check if $1 is equal to "0", if yes then it is a full removal; if not it is either an upgrade or an install --force of the same package.

To test this argument, the following 'if' statement is used:

%postun
if [ $1 = 0 ]; then
    // Do stuff specific to uninstalls
fi
if [ $1 = 1 ]; then
    // Do stuff specific to upgrades
fi

A single test is therefore enough, to call the right action at the right time.

Filetriggers

In ROSA, rpm filetriggers are used to remove the burden of the repetitive tasks like "%post -p /sbin/ldconfig" or "%update_menus".

More macros

When building RPM's for ROSA, you have more macros to simplify the specfile.

• Handling the info pages. An example is the best teacher:

%post
%__install_info %{name}.info

%preun
%__install_info %{name}.info

• The menu system. In ROSA, XDG Menu system is used.

%post
%{update_menus}

%postun
%{clean_menus}

• Handling internationalization cleanly. The best way is not to enter by hand the .mo files that usually are in /usr/share/locale/.., but to use a special macro in the %install section, which will fill up a special file for that:

%find_lang %{name}

Then you will use the file in the file list:

%files -f %{name}.lang

• Build macros. The build macros %configure and %makeinstall are quite big at the present time. They specify the prefix, but also every common directory (such as bindir, datadir, and so on); in that respect, they work flawlessly with small and medium sized packages, but always need some attention for the rest. The macro %make performs the make command with appropriate -j<num> option to scale well with multiprocessors. If you need to call manually the ./configure script, remember to NEVER hardcode the architecture; the macro %{targetplatform} is made for that purpose (or even %{targetcpu} , if necessary).
• Building servers. To build safer servers, we use a specific macro, %serverbuild, to be used before the actual build occurs. This allows for safer optimization flags. The %build section will often look like:

%build
%serverbuild
%configure
%make

With 2012 ROSA release we have added a hardened macro which is called %serverbuild_hardened. This macro exports -fPIE to the CFLAGS and -Wl,-z,now -pie to the LDFLAGS. This macro is recomended to provide better security by using full RELRO and PIE.

%build
%serverbuild_hardened
%configure
%make

• Initscript macros. When you install a package which will provide it's own initscript (the files in the directory /etc/init.d ), it needs to be added through a call which looks like chkconfig --add .., but not in the case of upgrades, and it needs to be restarted if already running; when uninstalling, similar (opposite) things must be done; we have specific macros to do that without a glitch:

%post
%_post_service <initscript-name>

%preun
%_preun_service <initscript-name>

• Handling ghostfiles. Mostly with games, sometimes packages use a varying file which may even not be present. That's where ghostfiles are useful. Here's an example:

%install

(...)

mkdir -p %{buildroot}/var/lib/games
touch %{buildroot}/var/lib/games/methanescores

%post
%create_ghostfile /var/lib/games/powermanga.hi root games 664

(...)

%files
%attr(664, root, games) %ghost /var/lib/games/powermanga.hi

The %create_ghostfile macro will expand to:

if [ ! -f /var/lib/games/powermanga.hi ]; then 
  touch /var/lib/games/powermanga.hi
  chown root.games /var/lib/games/powermanga.hi
  chmod 664 /var/lib/games/powermanga.hi
fi 

• .desktop / MIME type mapping association : XDG menu system allows setting association between an application and a MIME type in .desktop file. The update-desktop-database utility should be run if such .desktop file is installed / uninstalled on the system, using macros as shown in the following example:

%post
%update_desktop_database

%postun
%clean_desktop_database

• Freedesktop.org MIME type database : the database used to list all available MIME types, with magic and/or extension file pattern should be updated using macros as shown in the following example :

%post
%update_mime_database

%postun
%clean_mime_database

• Icon cache : all packages shipping icons stored in /usr/share/icons/hicolor (or other freedesktop icon theme directories, such as /usr/share/icons/gnome or /usr/share/icons/crystalsvg ) must update icon cache, as stated below (icons stored in /usr/share/icons, /usr/share/icons/mini or /usr/share/icons/large are not concerned by this requirement) :

...
%file
...
%{_iconsdir}/hicolor/*
%{_iconsdir}/crystalsvg/*
....

%post
%update_icon_cache hicolor
%update_icon_cache crystalsvg

%postun
%update_icon_cache hicolor
%update_icon_cache crystalsvg

• GConf schemas registration : GNOME GConf schemas must be installed / uninstalled using the following macros:

...
# each schema key here corresponds to a file named /etc/gconf/schemas/<key>.schemas
%define schemas apps_gnome_settings_daemon_default_editordesktop_gnome_font_rendering desktop_gnome_peripherals_keyboard_xkb fontilus themus

%post
%post_install_gconf_schemas %{schemas}

%preun
%preun_uninstall_gconf_schemas %{schemas}

• Scrollkeeper database update: scrollkeeper database (used to index docbook documentation) should be updated when installing an .omf file like this:

...
%post
%update_scrollkeeper

%postun
%clean_scrollkeeper

Interaction with urpmi and rpmdrake

Sometimes it's necessary to warn the user about some particular care that should be taken when upgrading or installing a specific version of a package. rpmdrake-2.1.3 and above supports this: it searches in rpms for text files named README.install.urpmi, README.update.urpmi or README.urpmi, and displays them.

README.install.urpmi is displayed only for installed packages; README.update.urpmi only for upgraded packages; README.urpmi is displayed in both cases.

Alternative : checkinstall

A very easy way to build RPMs for personal use is to install the checkinstall package; compile from source as usual (./configure && make && sudo make install), but just replace the make install step by checkinstall. This automates building an RPM, and is very simple to use. The advantage is that you don't ever have to bypass the package manager when compiling from source, and that you can remove your package completely by a standard rpm uninstallation procedure. (However, it's probably A Good Idea to build RPMs "properly" as described above, if you intend to distribute them to others.)

Related links

• Packaging Groups
• ROSA Licensing policy

External links

• IBM article on rpm building
• A redhat magazine article on rpm building
• Pdf tutorial on rpm building made by GuruLabs
• Red Hat RPM Guide, hosted on fedoraproject.org

---

Note:

This HowTo is based on the Mandriva RPM Packaging Tutorial.