Packaging
From ArkWiki
Contents |
[edit] How to build RPMs for Ark Linux
Copyright 2004, Joan Sanfeliu <rasta@arklinux.org>
Updated and maintained by David Tio <deux at arklinux dot org>
Updated HTML Source 02/26/05 by Luke Hebert <aeroclown at arklinux dot org>
Updated to fix technical errors and typos, and to fit into the docs.arklinux.org system 2005/03/30; Updated to mention the V* tools 2006/06/26 by Bernhard Rosenkraenzer <bero at arklinux dot org>
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.
[edit] Introduction
This document tries to be a helpful guide for building RPMs for Ark Linux, it does not pretend to be an extensive documentation about RPM system. I will try to guide you through the process of building an RPM package for Ark Linux, just because I think the best way to learn this is with an example.
The first thing we need to know is our work environment, here there are two choices, one is to use the root user for building, and the other one is to use a regular user. I recommend the second one because it has limited permissions, and this way you will be sure the system wont be messed up if something goes wrong. So, from now on we will be using "arklinux" user. The build environment is placed under /usr/src/ark/, with the following structure:
BUILD RPMS SOURCES SPECS SRPMS
Where BUILD is the place where our apps are built, note that it isn't automatically cleared after a build. RPMS and SRPMS are where our final packages go, it will depend if we build binaries (ix86.rpm), sources (src.rpm), or both. SOURCES contains all sources of a package, including patches, icons, etc. All inside a src.rpm goes here, except the spec file, which goes to SPECS directory. Ok, now lets start with our example application, I've chosen kimdaba for this, not for anything special but because its spec file has some interesting things, such as a menu entry, and custom icons.
[edit] Getting started
The first thing to do -- if this is our first package -- is to install the packages we need in order to build RPMs. This is done by either installing the Ark Development Suite CD, or installing the following packages through "Install Software" or, on the command line, apt-get:
rpm-build patch
The next thing we need to do is to get the sources of our package, which are usually contained in a tar file. So, once we've downloaded them (in this case, kimdaba-0.1.tar.gz) we should move it to /usr/src/ark/SOURCES. What I usually do at this point, is to untar the sources, and compile it, adding "--prefix=$HOME/temp/" to the configure, this way, it will install everything under that directory, and well see which files we should take care of. Another way to achieve this is to start directly with the spec file, without caring at all about the files section. Once were done, we should run "rpmbuild -ba file.spec"
[edit] The spec file
The spec file is the heart of every build, it contains instructions and information about how the final rpm will be made. It is usually called as the name of the package (without versions) with ".spec" extension. So, in this case, kimdaba.spec. You can generate a template that will make the rest of the packaging process faster by using the vs, vl, vp, vkm and vj tools included in the rpm-build package. Please refer to the respective man pages (by going to man:/vs in Konqueror) and the section "Tools to make your life easier" at the end of this tutorial for details. Let's take a look at the first part of the file:
Name: kimdaba Version: 0.01 Release: 3ark Source: http://ktown.kde.org/kimdaba/download/%name-%version.tar.gz Source1: http://ktown.kde.org/kimdaba/download/%name-%version-icons.tar.gz Summary: K Image Database URL: http://ktown.kde.org/kimdaba/ License: GPL Group: Applications/Graphics BuildRoot: %_tmppath/%name-root
%description An image database tool.
This is the very first part of almost every package, it contains information about the package. The first two tags (Name and Version) are pretty obvious, package name and version of the application. The third one, Release refers to distributions own releases in relation to the actual version, that means, for every modification (rebuild) of the package, the release should be increased by one. That is, if those modifications (rebuilds) are made to the same version -- because when a new version starts, the release goes to 1 again. The Source tag is used to specify every source of the application, in this case, the tar file where the sources are. Often there are more than one source, like in this case, the second one refers to our custom icons tar file, but well talk about it later. There is an important macro used here, %version which holds the value of the version tag above, it is useful to avoid hardcoded values because you'll have to change the version number in only one place when updating to a newer version. The same applies for %name. Summary holds a brief explanation of what the package is about, and should be no longer than 1 line of 80 characters. URL should contain the URL where the application can be found, or the official URL for the application. License is also clear, the license under which the application is released. The Group tag is used to specify how the package should be grouped with other packages, for a list of available groups, see the file /usr/share/doc/rpm-*/GROUPS. BuildRoot is fine as it is, it sets the temporary directory where the package will be built. The %description section should contain a longer explanation of what the package is/does. Now I'll describe the %prep section, which prepares the software for building. It looks like this:
%prep %setup -n %name-%version
In this section, we usually use a macro called %setup, it takes care of removing older builds and uncompressing the sources. By default, it expects the sources to be in a directory called the same as the %name-%version variables (explained above), there's no need to use -n here, because they are under a directory called "kimdaba-0.01" -- we just use it to demonstrate what to do if the directory is not called %name-%version.
%build %configure make %?_smp_mflags
The %build script takes care of changing to the sources directory and actually start the build process. %configure executes the configuration script in the sources tree, followed by the make. %?_smp_mflags is a macro that tells make how many CPUs can be used on a SMP (multiprocessor) machine.
%install rm -rf $RPM_BUILD_ROOT make install DESTDIR="$RPM_BUILD_ROOT"
This is the final part of the building process, the %install script takes care of moving all the necessary files to our build root for packaging them. That's why we make sure the build directory is empty (rm -rf $RPM_BUILD_ROOT). After that, make install is used to install the files to their target locations. The DESTDIR="$RPM_BUILD_ROOT" parameter tells "make install" to put the files in the temporary directory created for package creation rather than cluttering your system. Some broken Makefiles don't support the DESTDIR parameter - for those, you have to either patch them, or try using "%makeinstall" instead. Here is where we can put the final files in place to be packaged, for example, external icons, or our personalized desktop menu entry. Well talk later about those.
%files
%defattr(-,root,root)
%doc README
%{_datadir}/apps/kimdaba/*
%{_datadir}/applnk/*
%{_datadir}/icons/*
%{_bindir}/*
Once everything is in place, we must tell rpm which files we want to be packaged (sometimes we may want to exclude some files) that is the function of the %files list. We should list all the files we want to be packaged here, by default it is recursive, so we can include for example "/usr/share" and it will take all files in /usr/share/ as well. Here are some commonly used macros:
| Macro | Expands to |
| %_datadir | /usr/share |
| %_mandir | /usr/share/man |
| %_sysconfdir | /etc |
| %_includedir | /usr/include |
| %_libdir | /usr/lib |
| %_bindir | /usr/bin |
| %_sbindir | /usr/sbin |
The %doc directive sets the given filenames as documentation files, and places them under an already specified directory (specified in the rpmrc file), which, in our case, is "/usr/share/doc/%name-%version/". %defattr sets the default permissions and owner to the files. The format is %defattr(mode, owner, group). The dash (-) does not modify that value, taking the default values. In this case, we set root as a file owner and group for all our files, and we don't modify their permissions (because of the dash).
%clean rm -rf $RPM_BUILD_ROOT
%changelog * Mon Sep 1 2003 Joan Sanfeliu <rasta@arklinux.org> 0.01-1ark - First AL package
These are the final touches, the %clean script is used to clean our build root, so we keep our file system clean. The %changelog is where we note our modifications in the current build, so others can follow what has been done. It has always the same format:
- day month day-num year Name Surname <email@address> version-release
So we can determine who did the last build, and when and why it was done. It is important to add the release number at the end, because one version can be built several times, which results in several releases.
[edit] Adding custom icons
Ok, now lets look at the top of our spec file, there is a second source called %{name}-%{version}-icons.tar.gz this is the file where our icons are. We have to make this file ourselves, because it is a custom icons file. What i usually do, is to make exactly the same directory tree as in our file system, and put the icons in there, and then package it into a tar.gz file, Why this? Because this way, once we decompress the tar.gz, well have the directory tree already created, and well just need to move the main directory into place. Lets look at our example:
kimdaba-0.01-icons.tar.gz kimdaba-0.01-icons/ kimdaba-0.01-icons/usr/ kimdaba-0.01-icons/usr/share/ kimdaba-0.01-icons/usr/share/icons/ kimdaba-0.01-icons/usr/share/icons/hicolor/ kimdaba-0.01-icons/usr/share/icons/hicolor/16x16/ kimdaba-0.01-icons/usr/share/icons/hicolor/16x16/apps/ kimdaba-0.01-icons/usr/share/icons/hicolor/16x16/apps/kimdaba.png kimdaba-0.01-icons/usr/share/icons/hicolor/32x32/ kimdaba-0.01-icons/usr/share/icons/hicolor/32x32/apps/ kimdaba-0.01-icons/usr/share/icons/hicolor/32x32/apps/kimdaba.png kimdaba-0.01-icons/usr/share/icons/hicolor/48x48/ kimdaba-0.01-icons/usr/share/icons/hicolor/48x48/apps/ kimdaba-0.01-icons/usr/share/icons/hicolor/48x48/apps/kimdaba.png kimdaba-0.01-icons/usr/share/icons/hicolor/64x64/ kimdaba-0.01-icons/usr/share/icons/hicolor/64x64/apps/ kimdaba-0.01-icons/usr/share/icons/hicolor/64x64/apps/kimdaba.png
Here we can see the full path in our tarred file (/usr/share/icons/hicolor/), so once we decompress it, we just have to put the block of files in place. Now, lets look at the spec file, the icons stuff is usually made after the compilation, and after the %install script:
# Install icons
( cd $RPM_BUILD_ROOT
tar xvf %{SOURCE1}
cp -a %{name}-%{version}-icons/* .
rm -rf %{name}-%{version}-icons/
)
Here we untar the icons, and move them to our current directory ($RPM_BUILD_ROOT), here is where the trick of packaging the whole directory structure comes into scene. Otherwise we should have to move all icons by hand.
[edit] Menu entry
Now we only need to create a desktop menu entry for our application, it is done by creating a special file called app-name.desktop (kimdaba.desktop) which contains some information. The menu entry should be created in the %install script as well. Note that most current applications already provide a menu entry by themselves, so you can skip this step for most applications.
# Create menu entry
mkdir -p $RPM_BUILD_ROOT%{_datadir}/applnk/Graphics
cat > $RPM_BUILD_ROOT%{_datadir}/applnk/Graphics/kimdaba.desktop <<EOF
[Desktop Entry]
Name=Kimdaba
GenericName=K Image Database
Comment=Manage your pictures easily
Exec=kimdaba %f
Icon=kimdaba.png
Terminal=false
Encoding=UTF-8
Type=Application
EOF
chmod 644 $RPM_BUILD_ROOT%{_datadir}/applnk/Graphics/kimdaba.desktop
The first thing we do is to make the directory, where the file will be placed, in our build tree. We use cat to create it here inside the spec file, we also could add it as a separate source, but i personally prefer it to be in the spec file. As you can see, it contains some information, about the name, the icon, etc. The Name is what will be displayed in our menu, and the GenericName is what will be under brackets just after the name. We finally set its permissions to 644, and that's it. If you speak several languages, you may want to add internationalized entries to the desktop file -- for example, to support German you'd put
GenericName[de]=KDE Bilderdatenbank Comment[de]=Einfache Bildverwaltung
in addition to the entries above.
[edit] Building our package
Once we have finished our spec file, we want to build it, for it we will use the "rpmbuild" command:
for building both the SRPM and the RPM rpmbuild -ba file.spec
for building just the binary RPM rpmbuild -bb file.spec
The final results will be placed in /usr/src/ark/SRPMS and /usr/src/ark/RPMS for the source.rpm and the binary rpm respectively.
[edit] Tools to make your life easier
Ark Linux includes tools that make your life as a packager easier, by providing you with templates for a spec file for the package you want to build.
Meant to be useful for any system, these tools default to using vi to edit files -- if you aren't familiar with vi (it has a very steep learning curve - don't use it unless you know its basics or you're very patient), you want to set the EDITOR shell variable to your editor of choice. Since some other tools use the EDITOR variable as well, it is a good idea to make that setting globally: Edit the file ".profile" in your home directory, and add the line
export EDITOR=kwrite
to the end of the file (if you wish to use another editor, replace kwrite with whatever your favorite editor is called).
On to the tools:
[edit] vs
vs ("vi specfile") is what you typically want to use -- it creates a template .spec file for your application, and you just have to fill in the blanks. (To look up the meaning of the entries left blank, see the earlier chapters in this tutorial.)
To use vs, simply run "vs appname" -- that will generate /usr/src/ark/SPECS/appname.spec, containing a template spec file. Fill in the blanks, save, and you're ready to go.
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on vs by pointing konqueror at man:/vs.
[edit] vl
vl ("vi library-specfile") is what you want to use to package a library -- it does the same thing as vs, but the template spec file already includes the instructions needed to split out the -devel and -static packages, to keep development tools off an end user's system to save space.
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on vl by pointing konqueror at man:/vl.
[edit] vkm
vkm ("vi kernel-module-specfile") is a special version of vs meant for packaging kernel modules. Its build template contains instructions to make sure it gets built against all kernels (i586, i686, pentium3, pentium4, athlon, all for UP and SMP configurations).
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on vkm by pointing konqueror at man:/vkm.
[edit] vp
vp ("vi perl-specfile") is a special version of vs meant for packaging perl modules. It uses perl's Makefile.PL system rather than autoconf/configure in the build script template.
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on vp by pointing konqueror at man:/vp.
[edit] vj
vj ("vi java-specfile") is a special version of vs meant for packaging Java libraries - it uses ant for the build process and automatically generates pre-built binaries for gcj.
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on vj by pointing konqueror at man:/vj.
[edit] e and gendiff
e and gendiff are useful tools if you need to make changes to the code, e.g. to get it to build with a current compiler. e invokes your editor and creates a backup file (default: filename.ark~) with the original content, gendiff creates a patch file showing the differences between the files before and after being edited with e.
Example usage, assuming you want to package SomeApp, and it fails to build in test.cpp:
cd /usr/src/ark/BUILD/SomeApp e test.cpp (Make whatever changes you need to get it to build, save) cd /usr/src/ark/BUILD gendiff SomeApp .ark~ >../SOURCES/SomeApp-1.0-compile.patch
Then apply SomeApp-1.0-compile.patch from the spec file, and you're ready to go.
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on e and gendiff by pointing konqueror at man:/e and/or man:/gendiff.
[edit] scmtar
scmtar packages up a source tree checked out from a Source Control Management tool, such as Subversion, CVS, git, or mercurial. It removes the SCM specific files and creates a tar.lz file with a unique version number, based on the revision ID for Subversion and Mercurial, or the current date for CVS and git.
If you're using Ark Linux and Konqueror (and have already installed the rpm-build package), you can find more details on scmtar by pointing konqueror at man:/scmtar.
Back to Main Page
