Packaging Guidelines
From ArchServer Wiki
These guidelines form the basis for how software is to be maintained via PKGBUILD's for the ArchServer Project. They are based mainly off the standard ArchLinux packaging standards, with some minor modifications
Contents |
PKGBUILD Template
# Maintainer: Your Name <youremail at domain dot com> (disguise your email to protect against spam)
pkgname=(NAME)
pkgver=VERSION
pkgrel=1
pkgdesc=""
arch=('i686' 'x86_64')
url="http://ADDRESS/"
license=('GPL')
groups=()
depends=()
makedepends=()
optdepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=()
install=
source=($pkgname-$pkgver.tar.gz)
noextract=()
md5sums=() #generate with 'makepkg -g'
build() {
cd $srcdir/$pkgname-$pkgver
./configure \
--prefix=/usr
--other-option || return 1
make || return 1
}
package() {
make DESTDIR=$pkgdir install || return 1
}
Package Etiquette
- Packages MUST NOT be installed to /usr/local
- Use of "|| return 1" to abort building MUST be used on all operations, UNLESS the command:
- Can not be tested for appropriate return value
- failure would not alter the outcome of the package (eg, 'echo' commands showing the progress of packaging)
- Additional variables in a PKGBUILD could possibly conflict with variables used in makepkg itself. Custom variables SHOULD be prefixed with an underscore (_) and SHOULD be written in UPPERCASE:
_PKG_MAJOR_VER=
- Use of /usr/libexec/ for anything SHOULD be avoided. Use /usr/lib/${pkgname}/ instead.
- The packager field from the package meta file SHOULD be customized by the package builder by modifying the appropriate option in the /etc/makepkg.conf file, or alternatively by exporting the PACKAGER environment variable before building packages with makepkg
- All important messages for end users SHOULD be displayed post-install using an .install file. For example, if a package needs extra setup to work, directions should be included. Links to external instructions CAN be provided if available.
- Package descriptions MUST NOT include the package name in a self-referencing way. For example, "Nedit is a text editor for X11" could be simplified to "A text editor for X11". Descriptions SHOULD be limtied to ~80 characters or less.
- Unused PKGBUILD variables SHOULD be removed from the PKGBUILD of they are not used (eg. provides, replaces, optdepends etc.)
- The REPLACES variable SHOULD NOT be used in a PKGBUILD unless the package is being renamed, for example when Ethereal became Wireshark. If the package is providing an alternate version of an already existing package, the CONFLICTS and PROVIDES variables SHOULD be used instead.
- The following file naming conventions SHOULD be used in association with a PKGBUILD:
{pkgname}/PKGBUILD Main PKGBUILD
{pkgname}/{pkgname}.install Install file for the package. the .install suffix MUST be used.
{pkgname}/fix_for_broken_foobar.patch Any arbitrarily named patch to be applied against the package, the .patch suffix SHOULD be used.
{pkgname}/rc.{pkgname} An init script for the /etc/rc.d/ directory. The rc. prefix MUST be used.
{pkgname}/confd.{pkgname} A configuration file for the /etc/conf.d/ directory. The confd. prefix MUST be used.
{pkgname}/ChangeLog A log of changes made in PKGBUILD and package scripts. Letters 'C' and 'L' MUST be capital.
- A "Maintainer" comment MUST be at the top of each PKGBUILD to designate the current package maintainer (ie, you)
- A "Contributor" comment SHOULD be added at the top of each PKGBUILD to give appropriate attribution to other people who have contributed or previously maintained this PKGBUILD.
Package Naming
- The PKGNAME variable SHOULD consist of alphanumeric characters only.
- The PKGNAME variable SHOULD be written in lowercase.
- The PKGVER variable SHOULD be the same as the version released by the upstream author. Versions can include letters if need be (eg, nmap's version is 2.54BETA32).
- The PKGVER variable MUST NOT include hyphens.
Directories
- Configuration files SHOULD be placed in the /etc directory.
- If there's more than one configuration file is required, a subdirectory SHOULD be created in order to keep the /etc area as clean as possible. Use /etc/{pkgname}/ where {pkgname} is the name of your package (or a suitable alternative, eg, apache uses /etc/httpd/).
- Package files SHOULD follow these general directory guidelines:
| /etc | Configuration files |
| /etc/{pkgname} | Configuration files |
| /usr/bin | Application binaries |
| /usr/sbin | System binaries |
| /usr/lib | Libraries |
| /usr/include | Header files |
| /usr/lib/{pkgname} | Modules, plugins, etc. |
| /usr/share/doc/{pkgname} | Application documentation |
| /usr/share/info | GNU Info system files |
| /usr/share/man | Man Pages |
| /usr/share/{pkgname} | Application data |
| /var/lib/{pkgname} | Persistent application storage |
| /opt/{pkgname} | Large self-contained packages such as Java, etc. |
| /srv | Data served via daemons not owned by a specific human user, by protocol / daemon. Eg, /srv/http/ for file served by HTTP, /srv/postfix for Postfix). Data owned by a human-user MAY be served from either /srv or the users home directory (eg ~/public_html or ~/git |
- Packages SHOULD NOT install files to the following directories:
- /dev
- /home
- /srv
- /media
- /mnt
- /proc
- /root
- /selinux
- /sys
- /tmp
- /usr/local
- /var/tmp
Architectures
The ARCH array MUST contain and combination of one or more of 'i686', 'x86_64' and/or 'any' depending on which architectures it can be built on. The 'any' option MUST be used for architecture independent packages (eg, web applications). Use of the 'any' option is mutually exclusive of the other options.
Licenses
- The LICENSE array MUST be populated with data, unless a license is unavailable or unknown, in which case the 'unknown' option should be used.
- Common licenses are stored in /usr/share/licenses/common (eg. /usr/share/licenses/common/GPL). If a package is licensed under one of these licenses, the licenses variable will be set to the directory name (eg. license=('GPL'))
- If the appropriate license is not included in the official licenses package, several things MUST be done:
- The license file(s) MUST be installed to the /usr/share/licenses/$pkgname/ directory (eg. /usr/share/licenses/foobar/COPYING)
- If the source tarball does not contain the license details and the license is only displayed on a website for example, then you need to copy the license to a file and include it.
- Use the 'custom' option to the licenses array.
- Once a licenses is used in two or more packages in an official repo, including [community], it becomes common
- The MIT, BSD, zlib/libpng and Python licenses are special cases and cannot be included in the 'common' licenses pkg. For the sake of the license variable, it's treated like a common license (license=('BSD'), license=('MIT'), license=('ZLIB') or license=('Python')) but for the sake of the filesystem, it's a custom license, because each one has its own copyright line. Each MIT, BSD, zlib/libpng or Python licensed package should have its unique license stored in /usr/share/licenses/$pkgname/.
- Some packages may not be covered by a single license. In these cases multiple entries may be made in the license array e.g. license=("GPL" "custom:some commercial license"). For the majority of packages these licenses apply in different cases, as opposed to applying at the same time.
- The (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:
- (L)GPL - (L)GPLv2 or any later version
- (L)GPL2 - (L)GPL2 only
- (L)GPL3 - (L)GPL3 or any later version
Package Validation
- Verify the package dependencies (eg. run ldd on dynamic executables, check tools required by scripts, etc).
- The PKGBUILD file MUST be checked by the namcap utility to analyze the sanity of the package. Any errors found SHOULD be fixed before building the package.
- Packagers MUST have the correct packager variable set in makepkg.conf to ensure ownership is maintained over binary packages.