Difference between revisions of "Arch package guidelines"
(added MinGW Packages guidelines) |
Lahwaacz.bot (talk | contribs) (update interlanguage links) (Tag: wiki-scripts) |
||
(72 intermediate revisions by 13 users not shown) | |||
Line 1: | Line 1: | ||
− | [[Category: | + | [[Category:Arch package guidelines]] |
− | [[ | + | [[es:Arch packaging standards]] |
− | [[ | + | [[fr:Standard paquetage]] |
− | [[ | + | [[it:Arch packaging standards]] |
− | {{ | + | [[ja:Arch パッケージングスタンダード]] |
+ | [[pt:Arch package guidelines]] | ||
+ | [[ru:Arch package guidelines]] | ||
+ | [[sr:Arch packaging standards]] | ||
+ | [[zh-hans:Arch packaging standards]] | ||
+ | [[zh-hant:Arch packaging standards]] | ||
+ | {{Related articles start}} | ||
+ | {{Related|Creating packages}} | ||
+ | {{Related|PKGBUILD}} | ||
+ | {{Related|makepkg}} | ||
+ | {{Related|Arch Build System}} | ||
+ | {{Related|Arch User Repository}} | ||
+ | {{Related articles end}} | ||
− | + | When building packages for Arch Linux, '''adhere to the package guidelines''' below, especially if the intention is to '''contribute''' a new package to Arch Linux. You should also see the [https://archlinux.org/pacman/PKGBUILD.5.html PKGBUILD] and [https://archlinux.org/pacman/makepkg.8.html makepkg] manpages. | |
− | |||
− | + | ==PKGBUILD prototype== | |
− | |||
− | |||
− | |||
− | = | + | {{bc|1= |
− | |||
# Maintainer: Your Name <youremail@domain.com> | # Maintainer: Your Name <youremail@domain.com> | ||
pkgname=NAME | pkgname=NAME | ||
Line 36: | Line 43: | ||
source=($pkgname-$pkgver.tar.gz) | source=($pkgname-$pkgver.tar.gz) | ||
noextract=() | noextract=() | ||
− | md5sums=() # | + | md5sums=() #autofill using updpkgsums |
build() { | build() { | ||
− | cd " | + | cd "$pkgname-$pkgver" |
./configure --prefix=/usr | ./configure --prefix=/usr | ||
Line 46: | Line 53: | ||
package() { | package() { | ||
− | cd " | + | cd "$pkgname-$pkgver" |
make DESTDIR="$pkgdir/" install | make DESTDIR="$pkgdir/" install | ||
} | } | ||
+ | }} | ||
− | + | Other prototypes are found in {{ic|/usr/share/pacman}} from the pacman and abs packages. | |
− | Other prototypes are found in /usr/share/pacman from the pacman and abs packages. | ||
− | + | == Package etiquette == | |
− | + | * Packages should '''never''' be installed to {{ic|/usr/local}} | |
− | + | * '''Do not introduce new variables or functions''' into {{ic|PKGBUILD}} build scripts, unless the package cannot be built without doing so, as these could possibly '''conflict''' with variables and functions used in makepkg itself. | |
− | + | * If a new variable or a new function is absolutely required, '''prefix its name with an underscore''' ({{ic|_}}), e.g. {{bc|1=_customvariable=}} | |
− | + | * '''Avoid''' using {{ic|/usr/libexec/}} for anything. Use {{ic|/usr/lib/$pkgname/}} instead. | |
− | + | * The {{ic|packager}} field from the package meta file can be '''customized''' by the package builder by modifying the appropriate option in the {{ic|/etc/makepkg.conf}} file, or alternatively override it by creating {{ic|~/.makepkg.conf}}. | |
− | + | * 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. | |
− | + | * '''Dependencies''' are the most common packaging error. Please take the time to verify them carefully, for example by running {{ic|ldd}} on dynamic executables, checking tools required by scripts or looking at the documentation of the software. The [[namcap]] utility can help you in this regard. This tool can analyze both PKGBUILD and the resulting package tarball and will warn you about bad permissions, missing dependencies, redundant dependencies, and other common mistakes. | |
− | + | * Any '''optional dependencies''' that are not needed to run the package or have it generally function should not be included in the '''depends''' array; instead the information should be added to the '''optdepends''' array: | |
− | + | :{{bc|<nowiki> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | important messages should be echoed during install using an | ||
− | example, if a package needs extra setup to work, directions should be included. | ||
− | |||
− | needed to run the package or have it generally function | ||
− | included; instead the information should be added to the | ||
− | < | ||
optdepends=('cups: printing support' | optdepends=('cups: printing support' | ||
'sane: scanners support' | 'sane: scanners support' | ||
Line 99: | Line 79: | ||
'libjpeg: JPEG images support' | 'libjpeg: JPEG images support' | ||
'libpng: PNG images support') | 'libpng: PNG images support') | ||
− | </ | + | </nowiki>}} |
− | + | :The above example is taken from the '''wine''' package in {{Ic|extra}}. The optdepends information is automatically printed out on installation/upgrade so one should '''not''' keep this kind of information in {{ic|.install}} files. | |
− | The above example is taken from the | + | * 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. |
− | information is automatically printed out on installation/upgrade so | + | * Try to keep the '''line length''' in the PKGBUILD below ~100 characters. |
− | one should | + | * Where possible, '''remove empty lines''' from the {{ic|PKGBUILD}} ({{ic|provides}}, {{ic|replaces}}, etc.) |
− | + | * It is common practice to '''preserve the order''' of the {{ic|PKGBUILD}} fields as shown above. However, this is not mandatory, as the only requirement in this context is '''correct bash syntax'''. | |
− | + | * '''Quote''' variables which may contain spaces, such as {{ic|"$pkgdir"}} and {{ic|"$srcdir"}}. | |
− | + | * To ensure the '''integrity''' of packages, make sure that the [[PKGBUILD#Integrity|integrity variables]] contain correct values. These can be updated using the {{ic|updpkgsums}} tool. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | ==Package naming== | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | * Package names can contain only alphanumeric characters and any of {{ic|@}}, {{ic|.}}, {{ic|_}}, {{ic|+}}, {{ic|-}}. Names are not allowed to start with hyphens or dots. All letters should be lowercase. | |
− | + | * Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo. | |
− | + | * 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 Arch Linux 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 {{ic|/etc}} directory. If there is more than one configuration file, it is customary to '''use a subdirectory''' in order to keep the {{ic|/etc}} area as clean as possible. Use {{ic|/etc/{pkgname}/}} where {{ic|<nowiki>{pkgname}</nowiki>}} is the name of the package (or a suitable alternative, eg, apache uses {{ic|/etc/httpd/}}). | |
− | |||
− | + | * Package files should follow these '''general directory guidelines''': | |
− | |||
− | < | + | :{| |
− | + | |- | |
+ | | {{ic|/etc}} | ||
+ | | '''System-essential''' configuration files | ||
+ | |- | ||
+ | | {{ic|/usr/bin}} | ||
+ | | Binaries | ||
+ | |- | ||
+ | | {{ic|/usr/lib}} | ||
+ | | Libraries | ||
+ | |- | ||
+ | | {{ic|/usr/include}} | ||
+ | | Header files | ||
+ | |- | ||
+ | | {{ic|<nowiki>/usr/lib/{pkg}</nowiki>}} | ||
+ | | Modules, plugins, etc. | ||
+ | |- | ||
+ | | {{ic|<nowiki>/usr/share/doc/{pkg}</nowiki>}} | ||
+ | | Application documentation | ||
+ | |- | ||
+ | | {{ic|/usr/share/info}} | ||
+ | | GNU Info system files | ||
+ | |- | ||
+ | | {{ic|/usr/share/man}} | ||
+ | | Manpages | ||
+ | |- | ||
+ | | {{ic|<nowiki>/usr/share/{pkg}</nowiki>}} | ||
+ | | Application data | ||
+ | |- | ||
+ | | {{ic|<nowiki>/var/lib/{pkg}</nowiki>}} | ||
+ | | Persistent application storage | ||
+ | |- | ||
+ | | {{ic|<nowiki>/etc/{pkg}</nowiki>}} | ||
+ | | Configuration files for {{ic|<nowiki>{pkg}</nowiki>}} | ||
+ | |- | ||
+ | | {{ic|<nowiki>/opt/{pkg}</nowiki>}} | ||
+ | | Large self-contained packages | ||
+ | |} | ||
− | + | * Packages should not contain any of the following directories: | |
− | + | ** {{ic|/bin}} | |
+ | ** {{ic|/sbin}} | ||
+ | ** {{ic|/dev}} | ||
+ | ** {{ic|/home}} | ||
+ | ** {{ic|/srv}} | ||
+ | ** {{ic|/media}} | ||
+ | ** {{ic|/mnt}} | ||
+ | ** {{ic|/proc}} | ||
+ | ** {{ic|/root}} | ||
+ | ** {{ic|/selinux}} | ||
+ | ** {{ic|/sys}} | ||
+ | ** {{ic|/tmp}} | ||
+ | ** {{ic|/var/tmp}} | ||
+ | ** {{ic|/run}} | ||
− | + | == Makepkg duties == | |
− | |||
− | + | When [[makepkg]] is used to build a package, it does the following automatically: | |
− | |||
− | + | # Checks if package '''dependencies''' and '''makedepends''' are installed | |
− | + | # '''Downloads source''' files from servers | |
+ | # '''Checks the integrity''' of source files | ||
+ | # '''Unpacks''' source files | ||
+ | # Does any necessary '''patching''' | ||
+ | # '''Builds''' the software and installs it in a fake root | ||
+ | # '''Strips''' symbols from binaries | ||
+ | # '''Strips''' debugging symbols from libraries | ||
+ | # '''Compresses''' manual and, or info pages | ||
+ | # Generates the '''package meta file''' which is included with each package | ||
+ | # '''Compresses''' the fake root into the package file | ||
+ | # '''Stores''' the package file in the configured destination directory (<span title="Current Working Directory" style="border-bottom: 1px dotted">cwd</span> by default) | ||
− | + | ==Architectures== | |
− | |||
− | + | The {{Ic|arch}} array should contain {{Ic|'x86_64'}} if the compiled package is architecture-specific. Otherwise, use {{Ic|'any'}} for architecture independent packages. | |
− | |||
− | + | ==Licenses== | |
− | |||
− | + | See [[PKGBUILD#license]]. | |
− | |||
− | + | ==Additional guidelines== | |
− | + | Be sure to read the above guidelines first - important points are listed on this page that will not be repeated in the following guideline pages. These specific guidelines are intended as an addition to the standards listed on this page. | |
− | + | {{Package guidelines}} | |
− | |||
− | + | Packages submitted to the AUR must additionally comply with [[Arch User Repository#Rules of submission]]. | |
− |
Latest revision as of 21:31, 26 November 2018
When building packages for Arch Linux, adhere to the package guidelines below, especially if the intention is to contribute a new package to Arch Linux. You should also see the PKGBUILD and makepkg manpages.
Contents
PKGBUILD prototype
# Maintainer: Your Name <youremail@domain.com> pkgname=NAME pkgver=VERSION pkgrel=1 pkgdesc="" arch=() url="" license=('GPL') groups=() depends=() makedepends=() optdepends=() provides=() conflicts=() replaces=() backup=() options=() install= changelog= source=($pkgname-$pkgver.tar.gz) noextract=() md5sums=() #autofill using updpkgsums build() { cd "$pkgname-$pkgver" ./configure --prefix=/usr make } package() { cd "$pkgname-$pkgver" make DESTDIR="$pkgdir/" install }
Other prototypes are found in /usr/share/pacman
from the pacman and abs packages.
Package etiquette
- Packages should never be installed to
/usr/local
- Do not introduce new variables or functions into
PKGBUILD
build scripts, unless the package cannot be built without doing so, as these could possibly conflict with variables and functions used in makepkg itself. - If a new variable or a new function is absolutely required, prefix its name with an underscore (
_
), e.g._customvariable=
- Avoid using
/usr/libexec/
for anything. Use/usr/lib/$pkgname/
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 override it by creating~/.makepkg.conf
. - 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.
- Dependencies are the most common packaging error. Please take the time to verify them carefully, for example by running
ldd
on dynamic executables, checking tools required by scripts or looking at the documentation of the software. The namcap utility can help you in this regard. This tool can analyze both PKGBUILD and the resulting package tarball and will warn you about bad permissions, missing dependencies, redundant dependencies, and other common mistakes. - Any optional dependencies that are not needed to run the package or have it generally function should not be included in the depends array; instead the information should be added to the optdepends array:
optdepends=('cups: printing support' 'sane: scanners support' 'libgphoto2: digital cameras support' 'alsa-lib: sound support' 'giflib: GIF images support' 'libjpeg: JPEG images support' 'libpng: PNG images support')
- The above example is taken from the wine package in
extra
. The optdepends information is automatically printed out on installation/upgrade so one should not keep this kind of information in.install
files.
- 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.
- Try to keep the line length in the PKGBUILD below ~100 characters.
- Where possible, remove empty lines from the
PKGBUILD
(provides
,replaces
, etc.) - It is common practice to preserve the order of the
PKGBUILD
fields as shown above. However, this is not mandatory, as the only requirement in this context is correct bash syntax. - Quote variables which may contain spaces, such as
"$pkgdir"
and"$srcdir"
. - To ensure the integrity of packages, make sure that the integrity variables contain correct values. These can be updated using the
updpkgsums
tool.
Package naming
- Package names can contain only alphanumeric characters and any of
@
,.
,_
,+
,-
. Names are not allowed to start with hyphens or dots. All letters should be lowercase. - Package names should NOT be suffixed with the upstream major release version number (e.g. we don't want libfoo2 if upstream calls it libfoo v2.3.4) in case the library and its dependencies are expected to be able to keep using the most recent library version with each respective upstream release. However, for some software or dependencies, this can not be assumed. In the past this has been especially true for widget toolkits such as GTK and Qt. Software that depends on such toolkits can usually not be trivially ported to a new major version. As such, in cases where software can not trivially keep rolling alongside its dependencies, package names should carry the major version suffix (e.g. gtk2, gtk3, qt4, qt5). For cases where most dependencies can keep rolling along the newest release but some can't (for instance closed source that needs libpng12 or similar), a deprecated version of that package might be called libfoo1 while the current version is just libfoo.
- 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 Arch Linux 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 is more than one configuration file, it is 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 the 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
Binaries /usr/lib
Libraries /usr/include
Header files /usr/lib/{pkg}
Modules, plugins, etc. /usr/share/doc/{pkg}
Application documentation /usr/share/info
GNU Info system files /usr/share/man
Manpages /usr/share/{pkg}
Application data /var/lib/{pkg}
Persistent application storage /etc/{pkg}
Configuration files for {pkg}
/opt/{pkg}
Large self-contained packages
- Packages should not contain any of the following directories:
/bin
/sbin
/dev
/home
/srv
/media
/mnt
/proc
/root
/selinux
/sys
/tmp
/var/tmp
/run
Makepkg duties
When makepkg is used to build a package, it does the following automatically:
- Checks if package dependencies and makedepends are installed
- Downloads source files from servers
- Checks the integrity of source files
- Unpacks source files
- Does any necessary patching
- Builds the software and installs it in a fake root
- Strips symbols from binaries
- Strips debugging symbols from libraries
- Compresses manual and, or info pages
- Generates the package meta file which is included with each package
- Compresses the fake root into the package file
- Stores the package file in the configured destination directory (cwd by default)
Architectures
The arch
array should contain 'x86_64'
if the compiled package is architecture-specific. Otherwise, use 'any'
for architecture independent packages.
Licenses
See PKGBUILD#license.
Additional guidelines
Be sure to read the above guidelines first - important points are listed on this page that will not be repeated in the following guideline pages. These specific guidelines are intended as an addition to the standards listed on this page.
CLR – Cross – Eclipse – Electron – Free Pascal – GNOME – Go – Haskell – Java – KDE – Kernel – Lisp – MinGW – Node.js – Nonfree – OCaml – Perl – PHP – Python – R – Ruby – Rust – VCS – Web – Wine
Packages submitted to the AUR must additionally comply with Arch User Repository#Rules of submission.