View source for Manjaro Packaging Standards

<languages/>
__TOC__
<translate>
<!--T: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 comparison to the official ones. In such an occasion, the pkgname array should be different.'''

<!--T:2-->
When building packages for Manjaro Linux, '''adhere to the package guidelines''' below, especially if the intention is
to '''contribute''' a new package
to Manjaro Linux. You should also see the [https://archlinux.org/pacman/PKGBUILD.5.html PKGBUILD] and
[https://archlinux.org/pacman/makepkg.8.html makepkg] manpages.
</translate>
<translate>
==PKGBUILD prototype== <!--T:3-->
{{bc|1=
# 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

<!--T:4-->
build() {
  cd $pkgname-$pkgver

  <!--T:5-->
./configure --prefix=/usr
  make
}

<!--T:6-->
package() {
  cd $pkgname-$pkgver

  <!--T:7-->
make DESTDIR="$pkgdir/" install
}
}}

<!--T:8-->
Other prototypes are found in {{ic|/usr/share/pacman}} from the pacman and abs packages.
</translate>
<translate>
==Package etiquette== <!--T:9-->

	<!--T:10-->
<ul>
	<li>Packages should '''never''' be installed to {{ic|/usr/local}}</li>
	<li>
		'''Do not introduce new variables''' into
		{{ic|PKGBUILD}} build scripts, unless the package cannot be built without doing so, as these could
		possibly '''conflict''' with variables used
		in makepkg itself.

		<!--T:11-->
If a new variable is absolutely required,
		'''prefix the variable name with an underscore''' ({{ic|_}}), e.g.
		{{bc|1=_customvariable=}}

		<!--T:12-->
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.
		{{bc|<nowiki>http://downloads.sourceforge.net/directxwine/$patchname.$patchver.diff.bz2</nowiki>}}
		Such a situation defeats the effective functionality of the AUR.
	</li>

	<!--T:13-->
<li>
		'''Avoid''' using {{ic|/usr/libexec/}} for
		anything. Use {{ic|/usr/lib/${pkgname}/}} instead.
	</li>
	<li>
		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}}

		<!--T:14-->
file, or alternatively override it by creating ~/.makepkg.conf

	<!--T:15-->
</li>
<li>
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>
            <li>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 <b>optdepends</b> array:
{{bc|1=
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')
}}

<!--T:16-->
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
one should <b>not</b> keep this kind of information in .install files.

<!--T:17-->
</li>
        <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>
<li>Try to keep the '''line length''' in the PKGBUILD below ~100 characters.</li>
	<li>Where possible, '''remove empty lines''' from the {{ic|PKGBUILD}} ({{ic|provides}}, {{ic|replaces}}, etc.)</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>

</translate>
<translate>
==Package naming== <!--T:18-->
* Package names should consist of '''alphanumeric characters only'''; 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'''.
</translate>
<translate>
==Directories== <!--T:19-->
* '''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/}}).	

<!--T:20-->
* Package files should follow these '''general directory guidelines''':

<!--T:21-->
:{|
|-
| {{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 such as Java, etc.
|}

<!--T:22-->
* Packages should not contain any of the following directories:
** {{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}}
</translate>
<translate>
==Makepkg duties== <!--T:23-->

	<!--T:24-->
<p>
		When [[makepkg]] is used to build a package, it does the
		following automatically:
	</p>

	<!--T:25-->
<ol>
	<li>
		Checks if package '''dependencies''' and '''makedepends''' are installed	
	</li>
	<li>
		'''Downloads source''' files from servers
	</li>
	<li>
		'''Checks the integrity''' of source files
	</li>
	<li>
		'''Unpacks''' source files
	</li>
	<li>
		Does any necessary '''patching'''
	</li>
	<li>

		<!--T:26-->
'''Builds''' the software and installs it in a fake
		root
	</li>
	<li>
		'''Strips''' symbols from binaries
	</li>
	<li>
		'''Strips''' debugging symbols from libraries
	</li>
	<li>
		'''Compresses''' manual and, or info pages
	</li>
	<li>
		Generates the '''package meta file''' which is included with each package
	</li>

	<!--T:27-->
<li>
		'''Compresses''' the fake root into the package file
	</li>
	<li>
		'''Stores''' the package file in the configured destination directory (<span title="Current Working Directory" style="border-bottom:1px dotted">cwd</span> by default)
	</li>

	<!--T:28-->
</ol>
</translate>
<translate>
==Architectures== <!--T:29-->
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.
</translate>
<translate>
==Licenses== <!--T:30-->
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>
<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:
<ol>
<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:
{{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>
</ol></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 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>The (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:</li>
<ul>
<li>(L)GPL - (L)GPLv2 or any later version</li>
<li>(L)GPL2 - (L)GPL2 only</li>
<li>(L)GPL3 - (L)GPL3 or any later version</li>
</ul>
</li>
</ul>
</translate>
<translate>
==Submitting packages to the AUR== <!--T:31-->
	<p>Note the following before submitting any packages to the AUR:</p>

	<!--T:32-->
<ol>
        <li>
                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.
        </li>
	<li>
		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|updpkgsums}} command.
	</li>
	<li>
		Please '''add a comment line''' to the top of the
		{{ic|PKGBUILD}} file that follows this format.  Remember to disguise
                your email to protect against spam:

<!--T:33-->
{{bc|# Maintainer: Your Name <address at domain dot com>}}

<!--T:34-->
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:

<!--T:35-->
{{bc|# Maintainer: Your Name <address at domain dot com>
# Contributor: Previous Name <address at domain dot com>}}

	<!--T:36-->
</li>
	<li>
		Verify the package '''dependencies''' (eg, run
		{{ic|ldd}} on dynamic executables, check tools required
		by scripts, etc).

		<!--T:37-->
The TU team '''strongly''' recommend the use of the
		{{ic|namcap}} utility, written by Jason Chu (jason@archlinux.org), to analyze the
		sanity of packages. {{ic|namcap}} will warn you about
		bad permissions, missing dependencies, un-needed dependencies,
		and other common mistakes. You can install the
		{{ic|namcap}} package with {{ic|pacman}}.

		<!--T:38-->
Remember {{ic|namcap}} can be used to check both pkg.tar.gz files and PKGBUILDs
	</li>
<li> '''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. </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>
		All files uploaded to the AUR should be contained in a '''compressed tar
			file''' containing a directory with the '''{{ic|PKGBUILD}}''' and '''additional build files''' (patches, install, ...) in it.
{{bc|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.

<!--T:39-->
One can easily build a tarball containing all the required files by using {{Ic|makepkg --source}}. This
makes a tarball named {{Ic|$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
	</li>

	<!--T:40-->
</ol>
</translate>

[[Category:Contents Page{{#translation:}}]]