GNOME/Packaging

From openSUSE

To make creating new packages and maintaining old ones easier, the GNOME team is working on developing a set of packaging policies.

Our packaging policies are a superset of openSUSE's general packaging policies and and openSUSE's general packaging guidelines and conventions. Do read those pages and follow their advice.

What follows are some GNOME-specific guidelines.

What (almost) all GNOME packages should have

gconf scriptlets

Many GNOME packages install gconf schemas. In the past, they were tedious to package. Now, however, we have some RPM macros which automate much of the process. This page has the details on how to incorporate those scripts into your package.

Patch naming and commenting

Since many GNOME packages are heavily patched, we're working on conventions to name patches and to annotate them. GNOME/Patches has more information.

A -lang subpackage

All translated packages -- that is, packages containing programs that can run in more than one language or have documentation in more than one language -- should have a -lang subpackage.

To do this, add the %lang_package macro before %prep:

...
%lang_package

%prep
...

In the install section:

%find_lang %{name}

The -lang subpackage gets its own %files entry:

%files lang -f %{name}.lang

See the documentation on %find_lang for more information.

Updated .desktop files (only official OpenSUSE packages)

In order to get sortable and translatable menus, among other things, it's important to use the %suse_update_desktop_file macro in the %install section and add update-desktop-files in BuildRequires section. This will automatically include your desktop translation to the official OpenSUSE desktop translation project.

WARNING: Don't use this macro for packages not included in the official openSUSE distribution! It will remove existing translations.

The preferred way to call %suse_update_desktop_file is without any arguments except desktop file name.

%suse_update_desktop_file %{name}

Attempt to push .desktop file modifications upstream, but note that in particular cases it might be useful to make openSUSE-specific changes.

Here's an example from tomboy.spec:

%suse_update_desktop_file %{name} GNOME Utility TextEditor

And here's an example from evolution.spec:

%suse_update_desktop_file -G "Mail and Calendar" evolution Core-Office
%suse_update_desktop_file -G "Mail" -D "evolution-2.12/evolution-2.12.xml?usage-mail" evolution-email
%suse_update_desktop_file -G "Address Book" -D "evolution-2.12/evolution-2.12.xml?usage-contact" evolution-addressbook
%suse_update_desktop_file -G "Schedule Manager" -D "evolution-2.12/evolution-2.12.xml?usage-calendar" evolution-calendar
%suse_update_desktop_file -G "Task List" -D "evolution-2.12/evolution-2.12.xml?usage-calendar-todo" evolution-tasklist

For more information about %suse_update_desktop_file, see its documentation.

A .changes file

Keep the %changelog section of your spec empty (but do declare that section), and use a .changes file instead. The format of .changes files is documented.

Tools and tricks

osc plugins

We're working on developing a set of plugins for osc to ease maintenance of GNOME packages. More information about the plugins is available on the GNOME/OSC_plugins page.

The following plugins are especially useful when creating new packages.

The createspec plugin

This plugin creates a spec file in your current working directory that conforms to our standard. The automatically-generated spec files include the gconf scriptlets, lang subpackages, debuginfo packages, and other useful features. To use it, just run:

osc createspec package --standard=gnome

This will create a package.spec file containing all the above mentioned features.

The speclint plugin

This plugin inspects an already-existing spec file looking for common problems.

Quilt

quilt is a tool to manage large sets of patches by keeping track of the changes each patch makes. Patches can be applied, un-applied, refreshed, etc. It is available as part of the distribution; you can install the quilt package. Once installed, the basic workflow goes as follows:

First of all, you need to get the package sources into a directory and set it up:

cd package
quilt setup package.spec

This last command will create a directory (package-1.0) containing the upstream sources (only) of the package. Next step is applying the already existing patches to the upstream sources. This is an optional step, usually necessary only if you are going to modify an already existing patch:

cd package-1.0
quilt push -a

When the sources, patched or not, are ready, next step depends on what you want to do. To add new patches:

quilt new package-mypatch.patch              # this creates a new patch
quilt add Makefile                           # specify that Makefile is going to be modified in the new patch
vim Makefile                                 # Add your changes to the file here

Once you are happy with the changes, the last step is refreshing the package sources and adding the new patch to the spec file:

quilt refresh -p0
cd ../..
vim package.spec

Cheat Sheet

Because openSUSE's packaging documentation can be overwhelming, we are working on a much-distilled version. Or, if you will, a cheat sheet.

Macros we use

Macros for building

These macros are typically used in the %build section of your spec.

The %configure macro runs your package's autoconf-generated configure script with commonly-known arguments to set install locations. If necessary, you can pass it additional arguments, to augment or override the defaults.

The %__make macro is just an alias for /usr/bin/make. Not crucial, but it is good form. To enable parallel builds, you can use %__make %{?jobs:-j%jobs}.

Macros for installing

These macros are typically used in the %install section of your spec.

The %makeinstall macro is equivalent to "make install DESTDIR=$RPM_BUILD_ROOT".

The %find_lang macro finds all of the installed files providing translations and creates a file containing a list of them all.

When the translation files have the same name as your package, usage is simple:

%find_lang %{name}

And you can use %{name}.lang later in your spec.

Sometimes the translation files are named differently. The following comes from the gnome-build package:

%find_lang gbf-1

In this case, you can refer to gbf-1.lang later in your spec.

Please keep in mind that %find_lang collects not only locale translations, but also translated documentation. Also remember that when you're using %find_lang, you don't need to explicitly package %{_datadir}/gnome/help, since the .lang file includes everything it needs to.

The %find_gconf_schemas macro is discussed above;

The %fdupes macro finds duplicate files in your install root and replaces all but one of each dupe with symlinks to the first.

%fdupes $RPM_BUILD_ROOT

WARNING: Be careful when using the %fdupes macro. Due to limitations in RPM, it isn't possible to install packages that have symlinks across partitions. In that case, try %fdupes $RPM_BUILD_ROOT/usr/bin, %fdupes $RPM_BUILD_ROOT/usr/lib, etc

Older Distributions

Packages only needed in specific versions

The %suse_version macro corresponds to the version of openSUSE we're building for. There are no dots, and there's always a trailing digit. For example, %suse_version for openSUSE 10.3 is 1030. For 10.2 it was 1020. Currently (as of 24 October 2007), %suse_version in Factory is 1031. When openSUSE 11.0 is released, it will be 1100.

Pull in packages that provide rpm macros that enable -lang subpackages, gconf scriptlets, etc. Since they're included "out of the box" in openSUSE 10.3 and later, we only explicitly require them on openSUSE 10.2 and earlier.

%if %suse_version < 1030
BuildRequires: extra-rpm-macros gconf2-rpm-macros 
%endif

GNOME prefixes

As of openSUSE 10.3, we install GNOME under the /usr hierarchy. In 10.2 and older, however, it was installed under /opt/gnome. Therefore, it is often wise to include the following:

%if %suse_version < 1030
%define _prefix /opt/gnome
%define _sysconfdir /etc/%_prefix
%endif

Since %{_bindir}, %{_libdir}, etc, are defined with respect to %_prefix, it is usually sufficient to simply define %_prefix and %_sysconfdir.

RPM Conveniences

AutoReqProv

Be sure your spec file has AutoReqProv: yes in its preamble. When set, requirements on system libraries don't need to be explicitly listed. Note, however, that this works best with programs written in C and C++; programs written in interpreted languages, such as Python and Ruby, still need their dependencies listed explicitly.

Splitting/Merging/Renaming Packages

When splitting a package up into pieces, or merging two pieces of the package into one or renaming a package, special care should be taken with the Obsoletes/Provides made in the package: http://en.opensuse.org/Upgrade_Dependencies

Simple yet complete GNOME packages

The GNOME/Packaging/Simple_program_package page shows and explains in detail a simple yet complete spec file for a GNOME program.

The GNOME/Packaging/Simple_library_package page shows and explains a simple yet complete spec file for a GNOME library.