Aus Mandriva Community Wiki

Inhaltsverzeichnis 1 Foreword 2 Install the software 2.1 The basics 2.2 Building for Mandriva Linux 3 Preliminary tasks 3.1 Install required package 3.2 Create required folders 3.3 Create .rpmmacros file 4 Building an RPM 4.1 From an existing source RPM 4.2 From raw sources 4.2.1 Preliminary checks 4.3 Inside the spec file 4.3.1 Header section 4.3.2 Prep section 4.3.3 Build section 4.3.4 Install section 4.3.5 Files section 4.3.6 Changelog section 4.4 The build 4.5 Optimize the build 5 Testing an RPM 5.1 Basic tests 5.2 Linting the package 5.3 Install test 6 Something's going wrong? 6.1 For general RPM matters: 6.2 For specific Mandriva RPM matters: 7 Of Pre- and Post-installation scripts 7.1 Basics 7.2 Dealing with upgrades 8 More macros 9 Interaction with urpmi and rpmdrake 10 Mandriva Linux Groups 11 Mandriva Linux Valid Licenses 12 Some links 13 Other interesting sources of Mandriva RPM information

This HOWTO is aimed at helping people who want to produce software packages which should integrate well in the Mandriva Linux 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 Mandriva developers, but also to external people. An annex covering the more advanced topic is available on Development/Howto/RPM_Advanced

The Mandriva Linux distribution of GNU/Linux is produced and published by Mandriva, Inc., with the help of various contributors, testers, translators. Some of them are listed on Distro Credits

[bearbeiten] Foreword

It is assumed in this document that the reader is "linux-ready". He 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 obtain an rpm package that can integrate well in the Mandriva Linux distribution of GNU/Linux, from either a previous source rpm or from a tar source.

If you haven't done it yet, you should read the [Development/Howto/Participate| Cooker howto particpate], which explains the development process of Mandriva Linux.

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 verifying dependencies,
• while installing a package, perform actions in order to make the program installed ready to use,
• restore accidentally erased files belonging in a package,
• tell if a package is already installed,
• find to which package belongs a particular file,
• verify the current installation as to the fulfilment of dependency requirements of installed packages,
• ....

From the programmer's point of view, the program rpm 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 tell 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 put the files at their correct location, and the actions to perform in order to make the program operable.

[bearbeiten] Install the software

[bearbeiten] The basics

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

You can get the vanilla rpm distribution from Red Hat here: [1]

The binary rpm you will build for Mandriva Linux may not work across the distributions, although Mandriva does everything possible to stay compatible with Red Hat.

[bearbeiten] Building for Mandriva Linux

Building packages for Cooker (i.e. the development version of Mandriva Linux) is always subject to small patches and enhancements on the rpm program in use. Open any Mandriva Cooker mirror and get:

• The package rpm which is our patched version of Red Hat's.
• The package rpm-build which holds scripts used to build packages.
• The package spec-helper which is a tool to minimalize the specfiles by doing automatic things such as stripping the binaries and compressing the man pages.
• The package libtool which is used by some configure scripts to build shared libraries.
• The package rpmlint which is used to check the validity of the generated src.rpm.

[bearbeiten] Preliminary tasks

[bearbeiten] Install required package

In order to be able to build RPMs, you must have the rpm-build package installed. For instructions on installing packages, see Installieren und entfernen von Software.

[bearbeiten] 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 ~/rpm/{BUILD,RPMS/$ARCH,RPMS/noarch,SOURCES,SRPMS,SPECS,tmp} . Replace $ARCH with the architecture(s) you plan to build packages for. Basically this is i586, but may also be x86_64/sparc/alpha/ppc.

NOTE! 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.

Make sure that the tree is of the form:

• ~/rpm/BUILD: The directory where the sources are built.
• ~/rpm/RPMS: Contains the directories, one for each architecture, that will receive the binary packages after.
• ~/rpm/RPMS/i586: The directory where rpm packages for i586 processors will be stored.
• ~/rpm/RPMS/x86_64: The directory where rpm packages for AMD64 processors will be stored.
• ~/rpm/RPMS/noarch: Idem for noarch (processor-independant) packages.
• ~/rpm/SOURCES: The source files (mypackage.tar.bz2 for example).
• ~/rpm/SPECS: The spec files we will have to construct.
• ~/rpm/SRPMS: The source rpm after building.
• ~/rpm/tmp: For temporary stuff that rpm will create when building your packages.

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

[bearbeiten] Create .rpmmacros file

In order to build packages for Mandriva Linux, you will need to add the .rpmmacros configuration file into your home directory:

%_topdir                %(echo $HOME)/rpm
%_tmppath               %(echo $HOME)/rpm/tmp

# If you want your packages to be GPG signed automatically, add these three lines
# replacing 'Mandrivalinux' with your GPG name. You may also use rpm --resign
# to sign the packages later.
%_signature             gpg
%_gpg_name              Mandrivalinux
%_gpg_path              ~/.gnupg

# Add your name and e-mail into the %packager field below. You may also want to
# also replace vendor with yourself.
%packager               John Doe <[email protected]>
%distribution           Mandriva Linux
%vendor                 Mandriva

# If you want your packages to have your own distsuffix instead of mdv, add it
# here like this
%distsuffix             foo

Warning, don't set Vorlage:Macro, as one is already provided for you in the system-wide /usr/lib/rpm/mandriva/rpmrc.

Your rpm program is then setup to build packages. All of the above can be done in one shot (for i586) by running this RPM Setup Script.

[bearbeiten] Building an RPM

[bearbeiten] From an existing source RPM

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:

• 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 Mandriva Linux, just issue rpm -ivh mypackage.src.rpm; it will install all source files into your RPM directory. You can also setup urpmi to download the source.

For example:

[camille@kenobi ~/rpm]$ rpm -i /cooker/SRPMS/ktron-1.0.1-2mdk.src.rpm 
[camille@kenobi ~/rpm]$ 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 ~/rpm]$ cd ~/rpm/SPECS
[camille@kenobi ~/rpm]$ rpmbuild -ba ktron.spec
[camille@kenobi ~/rpm]$ ls -l ~/rpm/RPMS/i586/ktron-1.0.1-2mdk.i586.rpm
[camille@kenobi ~/rpm]$ ls -l ~/rpm/SRPMS/ktron-1.0.1-2mdk.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 ~/rpm/RPMS/i586 and ~/rpm/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 control_d). But in order to build an rpm, and to expand an src.rpm, you never need to be root.

The log of the build might be very long and can be stored for later browsing. I am using emacs or xemacs and use a second window with a shell (Alt-x shell) and save the buffer as ktron.LOG, for example, when finished.

In the ~/rpm/BUILD sub-directories you will usually access to the patched sources (if one or more patches were given in ~/rpm/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.

Now all we need to do, in this case of improving ktron, is to modify the spec file and then rebuild the package.

It is important to note that each package maintained at Mandriva is stored on a CVS system. This allows every state of a package to be recorded by the system, so that the developer may consult the archive to check previous modifications and if necessary revert to an older release version.

Each spec file is stored on a module called SPECS/<package> or contrib-SPECS/<package>. You can access it on http://cvs.mandriva.com/

For details on how to access the CVS system, consult the Mandriva Linux CVS pages

[bearbeiten] From raw sources

For example, if you find an interesting program at Freshmeat or Sourceforge that warns you when the tea is ready, you may want to make it available to all Mandriva Linux English tea drinkers. Probably the best way to do that is to set up an RPM for it that conforms to Mandriva's standards.

Download the tarball and place it in the SOURCES directory.

[bearbeiten] 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 open-sourced 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 Mandriva Licenses

bz2 Compression

To save space in the package, it is recommended to compress tarballs into bzip2 format. Most of the time, the sources will be released as a .tar.gz archive. First of all, convert it to a .tar.bz2 (which should be smaller), by using bzme provided by Mandriva's bzip2 package. 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 Subversion diffs (and Subversion also already uses some form of compression). Note: For high-risk security-critical packages we recommend that you don't modify the original source distribution, as it 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.

[bearbeiten] 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 and uninstall 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 Mandriva 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.

You can get a list of specs and patches here.

%define name    gif2png 
%define version 2.0.1 
%define release %mkrel 1 

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

Group:          Applications/Multimedia 
BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-buildroot 
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
rm -rf $RPM_BUILD_ROOT
%makeinstall

%clean 
rm -rf $RPM_BUILD_ROOT 

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

%changelog 
* Mon Nov 02 1999 Camille Begnis <[email protected]> 2.0.1-1mdk
- Upgraded to 2.0.1 

* Mon Oct 25 1999 Camille Begnis <[email protected]> 2.0.0-1mdk
- 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, clean)
• a built-in shell script macro (setup, patch)
• a directive used by a special section (defattr, doc, ...)

[bearbeiten] Header section

%define name    gif2png
%define version 2.0.1
%define release %mkrel 1

These three lines define constants that may be used in many following sections of the spec file, named Vorlage:Macro, Vorlage:Macro and Vorlage:Macro. Vorlage:Macro is a Mandriva macro that should be used to add mdv after the release number, see Distro Specific Release Tag.

Then, we can fill up some information fields for rpm :

Name:           %{name}

The name of the package as used in the package's name and in the package database on the user's machine.

Note that the "Vorlage:Macro" is a reference to the previous define.

Version:        %{version}
Release:        %{release}

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.arch.rpm
• A source package is named as: name-version-release.src.rpm (i.e. gif2png-2.0.1-1mdk.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 followed by mdv (stands for "Mandriva"; this is absolutely mandatory) 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.

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

This line is a one-liner of the package description.

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 allow tools like rpmbuildupdate to automatically rebuild new versions (see rpmbuildupdate for more info).

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

Patch0:         gif2png-2.0.1-bugfix.patch.bz2

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. Note that the patches are all bzipped, too. Even if a patch is small you might not benefit from bzip2 compression, but it has to be bzipped to be consistent.
2. You've been warned of the existence of a patch for your software's version somewhere on the net, and downloaded it.

Note that 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.

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 or kpackage.

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

BuildRoot:      %{_tmppath}/%{name}-%{version}-%{release}-buildroot

This line is very important and cannot be omitted. It tells rpm that to install the program, it will have to use a special root directory (a fake "/") on the compiling machine. There are two reasons for this:

1. When building an rpm, you don't have root access to the machine, so you cannot install the package in normal directories.
2. The installation into the working tree of a working machine will probably mix up the package's files with other files, and most important, it may be dangerous if the package is already installed. A lot of people like to use /var/tmp or /tmp for the buildroot. This is not necessarily a problem if you are the only user of your machine, but if you have multiple users on your machine, and they compile the same package at the same time rpm will barf. Therefore it is important that you define Vorlage:Macro, and within your own home directory!

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 Mandriva Licenses 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 >= 1.5.1

%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.

These files are stored on the poSPECS module in Cooker cvs. When a new package is created, the base po file is automatically created in this module for future translations.

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 Vorlage:Macro.

[bearbeiten] 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 when some packages are unbecomed (meaning?; DickGevers) tar.bz-ipped without 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: Vorlage:Macro. 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 Vorlage:Macro, or if Barney did the patch then it could be Vorlage:Macro

[bearbeiten] 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. Vorlage:Macro 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 Vorlage:Macro; 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 that you will need the libtool package to use Vorlage:Macro 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 Vorlage:Macro macro is to avoid this behaviour.

%make

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

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.

[bearbeiten] Install section

%install 

This section will contain the script responsible for actually installing the package in the simulation installation dir.: $RPM_BUILD_ROOT.

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

rm -rf $RPM_BUILD_ROOT

This is the first of the commands being executed in the Vorlage:Macro section; it cleans up a possible previous install directory.

%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 $RPM_BUILD_ROOT, e.g.

prefix=$RPM_BUILD_ROOT%{_prefix} bindir=$RPM_BUILD_ROOT%{_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=$RPM_BUILD_ROOT install.

To save both disk space and download time, Mandriva uses bzip2 to compress man- and info-pages. However, this aspect is handled directly by the Mandriva custom rpm program. At this point of the spec file, older packages contained some lines like find $RPM_BUILD_ROOT%{_mandir} -type f -exec bzip2 -9f {} \;

It is the same for old strip $RPM_BUILD_ROOT%{_bindir}/* || : lines: they have to be removed

All this stuff is to prepare the files to be ready to be packed.

%clean

This section is meant to clean the build directory tree, $RPM_BUILD_ROOT.

rm -rf $RPM_BUILD_ROOT

This is where the job is done.

[bearbeiten] Files section

%files 

This section consists of a list of files that will be picked from our simulation directory tree to be packed into the package. See the fine manual for the different options not being used in that simple example.

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 rpm -bi mypackage.spec in order to stop the building process just after the simulated install. Then, look in the simulated installation directory, ~/rpm/tmp/gif2png-buildroot 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 Vorlage:Macro in the Vorlage:Macro section and replace Vorlage:Macro by Vorlage:Macro (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 Vorlage:Macro 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 Vorlage:Macro are relative to your untarred source 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.bz2. This is done to preserve compatibility with other systems that could use gzip compression instead of Mandriva bzip. If you find such referencies to bz2 compression in spec files, change them to a wildcard. Most of the time you can even use Vorlage:Macro, 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 for everything) : Vorlage:Macro, Vorlage:Macro, Vorlage:Macro, Vorlage:Macro, Vorlage:Macro, Vorlage:Macro, Vorlage:Macro, Vorlage:Macro. For games, use Vorlage:Macro and Vorlage:Macro.

[bearbeiten] Changelog section

%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 <[email protected]> 2.0.1-1mdk 

• 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 
- Mandriva 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 handle 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 Vorlage:Macro

[bearbeiten] The build

Our spec file is finally complete. Take a long breath, sit down and type rpm -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 rpm ) to debug your work, look at other persons' specfiles, etc..

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

[bearbeiten] 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 cluster at Mandriva) 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.

[bearbeiten] Testing an RPM

You should also check the Bugzilla pages for information about this subject.

[bearbeiten] Basic tests

The first steps to perform are:

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

[bearbeiten] Linting the package

Next, you have to use rpmlint, which will test various things on the package. 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 can be found on Packaging Problems

[bearbeiten] 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.

[bearbeiten] 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:

[bearbeiten] For general RPM matters:

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. Post a question in the mailing list rpm-list you subscribed to a long time ago at the beginning of reading these howto pages.

[bearbeiten] For specific Mandriva RPM matters:

Drop a line to Mandriva's Quality Assurance, <[email protected]>.

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.

[bearbeiten] Of Pre- and Post-installation scripts

[bearbeiten] 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.

• Vorlage:Macro - This script is executed just before the package is installed on the system.
• Vorlage:Macro - This script is executed just after the package is installed on the system.
• Vorlage:Macro - This script is executed just before the package is uninstalled from the system.
• Vorlage:Macro - 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
• ...

[bearbeiten] 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 Vorlage:Macro script of the update is run after the Vorlage:Macro of the old version. So all Vorlage:Macro 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 Vorlage:Macro, Vorlage:Macro, Vorlage:Macro and Vorlage:Macro 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 0 will be passed to Vorlage:Macro and 1 passed to Vorlage:Macro. When the package is upgraded, 1 will be passed to Vorlage:Macro of the new RPM, 2 will be passed to Vorlage:Macro of the new RPM, 2 will be passed to Vorlage:Macro of the old RPM and 1 will be passed to Vorlage:Macro 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 ( Vorlage:Macro, Vorlage:Macro ) check if $1 is equal to "1" then it is a first time install, not an update.
• For uninstall scripts ( Vorlage:Macro, Vorlage:Macro ) 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.

[bearbeiten] More macros

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

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

%post
%''install''info %{name}.info

%preun
%''remove''install_info %{name}.info

• The menu system. Starting with MandrivaLinux2007.0, XDG Menu system is used, replacing the old Debian Menu system.

%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 Vorlage:Macro 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 Vorlage:Macro and Vorlage:Macro 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 Vorlage:Macro 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 Vorlage:Macro is made for that purpose (or even Vorlage:Macro, if necessary).
• Building servers. To build safer servers, we use a specific macro, Vorlage:Macro, to be used before the actual build occurs. This allows for safer optimization flags. The Vorlage:Macro section will often look like:

%build
%serverbuild
%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 $RPM_BUILD_ROOT/var/lib/games
touch $RPM_BUILD_ROOT/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 Vorlage:Macro 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
...
%{_icondir}/hicolor/*
%{_icondir}/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

[bearbeiten] 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-11mdk 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.

[bearbeiten] Mandriva Linux Groups

The list of groups can be found on RPM Groups

[bearbeiten] Mandriva Linux Valid Licenses

Please see on Mandriva Licenses

[bearbeiten] Some links

• Ark linux howto
• IBM article on rpm building
• A redhat magazine article on rpm building
• Pdf tutorial on rpm building made by GuruLabs
• Red Hat RPM Guide

[bearbeiten] Other interesting sources of Mandriva RPM information

• Cybercfo's "Mandrake a la Gentoo" tutorial