View source for Building RPMs - Quick Start

{{Introduction|This document contains a brief but complete overview of RPM package creation for ROSA Desktop distributions. The document doesn't reflect all aspects of packaging, for more details please take a look at the documents mentioned at the bottom of this page.}}

== Getting ready for the build and overview of the spec file ==

First, let's check what do we need in our system to build an rpm package. It is necessary to install {{pkg|rpm-build}} package that provides the rpmbuild command. Along with it, a bunch of other packages will be automatically installed that are used during the build. In ROSA we normally don't mention C/C++ compiler as explicit build requirement for every package, so it is not installed automatically and sooner or later you will have to install {{Pkg|gcc}} and {{Pkg|gcc-c++}} packages. All other packages required to build particular package should be required by the spec file of the package being built. Surely, there can be error in build requirements and during the build you will notice that missed something, but such issues easy to fix.

And what is an RPM package? One should distinguish RPM packages with sources ({{file|src.rpm}}) and packages with compiled programs tha are ready to be installed to the user's system {{file|%{arch}.rpm}}. Src.rpm packages contain tarball with program source code, patches and '''spec''' file that controls the build process. All this files are archived using cpio. You can see this archive if you enter inside rpm package using  {{Prog|mc}} file manager. The package can also contain some otheradditional files.

%{arch}.rpm packages contains cpio archive with program files that will be placed to proper folders during package instalation, different metadata and installation scripts.

You can also meet packages without source code inside. They are usually created for proprietary software which cannot be included into distribution (sources are not availavble, and the binary files should be preliminary adopted for particular system or it is just prohibited to out them to the distribution mirrors). Such a package often contain only a spec file. Binaries are downloaded from upstream during the package installation process (for example, inside a post script, which will be discusse later).

One can build packages under any user. However, it is not recommended to build packages under the root account, since there is a little chance that erroneous installation will use root folder ({{file|/}}) as installation root and then commands like {{cmd|rm -rf %{buildroot} }} will destroy the whole system. It also happens that malformed packages incorrectly install their packages not in the temporary folder, but somewhere in {{macro|%{_prefix} }} ({{file|/usr}}). This will lead to a system pollution and can even lead to loss of important files.

What should user do to be able to build packages? First, it is necessary to go to the home folder and create {{file|rpmbuild}} folder there with the following structure:

 ~/rpmbuild
 |-- BUILD
 |-- BUILDROOT
 |-- RPMS
 |   |-- i586
 |   |-- x86_64
 |   `-- noarch
 |-- SOURCES
 |-- SPECS
 `-- SRPMS

You should create {{file|BUILD}}, {{file|RPMS}}, {{file|SOURCES}}, {{file|SPECS}}, and {{file|SRPMS}} folders manually, {{file|RPMS}} subfolders will be created automatically during the package build.

In ROSA it is not recommended to explicitely mention packager and vendor in the spec; these tags are set automatically by the ABF build system. ABF also automatically signs every package that goes to official repository. So we won't consider package signing here.


Now let's take a look at the main file of the package - '''spec'''-file. Let's take a spec from the {{pkg|stardict}} package which is a good example, since it contains several tarballs (files with program soruces archived with {{cmd|tar}}), produces several subpackages and has some additional scripts. Usually spec file has the same name as the package itself- ({{file|stardict.spec}}). Though you can add package version if you are going to maintain several versions at once - ({{file|stardict-2.spec}}). Actually you can use any name, but this is not convenient and not recommended.

Content of the {{file|stardict.spec}} is shown below. We will insert our comments directly after each section of the spec, but if you simply join all the sections into a single files, you will get a complete {{file|stardict.spec}}.

Spec-file contains several sections and heading:

 Summary:        StarDict dictionary
 Name:           stardict
 Version:        2.4.8
 Release:        4
 License:        GPL
 URL:            http://stardict.sourceforge.net
 Group:          User Interface/Desktops
 Source0:        %{name}-%{version}.tar.bz2
 Source1:        %{name}-tools-%{version}.tar.bz2
 Patch0:         %{name}-2.4.8-desktop.patch

Tag names are self-explanatory. You can easily get access to the '''Name''', '''Version''' and '''Release''' tags anyhwhere in the spec using corresponding macros - {{macro|%{name} }}, {{macro|%{version} }}, {{macro|%{release} }}. '''Name''' and '''Version''' are usually reflected in the tarball name. If they are not, you will have to use some tricks inside your spec to unpack the tarball. If you build a package on the basis of snapshot of CVS, SVN or other VCS, then it is recommended to define a variable equal to the snapshot date in the beginning of the file {{macro|%define date 20070422}} and form the '''Release''' tag in the following way:

 Release: 0.git%{date}.4

Next we see a '''License''' as specified by software vendor, '''URL''' of a program site and a software '''Group''' the package belongs to. To choose a group, you can look at similar packages and check which group they use, or just choose a group from the [http://wiki.rosalab.ru/en/index.php/Packaging_group groups used in ROSA].

'''Source*''' — files with source code (either tarballs or regular files). In our example we have two tarballs with different programs; this significantly complicates the build. Regular files )(e.g., configs) can be simply copied to the destination in the %{{macro|%install}} section by means of {{cmd|install}} command. It has a vert straightforward syntax: {{cmd|install -m file_mask_in_chmod_style src dst}}. It can be used to create folders, as well. We don't use this command in our example; you can read more about it in its man page.

'''Patch''' — patches that should be applied to the original source code. It isn't acceptable to modify the code of the program itself and pack it back to the tarball - this will really complicate program updates. Standalone patches are used instead. They can be made in the following way. Unpack the source tarball (stardict-2.4.8 in our case) and copy stardict-2.4.8 to stardict-2.4.8.orig. After this, make necessary changes in the  stardict-2.4.8 folder, leave it and launch {{cmd|diff -ur stardict-2.4.8.orig stardict-2.4.8 > stardict-2.4.8-patch_name.patch}}. As one can see, the patch hash {{file|%{name}-%{version} }} prefix - this is the recommeded way of patch naming. In the spec file it is recommended to type patch name without macros (at least do not use {{macro|version}}). Otherwise after vesion update you will get an updated version macro and rpmbuild will look for a new patch name, while it's likely that the patch canbe applied to a new version without any changes. If the patch fails to apply to the new version, you should find the reasons and either update for the new program or just drop it.

In spec files of many distribution you can also meet definition of {{macro|BuildRoot}} - a folder that should be used for the build. In ROSA, there is no need to define BuildRoot, its name is formed automatically.

 BuildRequires:  libgnomeui-devel >= 2.2.0
 BuildRequires:  scrollkeeper
 BuildRequires:  gettext

 Requires(post):   GConf2
 Requires(post):   scrollkeeper
 Requires(postun): scrollkeeper

{{macro|BuildRequires}} section lists packages that are required to build our program. You can create such a list on the basis of README or INSTALL files from the program (though they rarely contain anything useful for this), from the configuration script (usually {{cmd|configure}}) and tfrom the build process itself (it happens that {{cmd|configure}} misses checks for some deopendencies and build fails).

{{macro|Requires}} — this section lists packages and files that should exist in the system for successful package installation. Rpmbuild automatically detects and sets dependencies on libraries, but you can also add dependencies manually. {{prog|Rpm}} also automatically adds dependencies on perl, python, mono and some other staff (to be sure, these dependencies are added to the package itself, not to the spec). If you don't want dependencies to be added automatically, you should add '''AutoReq: no''' to your spec. It is often used for proprietary programs with a lot of internal libraries, since {{prog|rpm}} may erroneously add dependency on something which is built into the program itself.

In our example we use {{macro|Requires(post)}} and {{macro|Requires(postun)}} to indicate dependencies necessary for post-install and post-uninstall scripts. It would also work to simply write  {{macro|Requires}}, but these dependencies are not needed for StarDict istelf, tey are required only to install/uninstall it. So this is just a matter of neatness.

There are some other useful tags which we haven't used in our example.

 Provides: name1, name2

- other names besides {{macro|%{name} }} that can be used to reference this package. This is convenient if you change the package name but there are other packages requiring the old name.

 Obsoletes: name1, name2

— indicates that these packages can be removed after instalation of this package, since it provides the same functionality, set of files, etc. One can use limitation on versions of packages that are obsoleted - {{macro|name <|>|<=|=|=> version}}. Hopefully this is self-explanatory.

 Conflicts: name1, name2

— list of packages that conflict with the current one. Such packages should be removed in order for the current one to be installed. Here you can use {{macro|name <|>|<=|=|=> version}}, as well.

 Suggests: name1, name2

- ''soft'' dependencies - packages that supply the current package with somme additional functionality (e.g., additional codecs for media players) but which are not obligatory to install and use the package.

 Epoch: number

— usually not set or set to 0. The aim of this parameter is like the following. Assume that our {{pkg|stardict}} package has version  '''2.4.8''' and there is an older package with version '''2.4.5'''. However, if {{pkg|stardict 2.4.5}} has {{macro|%{epoch} }} equal to '''1''' and {{pkg|2.4.8}}'s epoch is equal to '''0''', then {{pkg|stardict-2.4.5}} will be considered by  {{prog|RPM}} to be newer than {{pkg|stardict-2.4.8}}. This trick is used if one needs to downgrade the package in repository so it will be automatically downgraded by  {{prog|urpmi}} or {{prog|rpmdrake}} in users' systems during the next update. If {{macro|Epoch}} is set to zero, then the package is considered to be newer than the same package without {{macro|Epoch}}.

 BuildArch: architecture

— target hardware architecture. If this option is not set, the current system architecture will be used. Usually this option is used to indicate '''noarch''' packages that don't contain arch-specific binary files.

 ExclusiveArch: architecture1 architecture2

— indicates that the package can be built only for these architectures. Often used when building kernel modules.

Here the heading ends. Let's proceed with different sections

 %description
 StarDict is an international dictionary written for the GNOME environment.
 It has powerful features such as "Glob-style pattern matching," "Scan
 seletion word," "Fuzzy search," etc.

Description of the main package which will be named as {{macro|%{name} }}

 %package tools
 Summary:        StarDict-Editor
 Requires:       %{name} = %{version}-%{release}
 Group:          User Interface/Desktops

Here we define a subpackage named {{pkg|%{name}-tools}}. If you want to use a completely different name, you can define it like the following: {{macro|%package -n tools-stardict}}. Subpackage versionis set from the {{macro|Version}} macro. Note that we have a {{macro|Requires}} record mentioning the main package - {{pkg|stardict}}. If it had {{macro|%{epoch} }}, then it would be necessary to use {{macro|Requires: %{name}-%{epoch}:%{version}-%{release} }}, otherwise the package would fail to update.

 %description tools
 A simple tool for StarDict.

Subpackage description

 %prep
 %setup -q -a1
 %patch0 -p1

The {{macro|%prep}} section contains preparation steps performed before the build. {{macro|%setup}} unpacks the source code tarballs. '''-q''' option suppresses the output of unpacking process. '''-a1''' forces unpacking of {{macro|%{SOURCE1} }} inside(!) the folder extracted from the first tarball (a number after the option stands for the SOURCE number). Alternatively, '''-b''' option can be used to unpack second tarball to the same folder as the first one. If you have only one tarball then neither '''-a''' nor '''-b''' are used.

If name of the folder extrated from the first tarball differs from {{file|%{name}-%{version} }} then {{prog|rpmbuild}} will fail to enter inside it. In this case you should modify {{macro|%setup}} a little. If {{file|stardict-2.4.8.tar.bz2}} the top-level folder is named  {{file|stardict}} then setup should look like te following:

 %setup -q -n %{name} -a1

Just after tarball unpacking and before invocations of the {{macro|%patch}} macro you can copy additional files or launch some utilities to modify the program sources. For example, copy additional localization files or use {{cmd|sed}} to quickly fix some soure files. Just call {{cmd|cp}}, {{cmd|sed}} and other commands. Remember that the working folder for these operations is the one where the first tarball is unpacked (name of this folder is stored in the $RPM_BUILD_DIR variable, but it is used very rarely).

The {{macro|%patch}} macro is used to apply patches. If you created a patch in the way we described above, then you should pass '''-p1''' option to the macro. The {{cmd|-b .patch_name}} is also often used to create a backup copy of the patched files.

 %build
 pushd %{name}-tools-%{version}
 %configure
 %make
 popd

 %configure
 %make

In the {{macro|%build}} section the build itself takes place. Draw attention to the {{cmd|pushd}} and {{cmd|popd}} commands. They are used to enter the folder from the second tarball and leave it after the build. So after the {{cmd|pushd}}, that folder becomes current. {{cmd|popd}} returns us to the folder of the first tarball. If you have only one source tree, there is no need in these commands.

Since we have two programs in one package, we call {{macro|%configure}} and {{macro|make}} twice. If the program should be configured using {{prog|autotools}}, then the {{macro|%configure}} macro launches {{cmd|configure}} script from the unpacked tarball. It usually has a lot of parameters that can be viewed in command line by means of {{cmd|./configure --help}}. You can pass necessary options just after the {{macro|%configure}} macro. Note that invocation of {{macro|%configure}} differs from direct launch of {{cmd|./configure}}. In the first case some additional parameters will be passed automatically, such as installation paths, while in the second case default values will be used.

Successful configuration is followed by the build - the {{macro|%make}} macro that calls a command with the same name and passes some additional parameters to it (in particular, on multicore systems parallel make is invoked using the '''-j''' option).

If the program doesn't use {{prog|autotools}}, then {{macro|%configure}} (and maybe {{macro|%make}}) are not necessary; please refer to README and INSTALL files of the program for details. ROSA provides macros for some other common cases e.g., {{macro|%cmake}} macro for the case when cmake should be used.

If the build is completed successfuly, rpmbuild proceeds with the {{macro|%install}} section.

 %install
 pushd %{name}-tools-%{version}
 %makeinstall_std
 popd

 %makeinstall_std

 %find_lang %{name}

%{{macro|%find_lang}} is used to look for localization files. It takes name of localization files as a parameter and looks for appropriate files in {{file|%{buildroot}/usr/share/locale/*/LC_MESSAGES/*.mo}}. Usually this name is equal to {{macro|%{name} }}. If not, pass necesasry name to {{macro|find_lang}}.


In many spec files you can see that {{cmd|rm -rf %{buildroot} }} or {{cmd|rm -rf $RPM_BUILD_ROOT}} is performed in the beginning of {{macro|%install}}, as well as the {{macro|%clean}} section with the same commands. In ROSA there is no need in such clean up, it is performed automatically.

 %preun
 %preun_uninstall_gconf_schemas %{name}

These are sections with installation scripts. There are four kinds of such scripts: {{macro|%pre}} is launched before installation, {{macro|%post}} — after installation, {{macro|%preun}} — before removal, {{macro|%postun}} — after removal. In our example we remove Gconf schema and assume that we the package has only one schema whose name is equal to the package name. Note that we use a special macro to remove schemas; this macro is expanded by rpmbuild in ROSA to a set of shell commands. Installation of schemas is performed automaticaly by RPM using the [[Rpm_filetriggers|file trigger]] mechanism.

You can write usual Bash scripts in these sections (as well as in any other section of the spec). If you don't need to perform any actions of such kind, just omit pre/post sections in your spec.

In the {{macro|%files}} sections one shoud declare which files should be included in every package or subpackage. Every installed file should be assigned to some package, otherwise rpmbuild will report unpackaged files and fail.

'''-f''' is used to specify a file with list of files to be included. In our case we specify a file with a list of localization files.

Specialized macros are used for system folders:

* {{macro|%{_prefix} }} — {{file|/usr}}
* {{macro|%{_sysconfdir} }} — {{file|/etc}}
* {{macro|%{_bindir} }} — {{file|/usr/bin}}
* {{macro|%{_datadir} }} — {{file|/usr/share}}
* {{macro|%{_libdir} }} — {{file|/usr/lib}} or {{file|/usr/lib64}}, depending on system architecture
* {{macro|%{_lib} }} — {{file|/lib}} or {{file|/lib64}} corerspondingly
* {{macro|%{_libexecdir} }} — {{file|/usr/libexec}}
* {{macro|%{_includedir} }} — {{file|/usr/unclude}}
* {{macro|%{_mandir} }} — {{file|/usr/share/man}}
* {{macro|%{_sbindir} }} — {{file|/usr/sbin}}
* {{macro|%{_localstatedir} }} — {{file|/var}}.

 %files -f %{name}.lang
 %defattr(-, root, root)
 %doc AUTHORS COPYING INSTALL README NEWS
 %{_sysconfdir}/gconf/schemas/stardict.schemas
 %{_bindir}/stardict
 %{_bindir}/stardict-editor
 %{_libdir}/bonobo/servers/GNOME_Stardict.server
 %{_datadir}/applications/*.desktop
 %{_datadir}/stardict
 %{_datadir}/locale/*/LC_MESSAGES/*
 %{_datadir}/pixmaps/stardict.png
 %{_datadir}/gnome/help/%{name}/*
 %{_datadir}/idl/GNOME_Stardict.idl
 %{_datadir}/omf/*
 %doc %{_mandir}/man?/*

{{macro|%doc}} marks files as documentation. The third line copies these files to the {{file|%{_datadir}/doc/%{name}-%{version} }} folder.

By default, files in the package will be owned by root and their access permissions will be the same as set during the installation. If owner or permissions should be changed, use {{macro|%defattr}}.

After these lines, a simple enumeration of files follows.

 %files tools
 %{_bindir}/stardict-editor

The same for {{pkg|stardict-tools}} subpackage. If it were called {{pkg|tools-stardict}} then {{macro|%files}} would look like the following:

 %files -n tools-%{name}.

The last section in the spec is {{macro|%changelog}}. It contains a list of changes with respect to the previous version and usually formatted in the following way:

 %changelog
 * Sun Apr 22 2007 Your Name <your@email> - 2.4.8-4
 - update desktop patch


== Macros ==

Now it's time to get familiar with macros and variables. For example, assume that we are building a package from SVN snapshot and want to include snapshot date to release. In order to do this, we define a variable in the beginning of the spec:

 %define date 20070612

As you may see, variables are introduced through the {{macro|%define}} macro. Now anywhere in spec file you can refer our variable as {{macro|%{date} }} (braces are not obligatory, but in ROSA we have agreed to enclose variables with braces but leave macros without them, so so it is easier to distinguish variables from macros). In particular, definition of Version and relese will look like the following:

 Version: 0.5
 Release: 0.svn%{date}.3

Note that '''0.''' is appended before the date, and only after the date we append a number which is incremented in case we want to increment the release. Why do we follow this way? The thing is that when the final version is released ('''0.5''' in our case), revision number will be removed and release will be set to '''1'''. Since '''1''' is literally greater than any string starting with '''0''', the  resulting package will be considered to be newer than preliminary packages built from SVN snapshots.

One of the frequently used things is conditional operator:

 %if condition
   action1
 %else
   action2
 %endif

Or the same without {{macro|%else}}. This construction is straightforward - if {{macro|condition}} is true, then {{cmd|action1}} is executed, otherwise {{cmd|action2}} is launched.

Assume again that we are building something from SVN snapshot. Very often archives created from SVN contains a folder named {{macro|%{name}-%{version} }}, not {{macro|%{name}-%{version} }} (the {{file|sim-0.9.5.tar.bz2}} tarball has {{file|sim}} folder inside, since  sim 0.9.5 is not released; tarball with the final release will contain a folder named {{file|sim-0.9.5}}). To avoid necessity to modify spec file every time, you can use the following construction:

 %define svn 1
 ...
 %prep
 %if %{svn}
 %setup -q -n %{name}
 %else
 %setup -q
 %endif

If '''svn''' variable is not set, then instructions in the {{macro|%else}} branch will be launched. One can use stricter conditions: (do not forget about commas):

 %define svn 1
 ...
 %prep
 %if "%{svn}" == "1"
 %setup -q -n %{name}
 %else
 %setup -q
 %endif

Inside every section of the spec we can use any Shell command "as is", but it's not so easy for the spec heading. For example, assume that we need to detect Firefox version for some package (e.g., epiphany) to put it to the {{macro|Requires:}}. This will look like the following:

 Requires:       firefox = %(rpm -q firefox --qf "%%{version}")

Note that external command is laucnhed using {{cmd|%()}} (almost like in Bash - {{cmd|$()}}) in spec and parameters are passed using double '''%'''. You can execute any Linux command in this way.

One more popular macro is {{macro|%ifarch}} .. {{macro|%endif}} construction. Actions inside this block are executed only if architecture matches the one specified after {{macro|%ifarch}}. Architectures include x86_64, %{ix86} (a macro that expands to a list of supported x86 platforms) and others

As we have already noticed, in every spec file section you can use all Shell commands such as for, while, if, etc.

== Building a package ==

Now let's actually build a package. Tarballs with sources and patches should be put to the {{file|SOURCES}} file, a recommended places for spec files is the {{file|SPECS}} folder. After this you can simply type:

  rpmbuild -ba spec-file

and the build will be started. If it succeeds, then you will find resulting binary packages in the approrpiate subfolder of the {{file|RPMS}} directory and the source RPM in the {{file|SRPMS}} directory.

Often at the end of the build {{cmd|rpmbuild}} reports installed but unpackaged files. This means that you forgot to mention that files in the {{macro|%files}} sections. Just add them there. But if you don't want these files to be included in the package, use one of the following tricks:

* Add the followin line to the {{macro|%files}} section:
 %exclude path_to_file/file
* Add the following line to the beginning of the spec:
 %define _unpackaged_files_terminate_build 0

If you want to build only binary or only source rpm, replace '''-ba''' with '''-bb''' or '''-bs''' correspondingly. From other useful {{cmd|rpmbuild}} parameters one can mention '''-clean''' (remove all temporary files after the packages are made), '''--rmsource''' (remove sources from {{file|SOURCE}}) after build and '''-target=architecture''' (build package for given architecture).

You can also launch only particular section. We won't describe such parameters here, see '''man rpmbuild''' for more details.

== Rebuilding RPM package from the installed one ==

It sometimes happens that a package is already installed in your system but you can't find rpm package itself anywhere, or you may want to rebuild some installed package with different configs.

This problem can be solved by means of '''rpmrebuild''' tool. This is actually a Bash written and it is available in the ROSA contrib repository.

The tool is very easy to use. Just type:

 rpmrebuild name_of_installed_package

If some file has beed modified since the installation, you will be informed about this, but this won't be treated as error.

{{Cmd|Rpmrebuild}} has a lot of options - for example, you can change package release, changelog, scripts, Requires sections, description and a lot of other characteristics. You can even reuse a spec file which will be generated by the script. Though it will look a little ugly, but it's better than nothing.

You can get the whole list of parameters using

 rpmrebuild --help

and

 rpmrebuild --help-plugins


== See Also ==
[[Packaging_HowTo]]

[[:Category: Packaging Guidelines|ROSA Packaging Guidelines]]


{{Note|title=Note|msg=This page is based on several posts from the "Notes about Linux" blog:
* [http://tigro.info/wp/?p=270 Building packages. Chapter 1. RPM. Part 1. What kind of RPM packages exist and where to find them] (in Russian)
* [http://tigro.info/wp/?p=287 Building packages. Chapter 1. RPM. Part 2. Build preparation and spec file overview] (in Russian)
* [http://tigro.info/wp/?p=316 Building packages. Chapter 1. RPM. Part 3. Macros and package building] (in Russian)
|img=Idea.png}}

[[Category:Package_Management]]
[[Category:Packaging Guidelines]]
[[Category:ROSA_Developer_Tools]]

[[Ru:Сборка RPM - быстрый старт]]