Packaging/Guidelines

From openSUSE

Packaging Guidelines

It is the reviewer's responsibility to point out specific problems with a package and a packager's responsibility to deal with those issues. The reviewer and packager work together to determine the severity of the issues (whether they block a package or can be worked on after the package is in the repository.) The Packaging Guidelines are a collection of common issues and the severity that should be placed on them. While these guidelines should not be ignored, they should also not be blindly followed. If you think that your package should be exempt from part of the Guidelines, please bring the issue to the opensuse-packaging mailing list.

Please remember that any package that you submit must also conform to the Review Guidelines .

Naming

You should go through the Packaging/Naming_Guidelines to ensure that your package is named appropriately.

Version and Release

Documentation covering the proper way to use the Version and Release fields can be found here: Packaging/Naming_Guidelines#Package_Version

Legal

There are various legal concerns to consider when packaging for openSUSE.

Licensing

You should review Packaging/Licensing_Guidelines to ensure that your package is licensed appropriately.

No inclusion of pre-built binaries or libraries

All binaries or libraries included with openSUSE packages must have been built from source code included in the source package. This is a requirement for the following reasons:

• Security: Pre-packaged binaries and libraries not built from source could include anything, malicious, dangerous, or just broken. Also, these are functionally impossible to patch.
• Compiler Flags: Pre-packaged binaries and libraries not built from source probably don't have the standard openSUSE compiler flags for security and optimization.

If you are in doubt as to whether something is considered a binary or library, here is some helpful criteria:

• Is it executable? If so, it is probably a binary.
• Does it contain a .so, ,so.#, or .so.#.#.# extension? If so, it is probably a library.
• If in doubt, ask your reviewer. If the reviewer is not sure, they should ask the Fedora Packaging Committee.

* Wed Jun 14 2003 Joe Packager <joe at gmail.com> - 1.0-2
- Added README file (#42).

* Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> - 0.6-4
- And fix the link syntax.

* Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com> 0.6-4
- And fix the link syntax.

* Fri Jun 23 2006 Jesse Keating <jkeating@redhat.com>
- 0.6-4
- And fix the link syntax.

Tags

• The Packager tag should not be used in spec files. The identities of the packagers are evident from the changelog entries. By not using the Packager tag, you also avoid seeing bad binaries rebuilt by someone else with your name in the header. See also the Maximum RPM definition of the Packager tag at www.rpm.org . If you need to include information about the packager in the rpms you built, use %packager in your ~/.rpmmacros instead.
• The Vendor tag should not be used. It is set automatically by the build system.
• The Copyright tag is deprecated. Use the License tag instead, as detailed in Packaging/Licensing_Guidelines . Contact the upstream author if there is any doubt about what license the software is distributed under.
• The Summary tag value should not end in a period. If this bothers you from a grammatical point of view, sit down, take a deep breath, and get over it.
• Usually, the PreReq tag should be replaced by plain Requires. For more info, see Maximum RPM snapshot's fine grained dependencies chapter.
• The Source tag documents where to find the upstream sources for the rpm. In most cases this should be a complete URL to the upstream tarball. For special cases, please see the Packaging/Source_URL Guidelines

%(mktemp -ud %{_tmppath}/%{name}-%{version}-%{release}-XXXXXX)
%{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n)
%{_tmppath}/%{name}-%{version}-%{release}-root

At one point, the second was a mandatory value, but it is now left to the packager to decide. If unsure, simply pick the first.

Prepping BuildRoot For %install

Packages in openSUSE CAN NOT have rm -rf %{buildroot} or rm -rf $RPM_BUILD_ROOT at the beginning of an %install section.

%clean

Each package must have a %clean section, which contains rm -rf %{buildroot} (or $RPM_BUILD_ROOT).

In the past, some packages checked that %{buildroot} was not / before deleting it. This is not necessary in openSUSE anymore.

Requires

RPM has very good capabilities of automatically finding dependencies for libraries and eg. Perl modules. In short, don't reinvent the wheel, but just let rpm do its job. There is usually no need to explicitly list eg. Requires: libqt4 when the dependency has already been picked up by rpm in the form of depending on libraries in the libqt4 package.

Build requirements are different. There's no automatic dependency find procedure for them, which means that you must explicitly list stuff that the package requires to build successfully. Typically, some -devel packages are listed there. Refer to the BuildRequires section.

Sometimes we know that a package requires eg. gtk2-devel 2.0 or newer to build (and thus gtk+ 2.0 or newer to run, but that's handled automatically). There are two things to consider here:

First, if the lowest possible requirement is so old that nobody has a version older than that installed on any target distribution release, there's no need to include the version in the dependency at all. In that case we know the available software is new enough. For example, the version in gtk2-devel 2.0 dependency above is unnecessary for all openSUSE distributions since (at least) release 10.2. As a rule of thumb, if the version is not required, don't add it just for fun.

Typically, the requirements for -devel packages need yet another look. They're not usually picked up automatically by rpm. If the foo-devel package has a foo-config script, you can try doing a foo-config --libs and foo-config --cflags to get strong hints what packages should be marked as foo's requirements. The newer approach would be to try pkg-config foo instead of foo-config. Examples:

$ gtk-config --cflags
-I/usr/include/gtk-1.2 -I/usr/include/glib-1.2 -I/usr/lib/glib/include -I/usr/X11R6/include
$ gtk-config --libs
-L/usr/lib -L/usr/X11R6/lib -lgtk -lgdk -rdynamic -lgmodule -lglib -ldl -lXi -lXext -lX11 -lm

$ pkg-config gtk+-2.0 --cflags
-I/usr/include/gtk-2.0 -I/usr/lib64/gtk-2.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib64/glib-2.0/include -I/usr/include/pixman-1 -I/usr/include/freetype2 -I/usr/include/libpng12

$ pkg-config gtk+-2.0 --libs
-lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lgio-2.0 -lpangoft2-1.0 -lgdk_pixbuf-2.0 -lpangocairo-1.0 -lcairo -lpango-1.0 -lfreetype -lz -lfontconfig -lgobject-2.0 -lgmodule-2.0 -lglib-2.0

This means that gtk-devel should contain

Requires: glib-devel xorg-x11-devel

and gtk2-devel should contain

Requires: atk-devel cairo-devel glibc-devel glib2-devel pango-devel xorg-x11-devel

Rpm gives you the ability to depend on files instead of packages. Whenever possible you should avoid file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin. Using file dependencies outside of those directories requires yum (and other depsolvers using the repomd format) to download and parse a large xml file looking for the dependency. Helping the depsolvers avoid this processing by depending on the package instead of the file saves our end users a lot of time. There are times when other technical considerations outweigh these considerations. One specific example is packages installing into %{_libdir}/mozilla/plugins. In this case, mandating a specific browser in your package just to own this directory could drag in a large amount of needless packages. Requiring the directory to resolve the dependency is the better choice.

BuildRequires

In package development and testing, please verify that your package is not missing any necessary build dependencies. Having proper build requirements saves the time of all developers and testers as well as autobuild systems because they will not need to search for missing build requirements manually. It is also a safety feature that prevents builds with that would not otherwise fail, but would be missing crucial features. For example, a graphical application may exclude PNG support after its configure script detects that libpng is not installed.

Before adding BuildRequires to any package, please be comfortable with Requires .

There are two suggested ways of detecting missing BuildRequires. rpmdev-rmdevelrpms and mock. The first one is designed to remove all developer-related packages from your system. If the build fails or is missing certain features due to missing build dependencies, then the missing dependency needs to be found and added. Check the rpmdev-rmdevelrpms section to find out more.
mock is another good way to check build dependencies. Rather than remove all developer packages, it tries to build your package in a chroot. It makes no changes to your normal, daily environment and ensures that your package will build fine. However, mock may need a good internet connection to download all required packages. MockTricks page contains more information. Another mock-like tool, mach is also available in the Fedora repository.

[root@build-fc1 /] # rpmdev-rmdevelrpms
Found 52 devel packages:
guile-devel-1.6.4-8.2
bison-1.875-5
m4-1.4.1-14
flex-2.5.4a-30
openssl-devel-0.9.7a-23
automake-1.7.8-1
fontconfig-devel-2.2.1-6.1
XFree86-devel-4.3.0-42
tcl-devel-8.3.5-93
SDL_image-devel-1.2.3-3
SDL_ttf-devel-2.0.6-0.fdr.3.1
pth-devel-2.0.0-0.fdr.1.1
libIDL-devel-0.8.2-1
atk-devel-1.4.0-1
gtk2-devel-2.2.4-5.1
libmng-devel-1.0.4-4
glib-devel-1.2.10-11
gtk+-devel-1.2.10-28.1
audiofile-devel-0.2.3-7
compface-1.4-0.fdr.3.1
esound-devel-0.2.31-1
libungif-devel-4.1.0-16
gnome-libs-devel-1.4.1.2.90-35
openldap-devel-2.1.22-8
aspell-devel-0.50.3-16
gpgme03-devel-0.3.16-0.fdr.2.1
freeglut-devel-1.3-1.20020125.3
e2fsprogs-devel-1.34-1
db4-devel-4.1.25-14
krb5-devel-1.3.1-6
autoconf-2.57-3
libtool-1.5-8
gdbm-devel-1.8.0-21
freetype-devel-2.1.4-5
pkgconfig-0.14.0-6
ncurses-devel-5.3-9
tk-devel-8.3.5-93
SDL-devel-1.2.5-9
SDL_mixer-devel-1.2.4-9
zlib-devel-1.2.0.7-2
libgpg-error-devel-0.6-0.fr.3.1
glib2-devel-2.2.3-1.1
pango-devel-1.2.5-1.1
libjpeg-devel-6b-29
libpng-devel-1.2.2-17
ORBit-devel-0.5.17-10.3
clamav-devel-0.65-0.fdr.4.1
cyrus-sasl-devel-2.1.15-6
libtiff-devel-3.5.7-14
imlib-devel-1.9.13-14
gdk-pixbuf-devel-0.22.0-3.0
pilot-link-devel-0.11.8-1
Remove them? [y/N]  y[
]Removing.................................................................................................
................................................................Done.

bash
bzip2
coreutils
cpio
diffutils
fedora-release
findutils
gawk
gcc
gcc-c++
grep
gzip
info
make
patch
redhat-rpm-config
rpm-build
sed
shadow-utils
tar
unzip
util-linux-ng
which

Summary and description

The summary should be a short and concise description of the package. The description expands upon this. Do not include installation instructions in the description; it is not a manual. If the package requires some manual configuration or there are other important instructions to the user, refer the user to the documentation in the package. Add a README.SUSE, or similar, if you feel this is necessary. Also, please make sure that there are no lines in the description longer than 80 characters.

Please put personal preferences aside and use American English spelling in the summary and description. Packages can contain additional translated summary/description for supported Non-English languages, if available.

Trademarks in Summary or Description

Packagers should be careful how they use trademarks in Summary or Description. There are a few rules to follow:

• Never use "(TM)" or "(R)" (or the unicode equivalents, ™/®). It is incredibly complicated to use these properly, so it is actually safer for us to not use them at all.
• Use trademarks in a way that is not ambiguous. Avoid phrasing like "similar to" or "like". Some examples:

• BAD: It is similar to Adobe Photoshop.
• GOOD: It supports Adobe Photoshop PSD files, ...

• BAD: A Linux version of Microsoft Office
• GOOD: A word-processor with support for Microsoft Office DOC files

If you're not sure, ask yourself, is there any chance someone may get confused and think that this package is the trademarked item? When in doubt, try to leave the trademark out.

Encoding

Unless you need to use characters outside the ASCII repertoire , you will not need to be concerned about the encoding of the spec file. If you do need non-ASCII characters, save your spec files as UTF-8. If you're in doubt as to what characters are ASCII, please refer to this chart .

Non-ASCII Filenames

Similarly, filenames that contain non-ASCII characters must be encoded as UTF-8. Since there's no way to note which encoding the filename is in, using the same encoding for all filenames is the best way to ensure users can read the filenames properly. If upstream ships filenames that are not encoded in UTF-8 you can use a utility like convmv (from the convmv package) to convert the filename in your %install section.

Documentation

Any relevant documentation included in the source distribution should be included in the package. Irrelevant documentation include build instructions, the omnipresent INSTALL file containing generic build instructions, for example, and documentation for non-Linux systems, e.g. README.MSDOS. Pay also attention about which subpackage you include documentation in, for example API documentation belongs in the -devel subpackage, not the main one. Or if there's a lot of documentation, consider putting it into a subpackage. In this case, it is recommended to use *-doc as the subpackage name, and Documentation as the value of the Group tag.

Also, if a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present.

Compiler flags

Compilers used to build packages should honor the applicable compiler flags set in the system rpm configuration. This means in practice $RPM_OPT_FLAGS/%{optflags} for C, C++, and Fortran compilers. Honoring means that the contents of that variable is used as the basis of the flags actually used by the compiler during the package build. Adding to and overriding or filtering parts of these flags is permitted if there's a good reason to do so; the rationale for doing so should be reviewed and documented in the specfile especially in the override and filter cases.

Debuginfo packages

Packages should produce useful -debuginfo packages, or explicitly disable them when it is not possible to generate a useful one but rpmbuild would do it anyway. Whenever a -debuginfo package is explicitly disabled, an explanation why it was done is required in the specfile. Debuginfo packages are discussed in more detail in a separate document, Packaging/Debuginfo .

Devel Packages

If the software being packaged contains files intended solely for development, those files should be put in a -devel subpackage. The following are examples of file types which should be in -devel:

• Header files (e.g. .h files)
• Unversioned shared libraries (e.g. libfoo.so). Versioned shared libraries (e.g. libfoo.so.3, libfoo.so.3.0.0) should not be in -devel.

A good rule of thumb is if the file is used for development and not needed for the base package to run properly, it should go in -devel.

Pkgconfig Files

The placement of pkgconfig(.pc) files depends on their usecase. Since they are almost always used for development purposes, they should be placed in a -devel package. A reasonable exception is when the main package itself is a development tool not installed in a user runtime, e.g. gcc or gdb. Packages containing pkgconfig(.pc) files must Recommend: pkg-config (for usability).

Requiring Base Package

Devel packages must require the base package using a versioned dependency: Requires: %{name} = %{version}. Usually, subpackages other than -devel should also require the base package using a versioned dependency.

Shared Libraries

Whenever possible (and feasible), openSUSE Packages containing libraries should build them as shared libraries. In addition, every binary RPM package which contains shared library files (not just symlinks) in any of the dynamic linker's default paths, must call ldconfig in %post and %postun. If the package has multiple subpackages with libraries, each subpackage should also have a %post/%postun section that calls /sbin/ldconfig. An example of the correct syntax for this is:

%post -p /sbin/ldconfig

%postun -p /sbin/ldconfig

Note that this specific syntax only works if /sbin/ldconfig is the only call in %post and %postun. If you have additional commands to run during the scriptlet, call /sbin/ldconfig at the beginning of the scriptlet, like this:

%post
/sbin/ldconfig
/usr/bin/foo --add

%postun
/usr/bin/foo --remove
/sbin/ldconfig

Packaging Static Libraries

Packages including libraries should exclude static libs as far as possible (eg by configuring with --disable-static). Static libraries should only be included in exceptional circumstances. Applications linking against libraries should as far as possible link against shared libraries not static versions.

Libtool archives, foo.la files, should not be included. Packages using libtool will install these by default even if you configure with --disable-static, so they may need to be removed before packaging. Due to bugs in older versions of libtool or bugs in programs that use it, there are times when it is not always possible to remove *.la files without modifying the program. In most cases it is fairly easy to work with upstream to fix these issues. Note that if you are updating a library in a stable release (not devel) and the package already contains *.la files, removing the *.la files should be treated as an API/ABI change -- ie: Removing them changes the interface that the library gives to the rest of the world and should not be undertaken lightly.

Packaging Static Libraries

• In general, packagers are strongly encouraged not to ship static libs unless a compelling reason exists.

• We want to be able to track which packages are using static libraries (so we can find which packages need to be rebuilt if a security flaw in a static library is fixed, for instance). There are two scenarios in which static libraries are packaged:

1. Static libraries and shared libraries. In this case, the static libraries must be placed in a *-devel-static subpackage, which Requires *-devel subpackage. Separating the static libraries from the other development files in *-devel allow us to track this usage by checking which packages BuildRequire the *-devel-static package. The intent is that whenever possible, packages will move away from using these static libraries, to the shared libraries.
2. Static libraries only. When a package only provides static libraries you can place all the static library files in the *-devel subpackage. When doing this you also must have a virtual Provide for the *-devel-static package:

%package devel
Provides: foo-devel-static = %{version}

Packages which explicitly need to link against the static version must BuildRequire: foo-devel-static, so that the usage can be tracked.

• If (and only if) a package has shared libraries which require static libraries to be functional, the static libraries can be included in the *-devel subpackage. The devel subpackage must have a virtual Provide for the *-devel-static package, and packages dependent on it must BuildRequire the *-devel-static package.

Duplication of system libraries

For several reasons, a package should not include or build against a local copy of a library that exists on a system. The package should be patched to use the system libraries.

This prevents old bugs and security holes from living on after the core system libraries have been fixed.

%__arch_install_post            \
/usr/lib/rpm/check-rpaths     \
/usr/lib/rpm/check-buildroot

ERROR   0001: file '/usr/bin/xapian-tcpsrv' contains a standard rpath '/usr/lib64' in [/usr/lib64] 

/usr/lib/foo

%configure
sed -i 's|^hardcode_libdir_flag_spec=.*|hardcode_libdir_flag_spec=""|g' libtool
sed -i 's|^runpath_var=LD_RUN_PATH|runpath_var=DIE_RPATH_DIE|g' libtool

chrpath --delete $RPM_BUILD_ROOT%{_bindir}/xapian-tcpsrv

Make sure that you remember to add a BuildRequires: chrpath if you end up using this method.

Configuration files

Configuration files must be marked as such in packages.

As a rule of thumb, use %config(noreplace) instead of plain %config unless your best, educated guess is that doing so will break things. In other words, think hard before overwriting local changes in configuration files on package upgrades. An example case when /not/ to use noreplace is when a package's configuration file changes so that the new package revision wouldn't work with the config file from the previous package revision. Whenever plain %config is used, add a brief comment to the specfile explaining why.

Don't use %config or %config(noreplace) under /usr. /usr is deemed to not contain configuration files in openSUSE.

Initscripts

Currently, only SystemV-style initscripts are supported in Fedora. There are detailed guidelines for SysV-style initscripts here: Packaging/SysV_Init_Script

Desktop files

If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Installed .desktop files MUST follow the desktop-entry-spec , paying particular attention to validating correct usage of Name, GenericName, Categories , StartupNotify entries.

Icon tag in Desktop Files

The icon tag has to be short name without file extension:

• Icon=comical

because it allows for icon theming (it assumes .png by default, then tries .svg and finally .xpm).

.desktop file creation

If the package doesn't already include and install its own .desktop file, you need to make your own, and include it as a Source: (e.g. Source3: %{name}.desktop). Here are the contents of a sample .desktop file (comical.desktop):

[Desktop Entry]
Name=Comical
GenericName=Comic Archive Reader
Comment=Open .cbr & .cbz files
Exec=comical
Icon=comical
Terminal=false
Type=Application
Categories=Graphics;

%suse_update_desktop_file usage

It is not simply enough to just include the .desktop file in the package, one MUST run %suse_update_desktop_file in %install (and have BuildRequires: update-desktop-files), to help ensure .desktop file safety and spec-compliance. %suse_update_desktop_file MUST be used if the package does not install the file or there are changes desired to the .desktop file (such as add/removing categories, etc). Here are some examples of usage:

• check desktop file

%suse_update_desktop_file %{name}

• install desktop file and change categories

%suse_update_desktop_file -i %{name} System Utility Core GTK FileManager

Macros

Use macros instead of hard-coded directory names (see Packaging/RPM_Macros ).

Having macros in a Source: or Patch: line is a matter of style. Some people enjoy the ready readability of a source line without macros. Others prefer the ease of updating for new versions when macros are used. In all cases, remember to be consistent in your spec file and verify that the URLs you list are valid. spectool (from the rpmdevtools package) can aid you in checking that whether the URL contains macros or not.

If you need to determine the actual string when it contains macros, you can use rpm. For example, to determine the actual Source: value, you can run:

rpm -q --specfile foo.spec --qf "$(grep -i ^Source foo.spec)\n"

Using %{buildroot} and %{optflags} vs $RPM_BUILD_ROOT and $RPM_OPT_FLAGS

There are two styles of defining the rpm Build Root and Optimization Flags in a spec file.

There is very little value in choosing one style over the other, since they will resolve to the same values in all scenarios. You should pick a style and use it consistently throughout your packaging.

Mixing the two styles, while valid, is bad from a QA and usability point of view, and should not be done in openSUSE packages.

Handling Locale Files

openSUSE includes an rpm macro called %find_lang. This macro will locate all of the locale files that belong to your package (by name), and put this list in a file. You can then use that file to include all of the locales. %find_lang should be run in the %install section of your spec file, after all of the files have been installed into the buildroot. The correct syntax for %find_lang is usually:

%find_lang %{name}

In some cases, the application may use a different "name" for its locales. You may have to look at the locale files and see what they are named. If they are named myapp.mo, then you will need to pass myapp to %find_lang instead of %{name}. After %find_lang is run, it will generate a file in the active directory (by default, the top level of the source dir). This file will be named based on what you passed as the option to the %find_lang macro. Usually, it will be named %{name}.lang. You should then use this file in the %files list to include the locales detected by %find_lang. To do this, you should include it with the -f parameter to %files.

%files -f %{name}.lang
%defattr(-,root,root,-)
%{_bindir}/foobar
...

If you are already using the -f parameter for the %files section where the locales should live, just append the contents of %{name}.lang to the end of the file that you are already using with -f. (Note that only one file may be used with %files -f.)

Here is an example of proper usage of %find_lang, in foo.spec:

...
%prep
%setup -q

%build
%configure --with-cheese

%install
make DESTDIR=$RPM_BUILD_ROOT install
%find_lang %{name}

%clean
rm -rf $RPM_BUILD_ROOT

%files -f %{name}.lang
%defattr(-,root,root,-)
%doc LICENSE README
%{_bindir}/foobar

%changelog
* Thu May 4 2006 Tom "spot" Callaway <tcallawa@redhat.com> 0.1-1
- sample spec that uses %%find_lang

Why do we need to use %find_lang?

Using %find_lang helps keep the spec file simple, and helps avoid several other packaging mistakes.

• Packages that use %{_datadir}/* to grab all the locale files in one line also grab ownership of the locale directories, which is not permitted.
• Most packages that have locales have lots of locales. Using %find_lang is much easier in the spec file than having to do:

%{_datadir}/locale/ar/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/be/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/cs/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/de/LC_MESSAGES/%{name}.mo
%{_datadir}/locale/es/LC_MESSAGES/%{name}.mo
...

• As new locale files appear in later package revisions, %find_lang will automatically include them when it is run, preventing you from having to update the spec any more than is necessary.

Keep in mind that usage of %find_lang in packages containing locales is a MUST.

Timestamps

When adding file copying commands in the spec file, consider using a command that preserves the files' timestamps, eg. cp -p or install -p.

When downloading sources, patches etc, consider using a client that preserves the upstream timestamps. For example wget -N or curl -R. To make the change global for wget, add this to your ~/.wgetrc: timestamping = on, and for curl, add to your ~/.curlrc: -R.

Parallel make

Whenever possible, invocations of make should be done as

make %{?jobs:-j%jobs}

This generally speeds up builds and especially on SMP machines.

Do make sure, however, that the package builds cleanly this way as some make files do not support parallel building. Therefore you should consider adding

%jobs 3

to your ~/.rpmmacros file -- even on UP machines -- as this will expose most of these errors.

Requires(pre): ...
Requires(post): ...

%preun
if [ $1 -eq 0 ] ; then
/sbin/chkconfig --del %{name}
fi

Foo-Animal-Emu puts files into /usr/share/Foo/Animal/Emu
Foo-Animal-Llama puts files into /usr/share/Foo/Animal/Llama

In all cases we are guarding against unowned directories being present on a system. Please see Packaging/Unowned_Directories for the details.

Duplicate Files

An openSUSE package must not contain any duplicate files in the %files listing.

File Permissions

Permissions on files must be set properly. Executables should be set with executable permissions, for example. Every %files section must include a %defattr(...) line. Here is a good default:

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

Unless you have a very good reason to deviate from that, you should use %defattr(-,root,root,-) for all %files sections in your package.

Users and Groups

Some packages require or benefit from dedicated runtime user and/or group accounts. Guidelines for handling these cases are in a separate Packaging/Users_And_Groups document.

Web Applications

Web applications packaged in openSUSE should put their content into /srv/www/%{name} and NOT into /var/www. This is done because:

• /var is supposed to contain variable data files and logs. /srv/www is much more appropriate for this.
• Many users already have content in /var/www, and we do not want any openSUSE package to step on top of that.
• /var/www is no longer specified by the Filesystem Hierarchy Standard

Conflicts

Whenever possible, openSUSE packages should avoid conflicting with each other. Unfortunately, this is not always possible. For full details on openSUSE Conflicts policy, see: Packaging/Conflicts .

Bundling of multiple projects

Packages in openSUSE should make every effort to avoid having multiple, separate, upstream projects bundled together in a single package.

Avoid bundling of fonts in other packages

Fonts in general-purpose formats such as Type1, OpenType TT (TTF) or OpenType CFF (OTF) are subject to specific packaging guidelines, and should never be packaged in a private application directory instead of the system-wide font repositories. For more information, see: Package layout for fonts.

All patches should have tags

All patches in openSUSE spec files SHOULD have a comment above them about their status. For details see Packaging/Patches page.

Application Specific Guidelines

Some applications have specific guidelines written for them, located on their own pages in the Packaging/ hierarchy.

Eclipse

Guidelines for Eclipse plugin packages: Packaging/Eclipse_Plugins

Emacs

Guidelines for Emacs/X-Emacs packages: Packaging/Emacs

Fonts

Guidelines for font packages: Packaging/Fonts_Policy

Haskell

Guidelines for Haskell packages: Packaging/Haskell

Java

Guidelines for java packages: Packaging/Java

Lisp

Guidelines for lisp packages: Packaging/Lisp

Mono

Guidelines for Mono packages: Packaging/Mono

OCaml

Guidelines for OCaml packages: Packaging/OCaml

OpenOffice.org

Guidelines for OpenOffice.org extension packages: Packaging/OpenOffice.org_Extensions

Perl

Guidelines for Perl packages: Packaging/Perl

PHP

Guidelines for PHP packages: Packaging/PHP

Python

Guidelines for Python addon modules: Packaging/Python

R

Guidelines for R module packages: Packaging/R

Ruby

Guidelines for Ruby packages: Packaging/Ruby

Tcl/Tk

Guidelines for Tcl/Tk extension packages: Packaging/Tcl