Arch packaging standards

From ArchWiki
Revision as of 03:25, 22 April 2006 by WillySilly (Talk | contribs) (Added the MIT under the special cases for Licenses)

Jump to: navigation, search

Package Standards

When building packages for Arch Linux, you should adhere to the package guidelines below, especially if you would like to contribute your new package to Arch Linux.

Package Naming

  • Package names should consist of alphanumeric characters only; all letters should be lowercase.
  • Package versions should be the same as the version released by the author. Versions can include letters if need be (eg, nmap's version is 2.54BETA32). Version tags may not include hyphens! Letters, numbers, and periods only.
  • Package releases are specific to Arch Linux packages. These allow users to differentiate between newer and older package builds. When a new package version is first released, the release count starts at 1. Then as fixes and optimizations are made, the package will be re-released to the AL public and the release number will increment. When a new version comes out, the release count resets to 1. Package release tags follow the same naming restrictions as version tags.

Directories

  • Configuration files should be placed in the /etc directory. If there's more than one configuration file, it's customary to use a subdirectory 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

    System-essential configuration files

    /usr/bin Application binaries
    /usr/sbin System binaries
    /usr/lib Libraries
    /usr/include Header files
    /usr/lib/{pkg} Modules, plugins, etc.
    /usr/man Manpages
    /usr/share/{pkg} Application data
    /etc/{pkg} Configuration files for {pkg}
    /opt

    Large self-contained packages such as KDE, Mozilla, etc.

makepkg Duties

When you use makepkg to build a package for you, it does the following automatically:

  1. Checks if package dependencies are installed
  2. Downloads source files from servers
  3. Unpacks source files
  4. Does any necessary patching
  5. Builds the software and installs it in a fake root
  6. Removes /usr/doc, /usr/info, /usr/share/doc, and /usr/share/info from the package
  7. Strips symbols from binaries
  8. Strips debugging symbols from libraries
  9. Generates the package meta file which is included with each package
  10. Compresses the fake root into the package file
  11. Stores the package file in the configured destination directory (cwd by default)

Package Etiquette

  • Packages should never be installed to /usr/local
  • Do not introduce new variables into your PKGBUILD build scripts, unless the package cannot be built without doing so, as these could possibly conflict with variables used in makepkg itself. If a new variable is absolutely required, prefix the variable name with an underscore (_) e.g
    _customvariable=

    The AUR cannot detect the use of custom variables and so cannot use them in substitutions. This can most often be seen in the source array e.g.

    http://dl.sourceforge.net/sourceforge/directxwine/$patchname.$patchver.diff.bz2

    Such a situation defeats the effective functionality of the AUR.

  • Avoid using /usr/libexec/ for anything. Use /usr/lib/{pkg} instead.
  • The packager field from the package meta file can 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:
    # export PACKAGER="John Doe@your.email"
  • All important messages should be echoed during install using an .install file. For example, if a package needs extra setup to work, directions should be included.
  • Any optional dependencies that aren't needed to run the package or have it generally function shouldn't be included, but a warning message inside the .install file should echo something like: "To enable SMB support, download the Samba package."
  • When creating a package description for a package, do 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". Also try to keep the descriptions to ~80 characters or less.

Licenses

The use of the license field has been agreed and will be fully enforced and implemented in the next pacman release (probably 2.9.7). Until then the TU team continue to caution against the use of the license variable until the developers have implemented and tested the new system as there may be significant changes. It goes something like this:

  • A licenses package will be created in [current] that stores common (to be defined later) licenses in /usr/share/licenses/common ie. /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 e.g. license="GPL"
  • If the appropriate license is not included in the official licenses package, several things must be done:
    1. the license file(s) should be included /usr/share/licenses/$pkgname e.g. /usr/share/licenses/dibfoo/COPYING.
    2. 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. Remember to call it something appropriate too.
    3. add 'custom' to the licenses array. Optionally, you can replace 'custom' with 'custom:"name of license"'.
  • Once a licenses is used in two or more packages in an official repo, including [community], it becomes common
  • The MIT and BSD 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" or license="MIT") but for the sake of the filesystem, it's a custom license, because each one has its own copyright line. Each MIT or BSD 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. When pacman gets the ability to filter on licenses (so you can say, "I only want GPL and BSD licensed software") dual (or more) licenses will be treated by pacman using OR, rather than AND logic, thus pacman will consider the above example as GPL licensed software, regardless of the other licenses listed.

Submitting Packages

Note the following before submitting any packages:

  1. To ensure the security of pkgs submitted to the AUR please ensure that you have correctly filled the md5sum field. The md5sum's can be generated using the makepkg -g command.
  2. Please add a comment line to the top of your PKGBUILD file that follows this format:
    # Contributor: Your Name <your.email>
  3. Verify the package dependencies (eg, run ldd on dynamic executables, check tools required by scripts, etc). The TU team strongly recommend the use of the namcap utility, written by Jason Chu (jason@archlinux.org), to analyze the sanity of your package. namcap will tell you about bad permissions, missing dependencies, un-needed dependencies, and other common mistakes. You can install the namcap package with pacman. Remember namcap can be used to check both pkg.tar.gz files and PKGBUILDs
  4. Dependencies are the most common packaging error. Namcap can help detect them, but it is not always correct. Verify dependencies by looking at source documentation and the program website.
  5. All files uploaded to the AUR should be contained in a compressed tar file containing a directory with the PKGBUILD and additional build files (patches, install, ...) in it.
    foo/PKGBUILD
    foo/foo.install
    foo/foo_bar.diff
    foo/foo.rc.conf

    The archive name should contain the name of the package e.g. foo.tar.gz

    The tarball should not contain the binary tarball created by makepkg, nor should it contain the filelist

Creating Packages for apps in CVS/SVN

Please see the Arch CVS & SVN PKGBUILD guidelines