Difference between revisions of "Arch packaging standards"

From ArchWiki
Jump to: navigation, search
(Package Naming)
(wikify some external links, use https for archlinux.org)
(29 intermediate revisions by 7 users not shown)
Line 1: Line 1:
[[Category:About Arch (English)]]
+
[[Category:About Arch]]
[[Category:Package management (English)]]
+
[[Category:Package management]]
[[Category:Package development (English)]]
+
[[Category:Package development]]
[[Category:Guidelines (English)]]
+
[[es:Arch Packaging Standards]]
{{i18n|Arch Packaging Standards}}
+
[[fr:Standard paquetage]]
 +
[[it:Arch Packaging Standards]]
 +
[[ru:Arch Packaging Standards]]
 +
[[sr:Arch Packaging Standards]]
 +
[[zh-CN:Arch Packaging Standards]]
 +
[[zh-TW:Arch Packaging Standards]]
 +
'''The submitted PKGBUILDs must not build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in comparison to the official ones. In such an occasion, the pkgname array should be different.'''
  
==Packaging Standards==
+
When building packages for Arch Linux, '''adhere to the package guidelines''' below, especially if the intention is
<strong>The submitted PKGBUILDs must not build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in comparison to the official ones. In such an occasion, the pkgname array should be different.</strong>
+
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.
  
When building packages for Arch Linux, <strong>adhere to the package guidelines</strong> below, especially if the intention is
+
==PKGBUILD prototype==
to <strong>contribute</strong> a new package
+
{{bc|1=
to Arch Linux. You should also see the [http://archlinux.org/pacman/PKGBUILD.5.html PKGBUILD] and
+
[http://archlinux.org/pacman/makepkg.8.html makepkg] manpages.
+
 
+
====PKGBUILD Prototype====
+
<pre>
+
 
# Maintainer: Your Name <youremail@domain.com>
 
# Maintainer: Your Name <youremail@domain.com>
 
pkgname=NAME
 
pkgname=NAME
Line 50: Line 53:
 
   make DESTDIR="$pkgdir/" install
 
   make DESTDIR="$pkgdir/" install
 
}
 
}
 +
}}
  
</pre>
+
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====
+
==Package etiquette==
  
 
<ul>
 
<ul>
<li>Packages should <strong>never</strong> be installed to <code>/usr/local</code></li>
+
<li>Packages should '''never''' be installed to {{ic|/usr/local}}</li>
 
<li>
 
<li>
<strong>Do not introduce new variables</strong> into
+
'''Do not introduce new variables''' into
<code>PKGBUILD</code> build scripts, unless the package cannot be built without doing so, as these could
+
{{ic|PKGBUILD}} build scripts, unless the package cannot be built without doing so, as these could
possibly <strong>conflict</strong> with variables used
+
possibly '''conflict''' with variables used
 
in makepkg itself.
 
in makepkg itself.
  
 
If a new variable is absolutely required,
 
If a new variable is absolutely required,
<strong>prefix the variable name with an underscore</strong> (<code>_</code>), e.g.
+
'''prefix the variable name with an underscore''' ({{ic|_}}), e.g.
<pre>_customvariable=</pre>
+
{{bc|1=_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.
 
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.
<pre>http://downloads.sourceforge.net/directxwine/$patchname.$patchver.diff.bz2</pre>
+
{{bc|<nowiki>http://downloads.sourceforge.net/directxwine/$patchname.$patchver.diff.bz2</nowiki>}}
 
Such a situation defeats the effective functionality of the AUR.
 
Such a situation defeats the effective functionality of the AUR.
 
</li>
 
</li>
  
 
<li>
 
<li>
<strong>Avoid</strong> using <code>/usr/libexec/</code> for
+
'''Avoid''' using {{ic|/usr/libexec/}} for
anything. Use <code>/usr/lib/${pkgname}/</code> instead.
+
anything. Use {{ic|/usr/lib/${pkgname}/}} instead.
 
</li>
 
</li>
 
<li>
 
<li>
The <code>packager</code> field from the package meta file can be
+
The {{ic|packager}} field from the package meta file can be
<strong>customized</strong> by the package builder by modifying
+
'''customized''' by the package builder by modifying
the appropriate option in the <code>/etc/makepkg.conf</code>
+
the appropriate option in the {{ic|/etc/makepkg.conf}}
  
 
file, or alternatively override it by creating ~/.makepkg.conf
 
file, or alternatively override it by creating ~/.makepkg.conf
  
 
</li>
 
</li>
<li>All
+
<li>
important messages should be echoed during install using an <strong>.install file</strong>. For
+
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. </li>
 
example, if a package needs extra setup to work, directions should be included. </li>
             <li>Any <strong>optional dependencies</strong> that aren't
+
             <li>Any '''optional dependencies''' that are not
needed to run the package or have it generally function shouldn't be
+
needed to run the package or have it generally function should not be
 
included; instead the information should be added to the <b>optdepends</b> array:
 
included; instead the information should be added to the <b>optdepends</b> array:
<pre>
+
{{bc|1=
 
optdepends=('cups: printing support'
 
optdepends=('cups: printing support'
 
             'sane: scanners support'
 
             'sane: scanners support'
Line 99: Line 102:
 
             'libjpeg: JPEG images support'
 
             'libjpeg: JPEG images support'
 
             'libpng: PNG images support')
 
             'libpng: PNG images support')
</pre>
+
}}
  
The above example is taken from the <b>wine</b> package in <tt>extra</tt>. The optdepends
+
The above example is taken from the <b>wine</b> package in {{Ic|extra}}. The optdepends
 
information is automatically printed out on installation/upgrade so
 
information is automatically printed out on installation/upgrade so
 
one should <b>not</b> keep this kind of information in .install files.
 
one should <b>not</b> keep this kind of information in .install files.
  
 
</li>
 
</li>
         <li>When creating a <strong>package description</strong> for a package, do not include
+
         <li>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.</li>
 
         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.</li>
<li>Try to keep the <strong>line length</strong> in the PKGBUILD below ~100 characters.</li>
+
<li>Try to keep the '''line length''' in the PKGBUILD below ~100 characters.</li>
<li>Where possible, <strong>remove empty lines</strong> from the <code>PKGBUILD</code> (<code>provides</code>, <code>replaces</code>, etc.)</li>
+
<li>Where possible, '''remove empty lines''' from the {{ic|PKGBUILD}} ({{ic|provides}}, {{ic|replaces}}, etc.)</li>
<li>It is common practice to <strong>preserve the order</strong> of the <code>PKGBUILD</code> fields as shown above. However, this is not mandatory, as the only requirement in this context is <strong>correct bash syntax</strong>.</li>
+
<li>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'''.</li>
 
</ul>
 
</ul>
  
====Package Naming====
+
==Package naming==
 
 
 
<ul>
 
<ul>
 
<li>
 
<li>
Package names should consist of <strong>alphanumeric characters
+
Package names should consist of '''alphanumeric characters only'''; all letters should be
only</strong>; all letters should be
+
'''lowercase'''.
<strong>lowercase</strong>.
+
 
</li>
 
</li>
 
<li>
 
<li>
Package versions <strong>should be the same as the version
+
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.
released by the author</strong>. Versions can include
+
letters if need be (eg, nmap's version is 2.54BETA32).
+
<strong>Version tags may not include hyphens!</strong> Letters,
+
numbers, and periods only.
+
 
</li>
 
</li>
  
 
<li>
 
<li>
Package releases are <strong>specific to Arch Linux
+
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'''.
packages</strong>. These allow users to differentiate
+
between newer and older package builds. When a new package
+
version is first released, the <strong>release count starts at
+
1</strong>. Then as fixes and optimizations are made,
+
the package will be <strong>re-released</strong> to the Arch Linux
+
public and the <strong>release number will increment</strong>.
+
When a new version comes out, the release count resets to 1.
+
Package release tags follow the <strong>same naming
+
restrictions as version tags</strong>.
+
 
</li>
 
</li>
 
</ul>
 
</ul>
  
<h4>Directories</h4>
+
==Directories==
 
<ul>
 
<ul>
 
<li>
 
<li>
<strong>Configuration files</strong> should be placed in the
+
'''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/}}).
<code>/etc</code> directory. If there's more than one
+
configuration file, it's customary to <strong>use a
+
subdirectory</strong> in order to keep the
+
<code>/etc</code> area as clean as possible. Use
+
<code>/etc/{pkgname}/</code> where <code>{pkgname}</code> is
+
the name of your package (or a suitable alternative, eg, apache
+
uses <code>/etc/httpd/</code>).
+
 
</li>
 
</li>
  
 
<li>
 
<li>
Package files should follow these  
+
Package files should follow these '''general directory guidelines''':
<strong>general directory guidelines</strong>:
+
 
</li>
 
</li>
 
 
 
<table cellspacing="1" >
 
<table cellspacing="1" >
 
<tr>
 
<tr>
<td><code>/etc</code></td>
+
<td>{{ic|/etc}}</td>
 
<td style="padding-left: 1em;">
 
<td style="padding-left: 1em;">
<strong>System-essential</strong> configuration files
+
'''System-essential''' configuration files
 
</td>
 
</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/bin</code></td>
+
<td>{{ic|/usr/bin}}</td>
 
<td style="padding-left: 1em;">Application binaries</td>
 
<td style="padding-left: 1em;">Application binaries</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/sbin</code></td>
+
<td>{{ic|/usr/sbin}}</td>
  
 
<td style="padding-left: 1em;">System binaries</td>
 
<td style="padding-left: 1em;">System binaries</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/lib</code></td>
+
<td>{{ic|/usr/lib}}</td>
 
<td style="padding-left: 1em;">Libraries</td>
 
<td style="padding-left: 1em;">Libraries</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/include</code></td>
+
<td>{{ic|/usr/include}}</td>
 
<td style="padding-left: 1em;">Header files</td>
 
<td style="padding-left: 1em;">Header files</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/lib/{pkg}</code></td>
+
<td>{{ic|<nowiki>/usr/lib/{pkg}</nowiki>}}</td>
 
<td style="padding-left: 1em;">Modules, plugins, etc.</td>
 
<td style="padding-left: 1em;">Modules, plugins, etc.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/share/doc/{pkg}</code></td>
+
<td>{{ic|<nowiki>/usr/share/doc/{pkg}</nowiki>}}</td>
 
<td style="padding-left: 1em;">Application documentation</td>
 
<td style="padding-left: 1em;">Application documentation</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/share/info</code></td>
+
<td>{{ic|/usr/share/info}}</td>
 
<td style="padding-left: 1em;">GNU Info system files</td>
 
<td style="padding-left: 1em;">GNU Info system files</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/share/man</code></td>
+
<td>{{ic|/usr/share/man}}</td>
 
<td style="padding-left: 1em;">Manpages</td>
 
<td style="padding-left: 1em;">Manpages</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/usr/share/{pkg}</code></td>
+
<td>{{ic|<nowiki>/usr/share/{pkg}</nowiki>}}</td>
 
<td style="padding-left: 1em;">Application data</td>
 
<td style="padding-left: 1em;">Application data</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/var/lib/{pkg}</code></td>
+
<td>{{ic|<nowiki>/var/lib/{pkg}</nowiki>}}</td>
 
<td style="padding-left: 1em;">Persistent application storage</td>
 
<td style="padding-left: 1em;">Persistent application storage</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/etc/{pkg}</code></td>
+
<td>{{ic|<nowiki>/etc/{pkg}</nowiki>}}</td>
<td style="padding-left: 1em;">Configuration files for <code>{pkg}</code></td>
+
<td style="padding-left: 1em;">Configuration files for {{ic|<nowiki>{pkg}</nowiki>}}</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td><code>/opt/{pkg}</code></td>
+
<td>{{ic|<nowiki>/opt/{pkg}</nowiki>}}</td>
 
<td style="padding-left: 1em;">
 
<td style="padding-left: 1em;">
 
Large self-contained packages such as Java,
 
Large self-contained packages such as Java,
Line 241: Line 222:
 
</ul>
 
</ul>
  
====[[Makepkg]] Duties====
+
==Makepkg duties==
  
 
<p>
 
<p>
When you use makepkg to build a package for you, it does the
+
When [[makepkg]] is used to build a package, it does the
 
following automatically:
 
following automatically:
 
</p>
 
</p>
Line 250: Line 231:
 
<ol>
 
<ol>
 
<li>
 
<li>
Checks if package <strong>dependencies</strong> and <strong>makedepends</strong> are installed
+
Checks if package '''dependencies''' and '''makedepends''' are installed
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Downloads source</strong> files from servers
+
'''Downloads source''' files from servers
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Checks the integrity</strong> of source files
+
'''Checks the integrity''' of source files
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Unpacks</strong> source files
+
'''Unpacks''' source files
 
</li>
 
</li>
 
<li>
 
<li>
Does any necessary <strong>patching</strong>
+
Does any necessary '''patching'''
 
</li>
 
</li>
 
<li>
 
<li>
  
<strong>Builds</strong> the software and installs it in a fake
+
'''Builds''' the software and installs it in a fake
 
root
 
root
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Strips</strong> symbols from binaries
+
'''Strips''' symbols from binaries
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Strips</strong> debugging symbols from libraries
+
'''Strips''' debugging symbols from libraries
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Compresses</strong> manual and, or info pages
+
'''Compresses''' manual and, or info pages
 
</li>
 
</li>
 
<li>
 
<li>
Generates the <strong>package meta file</strong> which is
+
Generates the '''package meta file''' which is included with each package
included with each package
+
 
</li>
 
</li>
  
 
<li>
 
<li>
<strong>Compresses</strong> the fake root into the package file
+
'''Compresses''' the fake root into the package file
 
</li>
 
</li>
 
<li>
 
<li>
<strong>Stores</strong> the package file in the configured
+
'''Stores''' the package file in the configured destination directory (<span title="Current Working Directory" style="border-bottom:1px dotted">cwd</span> by default)
destination directory
+
(<span title="Current Working Directory" style="border-bottom:1px dotted">cwd</span> by
+
default)
+
 
</li>
 
</li>
  
 
</ol>
 
</ol>
  
====Architectures====
+
==Architectures==
The <tt>arch</tt> array should contain <tt>'i686'</tt> and/or <tt>'x86_64'</tt> depending on which architectures it can be built on. You can also use <tt>'any'</tt> for architecture independent packages.
+
The {{Ic|arch}} array should contain {{Ic|'i686'}} and/or {{Ic|'x86_64'}} depending on which architectures it can be built on. You can also use {{Ic|'any'}} for architecture independent packages.
  
====[[Licenses]]====
+
==Licenses==
The license array is being implemented little by little in the official repos, and it <b>should</b> be used in your packages as well. You can use it as follows:
+
The [[Licenses|license]] array is being implemented in the official repos, and it <b>should</b> be used in your packages as well. Use it as follows:
 
<ul>
 
<ul>
 
<li>A licenses package has been created in [core] that stores common 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')</li>
 
<li>A licenses package has been created in [core] that stores common 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')</li>
 
<li>If the appropriate license is not included in the official licenses package, several things must be done:
 
<li>If the appropriate license is not included in the official licenses package, several things must be done:
 
<ol>
 
<ol>
<li>The license file(s) should be included in /usr/share/licenses/$pkgname/ e.g. /usr/share/licenses/dibfoo/COPYING.</li>
+
<li>The license file(s) should be included in /usr/share/licenses/$pkgname/ e.g. /usr/share/licenses/dibfoo/LICENSE. One good way to do this is by using:
<li>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.
+
{{bc|install -D -m644 LICENSE "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE"}}
 +
</li>
 +
<li>If the source tarball does NOT contain the license details and the license is only displayed on a website for example, then copy the license to a file and include it.  Remember to call it something appropriate too.
 
<li>Add 'custom' to the licenses array.  Optionally, you can replace 'custom' with 'custom:"name of license"'.</li>
 
<li>Add 'custom' to the licenses array.  Optionally, you can replace 'custom' with 'custom:"name of license"'.</li>
 
</ol></li>
 
</ol></li>
 
<li>Once a licenses is used in two or more packages in an official repo, including [community], it becomes common</li>
 
<li>Once a licenses is used in two or more packages in an official repo, including [community], it becomes common</li>
<li>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/.</li>
+
<li>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 is treated like a common license (license=('BSD'), license=('MIT'), license=('ZLIB') or license=('Python')) but for the sake of the filesystem, it is 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/.</li>
 
<li>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.</li>
 
<li>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.</li>
 
<li>The (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:
 
<li>The (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:
Line 320: Line 299:
 
</ul>
 
</ul>
  
====Submitting Packages to the AUR====
+
==Submitting packages to the AUR==
 
<p>Note the following before submitting any packages to the AUR:</p>
 
<p>Note the following before submitting any packages to the AUR:</p>
  
 
<ol>
 
<ol>
 
         <li>
 
         <li>
                 The submitted PKGBUILDs <strong>MUST NOT</strong> build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in compare to the official ones. In such an occasion the pkgname array should be different to express that difference.
+
                 The submitted PKGBUILDs '''MUST NOT''' build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in compare to the official ones. In such an occasion the pkgname array should be different to express that difference.
eg. A GNU screen PKGBUILD submitted containing the sidebar patch, could be named screen-sidebar etc. Additionally the <strong>provides=('screen')</strong> PKGBUILD array should be used in order to avoid conflicts with the official package.
+
eg. A GNU screen PKGBUILD submitted containing the sidebar patch, could be named screen-sidebar etc. Additionally the '''provides=('screen')''' PKGBUILD array should be used in order to avoid conflicts with the official package.
 
         </li>
 
         </li>
 
<li>
 
<li>
To ensure the security of pkgs submitted to the AUR please <strong>ensure</strong> that you have correctly filled the <code>md5sum</code> field.  The <code>md5sum</code>'s can be generated using the <code>makepkg -g</code> command.
+
To ensure the security of pkgs submitted to the AUR please '''ensure''' that you have correctly filled the {{ic|md5sum}} field.  The {{ic|md5sum}}'s can be generated using the {{ic|makepkg -g}} command.
 
</li>
 
</li>
 
<li>
 
<li>
Please <strong>add a comment line</strong> to the top of your
+
Please '''add a comment line''' to the top of the
<code>PKGBUILD</code> file that follows this format.  Remember to disguise
+
{{ic|PKGBUILD}} file that follows this format.  Remember to disguise
 
                 your email to protect against spam:
 
                 your email to protect against spam:
  
<pre># Maintainer: Your Name <address at domain dot com></pre>
+
{{bc|# Maintainer: Your Name <address at domain dot com>}}
  
 
If you are assuming the role of maintainer for an existing PKGBUILD, add your name to the top as described above and change the title of the previous Maintainer(s) to Contributor:
 
If you are assuming the role of maintainer for an existing PKGBUILD, add your name to the top as described above and change the title of the previous Maintainer(s) to Contributor:
  
<pre># Maintainer: Your Name <address at domain dot com>
+
{{bc|# Maintainer: Your Name <address at domain dot com>
# Contributor: Previous Name <address at domain dot com></pre>
+
# Contributor: Previous Name <address at domain dot com>}}
  
 
</li>
 
</li>
 
<li>
 
<li>
Verify the package <strong>dependencies</strong> (eg, run
+
Verify the package '''dependencies''' (eg, run
<code>ldd</code> on dynamic executables, check tools required
+
{{ic|ldd}} on dynamic executables, check tools required
 
by scripts, etc).
 
by scripts, etc).
  
The TU team <strong>strongly</strong> recommend the use of the
+
The TU team '''strongly''' recommend the use of the
<code>namcap</code> utility, written by Jason Chu (jason@archlinux.org), to analyze the
+
{{ic|namcap}} utility, written by Jason Chu (jason@archlinux.org), to analyze the
sanity of your package. <code>namcap</code> will tell you about
+
sanity of packages. {{ic|namcap}} will warn you about
 
bad permissions, missing dependencies, un-needed dependencies,
 
bad permissions, missing dependencies, un-needed dependencies,
 
and other common mistakes. You can install the
 
and other common mistakes. You can install the
<code>namcap</code> package with <code>pacman</code>.
+
{{ic|namcap}} package with {{ic|pacman}}.
  
Remember <code>namcap</code> can be used to check both pkg.tar.gz files and PKGBUILDs
+
Remember {{ic|namcap}} can be used to check both pkg.tar.gz files and PKGBUILDs
 
</li>
 
</li>
<li> <strong>Dependencies</strong>
+
<li> '''Dependencies'''
 
are the most common packaging error. Namcap can help detect them, but
 
are the most common packaging error. Namcap can help detect them, but
 
it is not always correct. Verify dependencies by looking at source
 
it is not always correct. Verify dependencies by looking at source
 
documentation and the program website. </li>
 
documentation and the program website. </li>
<li>'''Don't use <tt>replaces</tt>''' in your PKGBUILD unless you want to rename your package, for example when ''Ethereal'' became ''Wireshark''. If you just provide an alternate version of an already existing package, use <tt>conflicts</tt> (and <tt>provides</tt> if that package is required by others). The main difference is: after syncing (-Sy) pacman immediately wants to replace an installed, 'offending' package upon encountering a package with the matching <tt>replaces</tt> anywhere in its repositories; <tt>conflicts</tt> on the other hand is only evaluated when actually installing the package, which is pretty much always the desired behavior because you don't push your package down other people's throat this way.</li>
+
<li>'''Do not use {{Ic|replaces}}''' in a PKGBUILD unless the package is to be renamed, for example when ''Ethereal'' became ''Wireshark''. If the package is an alternate version of an already existing package, use {{Ic|conflicts}} (and {{Ic|provides}} if that package is required by others). The main difference is: after syncing (-Sy) pacman immediately wants to replace an installed, 'offending' package upon encountering a package with the matching {{Ic|replaces}} anywhere in its repositories; {{Ic|conflicts}} on the other hand is only evaluated when actually installing the package, which is usually the desired behavior because it is less invasive.</li>
 
<li>
 
<li>
All files uploaded to the AUR should be contained in a <strong>compressed tar
+
All files uploaded to the AUR should be contained in a '''compressed tar
file</strong> containing a directory with the <strong><code>PKGBUILD</code></strong> and <strong>additional build files</strong> (patches, install, ...) in it.
+
file''' containing a directory with the '''{{ic|PKGBUILD}}''' and '''additional build files''' (patches, install, ...) in it.
<pre>foo/PKGBUILD
+
{{bc|foo/PKGBUILD
 
foo/foo.install
 
foo/foo.install
 
foo/foo_bar.diff
 
foo/foo_bar.diff
foo/foo.rc.conf</pre>
+
foo/foo.rc.conf}}
 
The archive name should contain the name of the package
 
The archive name should contain the name of the package
 
e.g. foo.tar.gz.
 
e.g. foo.tar.gz.
  
You can easily build a tarball containing all the required files by using <tt>makepkg --source</tt>. This
+
One can easily build a tarball containing all the required files by using {{Ic|makepkg --source}}. This
makes a tarball named <tt>$pkgname-$pkgver-$pkgrel.src.tar.gz</tt>, which you can then upload to the AUR.
+
makes a tarball named {{Ic|$pkgname-$pkgver-$pkgrel.src.tar.gz}}, which can then be uploaded to the AUR.
 
 
The tarball <strong>should not</strong> contain the binary tarball created by makepkg, nor should it contain the filelist
+
The tarball '''should not''' contain the binary tarball created by makepkg, nor should it contain the filelist
 
</li>
 
</li>
  
 
</ol>
 
</ol>
  
==Additional Guidelines==
+
==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.
+
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.
  
<h4>CVS/SVN Packages</h4>
+
===VCS (SVN, GIT, HG, etc) packages===
Please see the [[Arch CVS & SVN PKGBUILD guidelines]]
+
Please see the [[Arch CVS & SVN PKGBUILD guidelines|Arch VCS PKGBUILD guidelines]]
  
<h4>Eclipse Plugin Packages</h4>
+
===Eclipse plugin packages===
 
Please see the [[Eclipse plugin package guidelines]]
 
Please see the [[Eclipse plugin package guidelines]]
  
        <h4>Gnome Packages</h4>
+
===GNOME packages===
Please see the [[Gnome package guidelines]]
+
Please see the [[GNOME Package Guidelines]]
  
<h4>Haskell Packages</h4>
+
===Go packages===
 +
Please see the [[Go Package Guidelines]]
 +
 
 +
===Haskell packages===
 
Please see the [[Haskell package guidelines]]
 
Please see the [[Haskell package guidelines]]
  
<h4>Java Packages</h4>
+
===Java packages===
Please see the [[Java Package Guidelines]]
+
Please see the [[Java Package Guidelines]]
  
        <h4>Kernel Module Packages</h4>
+
===KDE packages===
 +
Please see the [[KDE Package Guidelines]]
 +
 
 +
===Kernel module packages===
 
Please see the [[Kernel Module Package Guidelines]]
 
Please see the [[Kernel Module Package Guidelines]]
  
        <h4>Lisp Packages</h4>
+
===Lisp packages===
 
Please see the [[Lisp Package Guidelines]]
 
Please see the [[Lisp Package Guidelines]]
  
        <h4>Perl Packages</h4>
+
===OCaml packages===
 +
Please see the [[OCaml_Package_Guidelines]]
 +
 
 +
===Perl packages===
 
Please see the [[Perl Package Guidelines]]
 
Please see the [[Perl Package Guidelines]]
  
        <h4>Python Packages</h4>
+
===Python packages===
 
Please see the [[Python Package Guidelines]]
 
Please see the [[Python Package Guidelines]]
  
        <h4>Ruby Gem Packages</h4>
+
===Ruby Gem packages===
 
Please see the [[Ruby Gem Package Guidelines]]
 
Please see the [[Ruby Gem Package Guidelines]]
  
        <h4>Wine Packages</h4>
+
===Wine packages===
 
Please see the [[Arch wine PKGBUILD guidelines]]
 
Please see the [[Arch wine PKGBUILD guidelines]]
 +
 +
===MinGW packages===
 +
Please see the [[MinGW PKGBUILD guidelines]]

Revision as of 04:09, 3 December 2012

The submitted PKGBUILDs must not build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in comparison to the official ones. In such an occasion, the pkgname array should be different.

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.

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=() #generate with 'makepkg -g'

build() {
  cd "$srcdir/$pkgname-$pkgver"

  ./configure --prefix=/usr
  make
}

package() {
  cd "$srcdir/$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 into 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://downloads.sourceforge.net/directxwine/$patchname.$patchver.diff.bz2

    Such a situation defeats the effective functionality of the AUR.

  • 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.
  • Any optional dependencies that are not needed to run the package or have it generally function should not be included; 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.

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 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 Application binaries
    /usr/sbin System 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 such as Java, etc.

  • Package should not contain following directories:
    • /dev
    • /home
    • /srv
    • /media
    • /mnt
    • /proc
    • /root
    • /selinux
    • /sys
    • /tmp
    • /var/tmp

Makepkg duties

When makepkg is used to build a package, it does the following automatically:

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

Architectures

The arch array should contain 'i686' and/or 'x86_64' depending on which architectures it can be built on. You can also use 'any' for architecture independent packages.

Licenses

The license array is being implemented in the official repos, and it should be used in your packages as well. Use it as follows:

  • A licenses package has been created in [core] that stores common 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 in /usr/share/licenses/$pkgname/ e.g. /usr/share/licenses/dibfoo/LICENSE. One good way to do this is by using:
      install -D -m644 LICENSE "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE"
    2. If the source tarball does NOT contain the license details and the license is only displayed on a website for example, then 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, 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 is treated like a common license (license=('BSD'), license=('MIT'), license=('ZLIB') or license=('Python')) but for the sake of the filesystem, it is 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. 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.
  • 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

Submitting packages to the AUR

Note the following before submitting any packages to the AUR:

  1. The submitted PKGBUILDs MUST NOT build applications already in any of the official binary repositories under any circumstances. Exception to this strict rule may only be packages having extra features enabled and/or patches in compare to the official ones. In such an occasion the pkgname array should be different to express that difference. eg. A GNU screen PKGBUILD submitted containing the sidebar patch, could be named screen-sidebar etc. Additionally the provides=('screen') PKGBUILD array should be used in order to avoid conflicts with the official package.
  2. 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.
  3. Please add a comment line to the top of the PKGBUILD file that follows this format. Remember to disguise your email to protect against spam:
    # Maintainer: Your Name <address at domain dot com>

    If you are assuming the role of maintainer for an existing PKGBUILD, add your name to the top as described above and change the title of the previous Maintainer(s) to Contributor:

    # Maintainer: Your Name <address at domain dot com>
    # Contributor: Previous Name <address at domain dot com>
  4. 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 packages. namcap will warn 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
  5. 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.
  6. Do not use replaces in a PKGBUILD unless the package is to be renamed, for example when Ethereal became Wireshark. If the package is an alternate version of an already existing package, use conflicts (and provides if that package is required by others). The main difference is: after syncing (-Sy) pacman immediately wants to replace an installed, 'offending' package upon encountering a package with the matching replaces anywhere in its repositories; conflicts on the other hand is only evaluated when actually installing the package, which is usually the desired behavior because it is less invasive.
  7. 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.

    One can easily build a tarball containing all the required files by using makepkg --source. This makes a tarball named $pkgname-$pkgver-$pkgrel.src.tar.gz, which can then be uploaded to the AUR.

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

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.

VCS (SVN, GIT, HG, etc) packages

Please see the Arch VCS PKGBUILD guidelines

Eclipse plugin packages

Please see the Eclipse plugin package guidelines

GNOME packages

Please see the GNOME Package Guidelines

Go packages

Please see the Go Package Guidelines

Haskell packages

Please see the Haskell package guidelines

Java packages

Please see the Java Package Guidelines

KDE packages

Please see the KDE Package Guidelines

Kernel module packages

Please see the Kernel Module Package Guidelines

Lisp packages

Please see the Lisp Package Guidelines

OCaml packages

Please see the OCaml_Package_Guidelines

Perl packages

Please see the Perl Package Guidelines

Python packages

Please see the Python Package Guidelines

Ruby Gem packages

Please see the Ruby Gem Package Guidelines

Wine packages

Please see the Arch wine PKGBUILD guidelines

MinGW packages

Please see the MinGW PKGBUILD guidelines