GNOME/Packaging/Simple library package

From openSUSE

This is a draft. Captain Magnus Boman is going to read it and provide feedback on how it could be improved.

This page contains a very simple RPM spec file for a GNOME library, libgtkhtml, and explains each part of it in detail.

Preamble

# norootforbuild

Build requirements

Here we list build requirements. This list should contain the fewest necessary packages necessary to build your library. Notice that we don't explicitly require glib2-devel here, even though libgtkhtml makes use of it. It isn't necessary: libgnomecanvas-devel requires gtk2-devel which in turn requires glib2-devel.

BuildRequires:  gail-devel libgnomecanvas-devel libxml2-devel update-desktop-files

Package metadata

Here we list various package metadata.

Name:           libgtkhtml
License:        GPL v2 or later, LGPL v2 or later
Group:          Development/Libraries/GNOME
Version:        2.11.1
Release:        1
Summary:        A Library for HTML Support in GTK2.0
Url:            http://www.gnome.org

Sources and Patches

Source:         ftp://ftp.gnome.org/pub/GNOME/sources/libgtkhtml/2.11/%{name}-%{version}.tar.bz2
Patch:          libgtkhtml.patch

Misc

The BuildRoot tag specifies where the "fake" installation happens. This is different from the chroot where build occur. So, if the chroot is /builds/10.3, BuildRoot will expand to /builds/10.3/var/tmp/gnome-hello-2.03-build. Its contents will be made up of the files to be included in the package, such as /builds/10.2/var/tmp/gnome-hello-2.03-build/usr/bin/gnome-hello.

BuildRoot:      %{_tmppath}/%{name}-%{version}-build

RPM can examine shared libraries to determine what libraries they depend on, and as such, it usually isn't necessary to list many requirements explicitly. Autoreqprov: on enables this functionality.

AutoReqProv:    on

A free-form description of the library.

%description
Libgtkhtml provides extensions for GTK to handle the HTML format. It is
widely used by applications for the GNOME 2.x Desktop.

A -devel subpackage

Most libraries are shipped in two packages. The "base" package (in this case, libgtkhtml) is necessary for programs that depend on the library to run. The -devel subpackage is used by programmers who want to write programs that utilize the library.

-devel subpackage metadata

Here is how the -devel subpackage is declared. Notice that it doesn't contain information already present in the preamble. Notice that the Summary: tag is terrible!

%package devel
Summary:        Include Files and Libraries mandatory for Development.
Group:          Development/Libraries/GNOME

A -devel subpackage isn't very useful without its corresponding "base" package!

Requires:       %{name} = %{version}

-devel subpackages often require yet other -devel subpackages. We list them here.

Requires:       gtk2-devel libxml2-devel gail-devel

A freeform description of the -devel subpackage. It's a terrible description.

%description devel
This package contains all necessary include files and libraries needed
to develop applications that require these.

Prepare the source

Prepare the source for compilation.

%prep

The %setup line is important; it is what extracts the Source lines listed above.

%setup -q 

Apply a patch.

%patch

Build the code

%build

When patches touch auto* files, we need to run autoreconf.

autoreconf -i -f

It's possible to override or supplement the default CFLAGS.

export CFLAGS="$RPM_OPT_FLAGS -fno-strict-aliasing"

%configure runs "./configure" with a reasonable set of default arguments, including install locations. Subsequent arguments can supplement or override the defaults.

%configure \
    --disable-static

Build the the library. %__make is just an alias for "make". %{?jobs:-j%jobs} causes make to run in parallel where possible and when specified.

%__make %{?jobs:-j%jobs}

Install the results

Once the program has been compiled, it's necessary to install it. This doesn't install the package or any files on your working system. Instead, it puts files where they would go if you ran "make install" directly, but under a temporary directory. The temporary directory that's used is defined in BuildRoot: tag in your spec's preamble.

%install

This is an alias for "make install DESTDIR=$RPM_BUILD_ROOT", which works for nearly every program that is built using autotools.

%makeinstall

Scripts that are run upon installation and uninstallation

Upon installation and uninstallation of many libraries, it's necessary to run commands. They usually update databases already installed on your system, etc. /sbin/ldconfig is necessary for virtually every shared library. The %post command is run after installing a package. The %postun command is run after uninstalling a package.

%post -p /sbin/ldconfig

%postun -p /sbin/ldconfig

Clean up working directories

Remove the BuildRoot: specified in the preamble. This is surprisingly important; without it, it is possible to have many mysterious errors. On the other hand, it is sometimes convenient to poke around after a package fails to build. So feel free to comment out this section when working on a package, but remove the comments before distributing the package.

%clean 
rm -rf $RPM_BUILD_ROOT

List the files in the package

Base package filelist

Here we list all the files and directories that the base package includes.

%files 

Make sure that all of the package's files are owned by root.

%defattr(-, root, root)

Automagically install and list documentation files. These files will end up in /usr/share/doc/packages/libgtkhtml.

%doc AUTHORS COPYING.LIB ChangeLog NEWS README TODO docs/IDEAS

Include shared library files. This is the "meat" of the file list.

%{_libdir}/*.so.*

-devel subpackage filelist

We list files in the -devel subpackage here.

%files devel
%defattr(-, root, root)

Automatically list all files under %{_includedir}/gtkhtml-2.0. These files typically end in .h.

%{_includedir}/gtkhtml-2.0

List files files necessary for linking.

%{_libdir}/*.so
%{_libdir}/*.*a

List files used by pkg-config.

%{_libdir}/pkgconfig/*.pc

Changelog

You can fill this in by hand, but it's easier to maintain an external .changes file, whose contents will be included in the %changelog section automatically by the Build Service.

One advantage to using an external .changes file is that it's safe to do global find-and-replace operations in the spec file that you're editing -- you won't be "rewriting history".

%changelog

The format of .changes files is described here.

See also

• There is a document describing a simple spec file for a program, which may be of interest.