SUSE Build Tutorial

From openSUSE

Introduction

This document is an overview of the SUSE build structure and a tutorial on how to build RPM packages for openSUSE. This information will help you set up your own temporary build environment. The first four parts of this document give a general overview on how things work followed by examples for you to try out.

Prerequirements

You should have a good understanding about the creation of RPMs. This document is not aimed to be a replacement for RPM documentation. There are already many HOWTOs, Guides and Books for this see the resources paragraph for RPM related links.

You should also have some experience with PGP related tools, especially GNU Privacy Guard (gpg) since it is the most widely used implementation of OpenPGP. We will explain why PGP is important later on when we talk about package signing. To sign packages you will need your own PGP key before you start to use the openSUSE build environment.

And of course you should be familiar with the source code environment your project is using for your package. The openSUSE build structure can work around some common mistakes made by project maintainers but knowing something about make, autoconf, imake or other source code configuration mechanisms will be helpful when working with packages.

Requirements

That's simple. You need 3 GB of hard disk space and our build tool, build. That's it.

You need 3 GB of hard disk space because the SUSE build structure is using a separate linux installation on your hard disk as the environment to build your package. This isolated environment has one big advantage: Building a package won't tamper with your current linux installation. The only disadvantage is that you need 3GB of (temporary) hard disk space for every separate build environment. But with today's hard disk capacities this shouldn't be a problem.

The build tool sets up a build environment in a given location and then builds the package in that environment. The build environment consists of a base system and any additional packages you specify in the RPM spec file.

Work flow

The following steps outline a normal work flow to build a package. Of course in a real world example you might fail at some step and have to repeat it until it does not fail anymore. This outline is just to give you a feeling what we are trying to achieve.

Step One - Install requirements

Install the following packages from your openSUSE installation source using YaST, if you don't have them already installed:

• build
• gpg

Step Two - Configure build

Configure the build tool . There are some settings you have to tweak to match your local environment. For example:

• where to get the RPM packages to set up the build environment
• what is the basename for build root directory

and things like that.

Step Three - Create source directory

Create a directory somewhere that is accessible to you and root. This is the location where you put your files used to build the package. You can use any location you want. However, it must be accessible for you and root because only root can start the build environment setup. But you don't want to work as root all the time on the package so you need a shared location.

Step Four - Get project source files

Get the project's source files necessary to build the package. Most projects provide source files in compressed tarballs.

Step Five - Create the spec file

Now that you have the source you follow the usual RPM creation process. Create a specfile for the package.

Step Six - Build the package

After you have created the RPM spec file it is time to try to see if it builds. Switch to the root account and change into the directory where your spec file, source, and patches are. Then, start build.

Step Seven - Test the package

After the build has succeeded you should test the functionality of your package.

Specfiles

RPM specfiles should be written according to the openSUSE Package Conventions. As this is a fairly complex topic by itself there is an extra document about it. Please follow this Document closely while developing your specfile.

You can find some example specfiles for different packages in the Build Service SVN.

Configuration

build Environment Variables

• BUILD_DIST

The Distribution you want to build for.

• BUILD_RPMS

This is were the openSUSE RPMS are supposed to be: if the openSUSE DVD has only been mounted, this variable should be set to <DVD_mount_point>/suse. If the DVD has been copied into a directory, this variable should be set to <that_directory>/suse.

BUILD_RPMS default value is /media/dvd/suse

• BUILD_ROOT

The isolated chroot directory where the rpm will be built.

BUILD_ROOT defaults to /var/tmp/build-root

• BUILD_RPM_BUILD_STAGE

This is the actual option(s) that will be passed to rpmbuild (see rpmbuild man page to have a complete list of these options)

BUILD_RPM_BUILD_STAGE default value is '-ba' (i.e. Build binary and source packages after doing the %prep, %build, and %install stages).

Examples

Here are some realworld examples for different exemplary package groups and specific package features.

KDE Packages

BuildRequires: kdelibs3-devel update-desktop-files

Name:         kvpnc
License:      GPL
Group:        Productivity/Networking/System
Summary:      GUI frontend for openswan and vpnc
Version:      0.7.2
Release:      1
URL:          http://home.gna.org/kvpnc/
BuildRoot:    %{_tmppath}/%{name}-%{version}-build
Source0:      %name-%{version}.tar.bz2

%description
The application can create configurations for various kinds of VPN
connections. You should install also the "vpnc" or "openswan" package.

%prep
# extract the source and go into the kvpnc-0.7.2 directory
%setup -q
# source the standard build enviroment as defined in kdelibs3 package
. /etc/opt/kde3/common_options
# replace the admin/ folder with the version from kdelibs3 (will work for sure with
# current autoconf and automake) and create Makefile.in and configure script.
update_admin --no-unsermake

%build
# source the standard build enviroment as defined in kdelibs3 package
. /etc/opt/kde3/common_options
./configure $configkde --disable-final
# do compile with the number of jobs given to the --jobs parameter of the build script.
make %{?jobs:-j%jobs}

%install
iconv -f iso8859-1 -t utf-8 src/kvpnc.desktop > w && mv w src/kvpnc.desktop
# install all files into the BuildRoot
make DESTDIR=$RPM_BUILD_ROOT install
rm -rf $RPM_BUILD_ROOT/opt/kde3/share/doc/HTML/kvpnc
# updates the .desktop file. It applys additional translations and Categories for a 
# proper position in the KDE menu
%suse_update_desktop_file %name System Network
# does find all localisation files and adds proper database attributes to them
%find_lang %name

%clean
# clean up the hard disc after build
rm -rf $RPM_BUILD_ROOT

%files -f %name.lang
%defattr(-,root,root)
%dir /opt/kde3/share/icons/hicolor/16x16/apps
%dir /opt/kde3/share/icons/hicolor/32x32/apps
/opt/kde3/bin/kvpnc
/opt/kde3/share/appl*/*/kvpnc.desktop
/opt/kde3/share/apps/kvpnc
/opt/kde3/share/icons/*/*/*/kvpnc*.png

Gnome Packages

Guidelines for creating GNOME packages have moved to the GNOME packaging page.

Perl Packages

Perl packages are quite easy and similar to package because they are almost already prepared for the CPAN archive.

Name:         perl-Curses
Version:      1.12
Release:      1
# define the name from CPAN
%define cpan_name Curses
# do this package was known as "perl_cur" in old times. So we do need to Provide and Obsolete
# this package. YaST will install this package during update instead of the old one in this way.
Provides:     %cpan_name
# we better require the exact perl version, which was used to create this package
Requires:     perl = %{perl_version}
Group:        Development/Libraries/Perl
License:      Artistic License, Other License(s), see package
URL:          http://cpan.org/modules/by-module/Curses/
Summary:      A Dynamic Loadable Curses Module for Perl5
Source:       %cpan_name-%{version}.tar.bz2
BuildRoot:    %{_tmppath}/%{name}-%{version}-build

%description
This is a dynamic loadable curses module for Perl5.  This package can
be found at any CPAN archive.

%prep
%setup -q -n %cpan_name-%{version}

%build
perl Makefile.PL OPTIMIZE="$RPM_OPT_FLAGS -Wall"
make
make test

%install
make DESTDIR=$RPM_BUILD_ROOT install_vendor
%perl_process_packlist

%clean
# clean up the hard disc after build
rm -rf $RPM_BUILD_ROOT

%files
%defattr(-,root,root)
%doc Artistic Copying README
%doc %{_mandir}/man3/*
%{perl_vendorarch}/%cpan_name.pm
%{perl_vendorarch}/auto/%cpan_name
/var/adm/perl-modules/%{name}

Resources

• Package Conventions
• Maximum RPM - A book about the RPM Package Manager
• RPM HOWTO
• RPM Guide by Eric Foster-Johnson
• build HOWTO By Paul MacKay
• RPM install/uninstall script reference
• Presentation containing a good overview about make and autoconf by Stefan Hundhammer
• rpmbuild(8) man pages
• build(1) man pages