2.1. The basics

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

You can get the vanilla rpm distribution from RedHat here: ftp://ftp.rpm.org/pub/rpm/dist/

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

2.2. Building for Mandrake Linux

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

• The package rpm which is our patched version of RedHat'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.

3.1. 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 $ARPH with the architecture(s) you plan to build packages for, basically this can be i586 but also sparc/alpha/ppc.

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.

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

3.2. Add configuration files

In order to build packages for Mandrake Linux, you will need to add two configuration files in your home directory:

.rpmrc

buildarchtranslate: i386: i586
buildarchtranslate: i486: i586
buildarchtranslate: i586: i586
buildarchtranslate: i686: i586


.rpmmacros

%_topdir               YOUR_HOME_DIR/rpm
%_tmppath              YOUR_HOME_DIR/rpm/tmp

%_signature            gpg
%_gpg_name             Mandrake Linux
%_gpg_path             ~/.gnupg
%distribution          Mandrake Linux
%vendor                MandrakeSoft

which you will have to edit to fit your name and directory.

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

In the same way, don't set %packager, so that rebuilding other people's packages won't put yourself in the Packager: field of the RPM, possibly in a public release which would direct bug reports to you instead of maintainer.

Your rpm program is then setup to build packages.

3.3. Subscribe to mailing lists

Mandrake's lists (Consult Mailing list pages on Mandrake Linux pages):

• changelog

• security

• cooker

• doc

• RedHat's rpm-list: send a mail to rpm-list-request@redhat.com with subscribe in the subject line.

• Also there is a good rpm-help list you can subscribe to, rpmhelp@freezer-burn.org; consult the archive at http://www.freezer-burn.org/lists/rpmhelp.php3.

4.1. 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 which list is available at http://www.linux-mandrake.com/en/cookerdevel.php3 . Under the ftp hierarchy, you will find:

• /SRPMS/ for source rpms,

• /cooker/Mandrake/RPMS/ for binary rpms.

• /contrib/SRPMS/ for contrib source rpms,

• /contrib/RPMS/ for contrib binary rpms.

When you find the source rpm you want to modify for Mandrake Linux, just issue rpm -ivh mypackage.src.rpm; it'll install all source files into your RPM directory.

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 installed in our RPM tree the source file ktron-1.0.1.tar.bz2 and the spec file. It is all we need, in that case, to modify the spec file and then rebuild the package.

It is important to note that each package maintained at MandrakeSoft is stored on a cvs system. This allows every state of a package to being recorded by the system, so that the developer may consult the archive to check previous modifications and eventually come back to an older release version.

Each spec file is stored on a module called SPECS/<package> or contrib-SPECS/<package>.

For details on how to access cvs system, consult Mandrake Linux CVS pages

4.2. From raw sources

You found an interesting program at freshmeat or AppWatch or sourceforgewhich warns you when the tea is ready. And you want it available to all our Mandrake Linux's english tea drinkers.

Download it and place it in the SOURCES directory.

4.3. Preliminary checks

• License. Some fools out there still write programs with non-GPL licenses. Check it carefully and ask whether it may be incorporated into the distribution or not. Unless exceptions such as Netscape, we do not accept non open-sourced software. Also we cannot accept software which licenses don't allow us to freely distribute. Watch out for these programs.

• bz2 Compression. To save space in the package, turn every source and patches to 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 will be smaller), by using bzme provided by Mandrake's bzip2 package. For high-risk security-critical packages where only non tar.bz2 source is distributed, we recommend that you don't bzip2 it it will change the md5sum. For these kind of packages we recommend that you leave it in .tar.gz form so that when someone runs md5sum on it it will match the value of the md5sum as listed at the download location. One such example where this exemption may apply would be OpenSSH.

4.4. 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 messed up 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 such things like [ -f configure.in ] && autoconf is valid.

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

This is an example from the cooker repository. You may also consider our template spec file to begin your 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 1mdk 

Name: %{name} 
Summary: tools for converting websites from using GIFs to using PNGs 
Version: %{version} 
Release: %{release} 
Source: http://www.tuxedo.org/~esr/gif2png/%{name}-%{version}.tar.bz2 
Source1: %{name}-%{version}-mdk-addon.tar.bz2 
Patch: gif2png-2.0.1-bugfix.patch.bz2 
URL: http://www.tuxedo.org/~esr/gif2png/ 
Group: Applications/Multimedia 
BuildRoot: %{_tmppath}/%{name}-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 
rm -rf $RPM_BUILD_ROOT 
%setup -a 1 
%patch -p1 

%build 
%configure 
%make

%install 
%makeinstall

%clean 
rm -rf $RPM_BUILD_ROOT 

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

%changelog 
* Mon Nov 02 1999 Camille Begnis <camille@mandrakesoft.com> 2.0.1-1mdk
- Upgraded to 2.0.1 

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

Let's then analyze in details 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, ...)

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

Name: %{name}

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

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

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

Patch: gif2png-2.0.1-bugfix.patch.bz2

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

Group: Multimedia

BuildRoot: %{_tmppath}/%{name}-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  
rm -rf $RPM_BUILD_ROOT 
%setup -a 1 
%patch -p1 

rm -rf $RPM_BUILD_ROOT

%setup -a 1 

%patch -p1

---

4.4.3. 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 %{_target_platform}; 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 %configure with packages building shared libraries.

When building, and when testing your package, you should verify that the target host is actually a 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 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.

%install 

%makeinstall

%clean

rm -rf $RPM_BUILD_ROOT

---

4.4.5. 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 explicitely list all files (this'll show up bugs in new versions). The only exceptions is for locales for which you should use %find_lang %{name} in %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(-,root,root,0755)

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

• -: all the attributes for regular files are remained 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.

%doc README NEWS COPYING AUTHORS

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

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

Here also it is recommended to list each man or info file separately.

Also you may wonder why telling gif2png.1* and not gif2png.1.bz2. This is to preserve compatibility with other systems that could use gzip compression instead of Mandrake bzip. If you find such referencies to bz2 compression into 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 /usr/lib/rpm/macros for everything) : %{_prefix}, %{_bindir}, %{_sbindir}, %{_datadir}, %{_libdir}, %{_sysconfdir}, %{_mandir}, %{_infodir}. For games, use %{_gamesbindir} and %{_gamesdatadir}.

%changelog 

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

- Upgraded to 2.0.1

- spec file stolen from korganizer. 
- last snapshot before release 
- Mandrake adaptations. 
- Fix bug in /etc/zsh use USERNAME instead of USER. 
- Remove petit bouchon which annoy 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 

4.5. The build

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

You may also add the --clean option which cleans the BUILD directory after package building completes. Usefull 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? Congratulation 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 package: use rpm -bs --rmspec --rmsource (in order to remove anything from the original build) and then do a rpm --rebuild.

5.1. Basic tests

The first steps to perform are:

• Are the rpms created in the corresponding directories with the correct name? (into ~/rpm/SRPMS/ and ~/rpm/RPMS/i586/)

• Is the information issued by the command rpm -qlivp --changelog mypackage.(src.)rpm correct?

5.2. Linting the package

Then, you have to use the "rpmlint" program, which will test various things on the package. (it comes from the rpmlint package) Type rpmlint mypackage.<archtype>.rpm and a report on the specified package will be issued.

5.3. Install test

On a machine - different from the compilation one if possible - have an upgrade or an install, and then check:

• Are all the expected files created at their expected place with the expected rights and owners?

• Are all the installation modifications (if any) effective?

• Are all binaries executable, and documentation accessible by expected users?

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

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

7.1. For general RPM matters:

1. The official RPM-HOWTO (installed along with your rpm program on your system).

2. The book from RedHat Maximum RPM is available at http://rpmdp.org/rpmbook/.

3. Post a question in the mailing list rpm-list you subscribed a long time ago at the beginning of this howto.

7.2. For specific Mandrake RPM matters:

Drop a line to Mandrake's Quality Assurance, <qa@mandrakesoft.com>.

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

8.1. Menu system

As of the 7.1 version of Mandrake Linux, we now use the Menu System written by Debian.

This excellent software provides a Window-Manager independant way to register an application to the system. Most of the time, this registration will become effective in the Start button or alike of your favourite Window Manager.

It works like this: each package includes a file in directory /usr/lib/menu/. Most of the time the filename will be the name of the package. In this file, it will have one line per menu-entry, like this:

?package(xbase):command="/usr/bin/X11/xedit" icon="xbase.xpm" \
                needs="X11" section="Applications/Editors" title="Xedit" \
		longtitle="The basic editor for the X Window system" \
                mimetypes="text/html,text/plain" accept_url="false" multiple_files="true"

It is suggested that you put the menu file within the spec, instead of creating a separate source for it. To do that you can :

cat << EOF > $RPM_BUILD_ROOT/%{_menudir}/myprogram ... menu stuff here ... using ONE line only per menu entry ... EOF

in the %install section. You noticed the %{_menudir} macro. It shall expand to %{_libdir}/menu.

• command: the command to launch ; it can be absolute or not (if so, it will use the PATH of the Window-Manager)

• icon: the xpm icon to be used by the Window Manager to refer to the application ; mainly used in the start button alike, but also can be used to dock (include in a toolbar/panel) the app ; therefore, you will not give an absolute path, and provide three classes of icons in your rpm package: a 16x16, a 32x32, and a 48x48, respectively in /usr/share/icons/mini, /usr/share/icons, and /usr/share/icons/large with the same name. There are macros for these three directories: %{_miconsdir} ; %{_iconsdir} ; %{_liconsdir}.

• needs: there are three classes of needs:

  • x11 indicates an application that will be launched under a private window provided by the X-Window system;

  • text indicates an application needing a terminal to be run (for example, this is the case for "telnet", "gnuplot", etc);

  • the last one is the name of a Window Manager, in order to prevent the other WM's from proposing this app; for example you will like that "iceconf" appear in the menu only under icewm, and you will use needs="icewm" for this one.

• section: the section where the application will go ; it has to be normalized in order to be efficient, therefore see Appendix D for the complete menu structure

• title: the name under which the application will be registered in the start button alike of the Window Managers

• longtitle: used by the Window Managers which support tooltips to display more information

• mimetypes: used to link program with predefined mimetypes. If this mimetype is not recognized by KDE or GNOME, it must be added in mandrake-mime package (see in CVS, soft/mandrake-mime modules). Mimetypes are separated by commas. This keywords and following ones are only supported with Mandrake Linux 8.1 and above.

• accept_url: used for mimetype support. Specify if the program accept url on the command line. If not specified, default is false.

• multiple_files: used for mimetype support. Specify if the program accept multiple files (or urls) on the command line. If not specified, default is false.

Whenever root runs update-menus, it will check all new or changed menufiles in /etc/menu and /usr/lib/menu, and run the installation scripts Window Managers should provide in /etc/menu-methods on them. Use our special macros for that:

%post
%{update_menus}

%postun
%{clean_menus}

You will have to provide the three icons described earlier. One popular way of doing it is to declare the three icons, bzipped, with Source: tags, and install them in appropriate directories in the %install section:

Source10: %{name}.16.xpm.bz2
Source11: %{name}.32.xpm.bz2
Source12: %{name}.48.xpm.bz2
# ..

%install
# ..
install -d $RPM_BUILD_ROOT/%{_miconsdir}
install -d $RPM_BUILD_ROOT/%{_liconsdir}
bzcat %{SOURCE10} > $RPM_BUILD_ROOT/%{_miconsdir}/%{name}.xpm
bzcat %{SOURCE11} > $RPM_BUILD_ROOT/%{_iconsdir}/%{name}.xpm
bzcat %{SOURCE12} > $RPM_BUILD_ROOT/%{_liconsdir}/%{name}.xpm

8.2. Library policy

In order to enjoy better upgrades, it is important to keep old major library versions in the system so that programs which use them still work.

Libraries in /usr/lib, /lib and /usr/X11R6/lib must be separately packaged, in library-only package, named with the name of the main library concatenated with the major of the library. These packages should not contain any binaries, they should be separately packaged. The goal is to be able to install libfoo1 and libfoo2 on the same system.

In the first time it is fundamental that the sources rpm keep the same name without any major number, so that the CVS repository only contains one branch for each package.

When the distribution must contain two versions of the same library, for example qt1 and qt2, sources rpms will be separated so that we can include the two of them in the distribution. And since then the two branches will be independently maintained.

Here's a generic example; the following case happens when the library comes with binaries, config files, or anything else that won't fit in the main library package (where only libraries go) nor in the devel package (where headers and devel libraries go (e.g. *.so and *.a)).

Source Package:
        foo-2.3.4-4mdk.src.rpm

Binary Packages:
	foo-2.3.4-4mdk.arch.rpm 
        libfoo2-2.3.4-4mdk.arch.rpm
	libfoo2-devel-2.3.4-4mdk.arch.rpm

In the opposite case to this example, when replacing an existing package, for example foobar, with a new one called libfoobar3, in the case foobar will not exist any more because there are no binaries, and no config files, libfoobar3 must have an obsolete tag on foobar. This is often the case for "simpler" libraries.

Source Package:
        foobar-3.1-7mdk.src.rpm

Binary Packages:
        libfoobar3-3.1-7mdk.arch.rpm
        libfoobar3-devel-3.1-7mdk.arch.rpm

Ok we described the default policy for library packages, however some special cases can happen and must be handled using the brain. Remember to always check the soname of the libraries ("objdump -x libfoo.so.1 | grep SONAME"), because some sonames include library version number, for example libfoo-1.2.so.4, in this case the package should be named libfoo1.2_4-1.2.4-3mdk.

Packages ending with a number should be handle with a "_" before the major, for example libfoo23_4-1.2-3mdk (in this case the soname would be libfoo23.so.4).

It is not necessary to split each library in separate packages, if a package contains several library, the name would be build with the main library of the package. If there are problems keeping libraries in the same package, the package should be splitted.

It is important to supply some Provides. First reason: concerning the devel package, most of the time the client app will only want to put libfoo-devel in the BuildRequires, without any version information. Second reason, for compatibility with other RPM-based systems, it's important to provide also original names, qualifying versions. Please refer to following skeleton examples. It's important to understand that putting a Provides without the version information, makes it impossible for later client RPM's to put a version information on dependencies, e.g. "Provides: foo-devel" is NOT enough, please use "Provides: foo-devel = 1.2.4-3mdk".

Here's an example of specfile for a package with no binary and config files, so only lib* binary packages are needed.

%define name gtkmm
%define version	1.2.4
%define release 1mdk
%define lib_name_orig libgtkmm
%define lib_major 1.2
%define lib_name %{lib_name_orig}%{lib_major}

Name: %{name}
Summary: C++ interface for popular GUI library gtk+       #(!) summary for SRPM only
Version: %{version}
Release: %{release}

%description
#Full and generic description of the whole package. (this will be the SRPM
#description only)

#main package (contains *.so.[major].* only)
%package -n %{lib_name}
Summary: Main library for gtkmm                           #(!) summary for main lib RPM only
Group: System/Libraries
Provides: %{name} = %{version}-%{release}

%description -n %{lib_name}
This package contains the library needed to run programs dynamically
linked with gtkmm.

%package -n %{lib_name}-devel
Summary: Headers for developing programs that will use Gtk--
Group: Development/GNOME and GTK+
Requires: %{lib_name} = %{version}
Provides: %{lib_name_orig}-devel = %{version}-%{release}  #(!) **MANDATORY**
Provides: %{name}-devel = %{version}-%{release}           #(!) **MANDATORY**

%description -n %{lib_name}-devel
This package contains the headers that programmers will need to develop
applications which will use Gtk--, the C++ interface to the GTK+ (the Gimp
ToolKit) GUI library.

%post -n %{lib_name} -p /sbin/ldconfig
%postun -n %{lib_name} -p /sbin/ldconfig

%files -n %{lib_name}
# ..
%{_libdir}/*.so.*

%files -n %{lib_name}-devel
# ..
%{_bindir}/gtkmm-config
%{_includedir}/*.h
%{_libdir}/*.so

8.3. Deeper inside the specfiles...

Here are some more tags that you might see, some that you will see often, some not.

• Prefix: This is for package relocation. It should NOT be used if your package is not relocatable. Don't be fooled! Prefix: does not define where a package should go. To specify you want the prefix to be /usr, all you need to do is put Prefix: /usr, and rpm will verify that every files in the packages does start with /usr; if this verification succeeds, the package will be marked as relocatable.

• Requires: What is required for the binary package to run. Be advised that RPM will compute the dependencies on dynamic libs automatically.

• BuildRequires: What is required for this package to build. Most likely it is one of the X-devel packages. For example, for an ncurses based application, you would probably want to put libncurses-devel (see Section 8.2 for details about the Library policy). Logical operaters such as <, >, are accepted (but not the "not"), like in the Requires: field.

• BuildConflicts: What should not be installed on the machine for the build.

• Provides: This is used to provide "ghost" packages (also called "virtual" packages). For example, apache provides webserver, wu-ftpd provides ftpserver. It can also makes available articifial alternates: proftpd will also provide ftpserver, so that anything needing "any" ftp server will be able to add ftpserver in its Requires: field.

• Conflicts: What other packages does this conflict with. Logical operaters are supported.

• BuildArchitectures: Specify specific arch to build this package, and let RPM bail out with errors if one of the Architectures is not the one specified in the list.

• ExclusiveArch: Can only build on the specific arch specified. Packages like MILO, the Alpha equivilant of LILO will need this.

• ExcludeArch: Exclude the specified archs.

• ExclusiveOS: We really don't know why the heck you would need to use this. This excludes a piece of software from a a particular operating system.

• Epoch: (supersedes Serial) Sometimes, naming scheme has been done the wrong way and the authors goes back to an earlier version. In this case, you need the Epoch: tag with a number. This number will take over the versioning comparison, when rpm has to guess whether a given package is newer than another. Please see Section 8.4 for how to name packages released via pre-versions.

There is also some interesting macros to note. Say you wanted to do something, but not on every platform. You can do this within RPM with the conditional macros:

%ifarch alpha sparc ppc
%patch0 -p1
%endif

The explanation: only apply the patch if the architecture is alpha, sparc, or ppc. It is not limited to using here, for example you can include this in your %files section if you so wish.

Ok. So you know that you can use rpm -ba to build a package. But you have more to play around with:

• rpm -bp: stops after completion of the %prep section. Basically, it uncompresses the sources and applies the relevant patches.

• rpm -bc: stops after completion of the %build section. Generally involves the equivalent of "make".

• rpm -bi: stops after completion of the %install section. Well, do you have to use -ba to build again? No! All is not lost. The Mandrake RPM system has been specially patched to allow the -bi option to work with --short-circuit, which will basically resume the process. So, let's say you screwed up your %files section, and now you have fixed it, you don't have to build again from -ba. You can just use rpm -bi --short-circuit file.spec, and then rpm -ba --short-circuit file.spec to build it. Bear in mind, this is for advanced users ONLY as it is very easy to build a broken spec if you do that.

• rpm --eval %macroname can evaluate a particular RPM macro. This seems to be an undocumented feature in the RPM 3.0.x series. For example, if you would like to find the %packager macro stands for, do: rpm --eval %packager.

8.4. Releasing pre-versions

Sometimes, program naming schemes are good, but rpm is lost. For example, with Proftpd, Pre-releases are named with the version followed by the suffix pre and then the pre version number, like so: 1.2.0pre5. Because of string comparisons, rpm thinks that 1.2.0pre5 is newer than 1.2.0 (we know that this is not true).

To permit upgrades to newer packages, we must help rpm to know which packages are newer than others. We could use the Epoch: tag (superseding the Serial: tag) but this is dirty. You have to use another naming convention, putting the "pre" stuff in the release tag; in our example you will call the package "1.2.0-0.pre5.1mdk". Then, when 1.2.0 comes out, you'll release "1.2.0-1mdk", and this package will be able to upgrade the pre5.

8.5. update-alternatives

The program update-alternatives, originally written by Debian, is here to provide default system-wide commands through the use of symbolic links. An example will help to understand the point:

# Whenever you call 'vim'...
lrwxrwxrwx    1 root     root           21 Jan 31 10:25 /bin/vim -> /etc/alternatives/vim

# It will go to /etc/alternatives...
lrwxrwxrwx    1 root     root           26 Mar 20 00:51 /etc/alternatives/vim -> ../../usr/bin/vim-enhanced

# Then, to the real program.
-rwxr-xr-x    1 root     root      1724604 Jun 18 13:25 /usr/bin/vim-enhanced

When a new program wants to provide the same functionality (say, vim-minimal) it would register to the update-alternatives system, and potentially become the real program called under vim. The choice is either made automatically (under that scenario, the program with highest 'priority' will be used, see below) or manually.

Here's how emacs-nox and emacs-X11 register and unregister themselves to the update-alternatives system:

%post nox
update-alternatives --install %{_bindir}/emacs emacs %{_bindir}/emacs-nox 10
%post X11
update-alternatives --install %{_bindir}/emacs emacs %{_bindir}/emacs-%{version} 20

%postun nox
update-alternatives --remove emacs %{_bindir}/emacs-nox
%postun X11
update-alternatives --remove emacs %{_bindir}/emacs-%{version}

The syntax with the --install command is pretty self-explanatory: you need to provide the link, the name, the full path of the real binary, and the priority. Default behaviour of the resulting system is to follow the priority (e.g. the 'automatic' mode).

8.6. Signing your packages

Paranoid people sign their packages. This is not really necessary, but signing makes it more secure. Before Mandrake 7.2, you needed to download the crypto packages from a FTP site because of laws prohibiting the distribution of crypto packages. This is no longer true. The GNU Privacy Guard (GPG) is already included in the standard distribution. We recommend that if you wish to sign you use GPG to sign but RPM supports PGP as well.

First you will need to install PGP/GPG (depending on your liking). Now read the documentation. As with most *nix applications these come with good documentation. Generate a key, and then extract the ASCII key to a plain text file.

To sign your RPM packages while building, you can use the --sign argument. To add one to an existing RPM, do rpm --addsign file.rpm. To resign an existing one, use the --resign option. But alas, when you type this you get nothing, because you still haven't set up your ~/.rpmmacros yet.

Now, add 2 lines to your ~/.rpmmacros. Add %signature pgp and %_pgp_name Your_Signature_Name. Replace pgp with gpg, if you choose to use that one instead.

8.7. More on the files section

Sometimes setting the permissions of the installed files for RPM is not always %defattr(-,root,root). You can set individual permissions for files, with the %attr() macro. %attr follows a similar format to %defattr, except that %attr is put in front of the filename.

To tell RPM that the file specified is a configuration file, place a %config at the front of the file. That way, RPM will upgrade the file, but save a copy of the old one (with the extension .rpmsave). Most of the time, it is NOT the desired behaviour, because you shall lose (temporarily) your precious configuration in exchange of the default one which is obviously far poorer than what you need. To address this issue, use %config(noreplace): it indicates that the file in the package should be installed with extension .rpmnew if there is already a modified file with the same name on the installed machine.

The %config(missingok) indicates that the file need not exist on the installed machine. The %config(missingok) is frequently used for files like /etc/rc.d/rc2.d/S55named where the (non-)existence of the symlink is part of the configuration in %post, and the file may need to be removed when this package is removed. This file is not required to exist at either install or uninstall time.

The %ghost tag on a file indicates that this file is not to be included in the package. It is typically used when the attributes of the file are important while the contents is not (e.g. a log file).

8.8. Subpackages

To split off into a subpackage you can specify %package foo where foo is the suffix that will be added to the main package name.

For example, if your main package name is fred, and you have a %package alice line , then your subpackage will be called fred-alice. You will need to add in the corresponding name in the %description and %files, for example, %description alice, %files alice.

If you don't wish to have RPM inherit the name of your main package as the prefix of the subpackage, you can specify the -n argument to %package, like so: %package -n mysubpackage. You will need to add -n for all other relevant RPM entries as well such as %description, %files and the RPM scripts. One such application of this would be the library policy mentioned earlier.

8.9. What to avoid

This subsection is for experienced RPM builders -- to be sure that they do not miss the point.

• Avoid any reference to $RPM_SOURCE_DIR. When using multiple sources, some people tend to reference these sources using this tag. This should be avoided and replaced by %{SOURCE2} for the Source2: source, for example.

• Avoid to do tricky/clever/strange things in the specfile without documenting it. Most of the time, putting a comment on the line before, with your initials, is very helpful for future re-packagers, in the following style:

  # (gc) I want to grab the xmms-config built in .., for bootstrapping nicely export PATH=".:$PATH"

8.10. Locale specific packages

Some packages are only meant to be used together with special localization(s). For example, cttex, a Thai word separator program, will be useless when you don't use your system in Thai.

For such packages, you need to put an explicit Requires: on the corresponding locale package (here, locales-th). With these information, the installer will be able to change the rates of the packages according to selected internalization configuration, so that the necessary packages get installed.

8.11. Easy handling of differences between two RPM's

Here is how Chmouel handles finely the differences between two RPM's.

rpmdiff () {
        if [[ -z $1 ]]
        then
                "Need a package"
                return 1
        fi
        package=$(rpm -qp --qf '%{NAME}' $1) 
        if [ -f /RPMS/$package-[0-9]* ]
        then
                /usr/bin/rpmdiff /RPMS/$package-[0-9]* $1 | \
                egrep '^(missing|added)' | egrep -v '/usr(/share)?/doc/'
        else
                echo "Can't find the pacakge  in /RPMS/"
        fi
}

example :

(chmou@kenobi)[RPMS/i586]-% rpmdiff util-linux-2.10n-1mdk.i586.rpm
missing    /usr/lib/more.help
added      /usr/share/misc/more.help
(chmou@kenobi)[RPMS/i586]-% 

8.12. To become a Jedi, use Emacs you have to

In a nutshell, Emacs can automate much of the work, with appropriate configuration file. A good start is Chmouel's, which is too big even to fit in appendices (> 1000 lines). You can find it on the web here: ftp://ftp.mandrakesoft.com/chmou/pub/rpm-spec-mode.el

Once installed, in addition to nice syntax highlighting, you'll increase the release tag with C-c r, add a new changelog entry (with your name, email address, correct version and release tag) with C-c e; you will even visit the bzipped patches (granted you have jka-compr and ffap) with minimal pain! And much more...

To use ffap/jka-compr in spec-file you can tell to the user to set this in ~/.emacs:

(if (not (jka-compr-installed-p)) (toggle-auto-compression))
(require 'ffap)
(defvar ffap-spec-path '("../SOURCES"))
(defun ffap-spec (name) (ffap-locate-file name t ffap-spec-path))
(add-to-list 'ffap-alist '(rpm-spec-mode . ffap-spec))