AUR submission guidelines

Related articles
Arch package guidelines
Package Maintainer guidelines
Users can
share
PKGBUILD
scripts using the
Arch User Repository
.  It does not contain any binary packages but allows users to upload
PKGBUILD
s that can be downloaded by others. These
PKGBUILD
s are completely unofficial and have not been thoroughly vetted, so they should be used at your own risk.
Submitting packages
Warning
Before attempting to submit a package you are expected to familiarize yourself with
Arch package guidelines
and
PKGBUILD
.
Verify carefully
that what you are uploading is correct. Packages that
violate the rules
may be
deleted without warning
.
If you are unsure in any way about the package or the build/submission process even after reading this section twice, submit the
PKGBUILD
to the
AUR mailing list
, the
AUR forum
on the Arch forums, or ask on our
IRC channel
for public review before adding it to the AUR.
Rules of submission
When submitting a package to the AUR, observe the following rules:
The submitted
PKGBUILD
s must not build applications
already in any
of the
official
binary
repositories
under any circumstances. Check the
official package database
for the package. If any version of it exists,
do not
submit the package. If the official package is out-of-date, flag it as such. If the official package is broken or is lacking a feature, then please
file a bug report
.
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
should be different to express that difference. For example, a package for GNU screen containing the sidebar patch could be named
screen-sidebar
. Additionally the
conflicts=('screen')
array should be used in order to avoid conflicts with the official package.
Check the AUR
if the package
already exists
. If it is currently maintained, changes can be submitted in a comment for the maintainer's attention. If it is unmaintained or the maintainer is unresponsive, the package can be adopted and updated as required. Do not create duplicate packages.
Make sure the package you want to upload is
useful
. Will anyone else want to use this package? Is it extremely specialized? If more than a few people would find this package useful, it is appropriate for submission.
The AUR and official repositories are intended for packages which install general software and software-related content, including one or more of the following: executable(s); configuration file(s); online or offline documentation for specific software or the Arch Linux distribution as a whole; media intended to be used directly by software.
Packages that do not support the
x86_64
architecture are
not allowed in the AUR
.
Do not use
replaces
in an AUR
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.
Packages that build from a version control system and are not tied to a specific version need to have an appropriate suffix,
-git
for git and so on, see
VCS package guidelines#Package naming
for a full list.
Packages that use
prebuilt
deliverables
, when the sources are available, must use the
-bin
suffix. An exception to this is with
Java
. The AUR should not contain the binary tarball created by makepkg, nor should it contain the filelist. If you are packaging a non-free software, see also
Nonfree applications package guidelines#Package naming
regarding usage of
-bin
suffix.
Packages that build from source using a specific version do not use a suffix.
Please add a
comment line
to the top of the
PKGBUILD
file which contains information about the current
maintainers
and previous
contributors
, respecting the following format. Remember to disguise your email to protect against spam. Additional lines are optional.
Note
The use of obfuscation when it comes to email addresses makes it difficult for people to contact you.
If you are assuming the role of maintainer for an existing
PKGBUILD
, add your name to the top like this
# Maintainer: Your Name <address at domain dot tld>
If there were previous maintainers, put them as contributors. The same applies for the original submitter if this is not you. If you are a co-maintainer, add the names of the other current maintainers as well.
# Maintainer: Your name <address at domain dot tld>
# Maintainer: Other maintainer's name <address at domain dot tld>
# Contributor: Previous maintainer's name <address at domain dot tld>
# Contributor: Original submitter's name <address at domain dot tld>
Add a
LICENSE
file and/or a
REUSE.toml
file to your repository. You are encouraged to follow the
Arch package guidelines#Package sources licenses
and license your submission under the
0BSD license
.
Note
Packages missing a license or containing a different license than
0BSD
are
not eligible
for promotion to the
official repositories
.
Authentication
For write access to the AUR, you need to have an
SSH key pair
. The content of the public key needs to be copied to your profile in
My Account
, and the corresponding private key configured for the
aur.archlinux.org
host. For example:
~/.ssh/config
Host aur.archlinux.org
  IdentityFile ~/.ssh/aur
  User aur
You should
create a new key pair
rather than use an existing one, so that you can selectively revoke the keys should something happen:
$ ssh-keygen -f ~/.ssh/aur
Tip
You can add multiple public keys to your profile by separating them with a newline in the input field.
Creating package repositories
If you are
creating a new package
from scratch, establish a local
Git
repository and an AUR remote by
cloning
the intended
pkgbase
. If the package does not yet exist, the following warning is expected:
$ git -c init.defaultBranch=master clone ssh://aur@aur.archlinux.org/
pkgbase
.git
Cloning into '
pkgbase
'...
warning: You appear to have cloned an empty repository.
Checking connectivity... done.
Note
The repository will not be empty if
pkgbase
matches a
deleted
package.
If you already have a package,
initialize it
as a Git repository if it is not one:
$ git -c init.defaultBranch=master init
and add an AUR remote:
$ git remote add
label
ssh://aur@aur.archlinux.org/
pkgbase
.git
Then
fetch
this remote to initialize it in the AUR.
Note
Pull and rebase
to resolve conflicts if
pkgbase
matches a deleted package.
Publishing new package content
Warning
Your commits will be authored with your
global Git name and email address
. It is very difficult to change commits after pushing them (
FS#45425
). If you want to push to the AUR under different credentials, you can change them per package with
git config user.name "..."
and
git config user.email "..."
.
When releasing a new version of the packaged software, update the
pkgver
or
pkgrel
variables to notify all users that an upgrade is needed. Do not update those values if only minor changes to the
PKGBUILD
such as the correction of a typo are being published.
Do not commit mere
pkgver
bumps for
VCS packages
. They are not considered out of date when the upstream has new commits. Only do a new commit when other changes are introduced, such as changing the build process.
Be sure to regenerate
.SRCINFO
whenever
PKGBUILD
metadata changes, such as
pkgver()
updates; otherwise the AUR will not show updated version numbers.
To upload or update a package:
add
at least
PKGBUILD
and
.SRCINFO
,
add any additional new or modified helper files (such as
.install
files or
local source files
such as
patches
),
add a
package source license
,
commit
with a meaningful commit message,
push
the changes to the AUR.
For example:
$ makepkg --printsrcinfo > .SRCINFO
$ git add PKGBUILD .SRCINFO
$ git commit -m "
useful commit message
"
$ git push
Note
If
.SRCINFO
was not included in your last commit, add it by
changing your last commit
with
git commit --amend
so the AUR will permit your push.
The AUR only allows pushes to the
master
branch. If the local branch is named something else,
rename
it and push again.
Tip
To keep the working directory and commits as clean as possible, create a
gitignore(5)
that excludes all files and force-add files as needed.
Maintaining packages
Check for feedback and comments from other users and try to incorporate any improvements they suggest; consider it a learning process!
Please do not leave a comment containing the version number every time you update the package. This keeps the comment section usable for valuable content mentioned above.
Please do not just submit and forget about packages! It is the maintainer's job to maintain the package by checking for updates and improving the
PKGBUILD
.
If you do not want to continue to maintain the package for some reason,
disown
the package using the AUR web interface and/or post a message to the AUR Mailing List. If all maintainers of an AUR package disown it, it will become an
"orphaned"
package.
Automation is a valuable tool for maintainers, but it can not replace
manual intervention
(e.g. projects can change license, add or remove dependencies, and other notable changes even for "minor" releases). Automated
PKGBUILD
updates are used at your own risk and any malfunctioning accounts and their packages may be removed without prior notice.
Requests
Deletion, merge, and orphan requests can be created by clicking on the "Submit Request" link under "Package Actions" on the right hand side. This dispatches notification emails to the current package maintainer and to the
aur-requests mailing list
for discussion.
Package Maintainers
will then either accept or reject the request.
Deletion
Request to
unlist
a
pkgbase
from the AUR. A short note explaining the reason for deletion is required, as well as supporting details (like when a package is provided by another package, if you are the maintainer yourself, it is renamed and the original owner agreed, etc).
Note
It is not sufficient to explain why a package is up for deletion only in its comments: as soon as a package maintainer takes action, the only place where such information can be obtained is the aur-requests mailing list.
Deletion requests can be rejected, in which case if you are the maintainer you will likely be advised to disown the package to allow adoption by another maintainer.
After a package is "deleted", its
git
repository remains available for
cloning
.
Merge
Request to delete a
pkgbase
and transfer its votes and comments to another
pkgbase
. The name of the package to merge into is required.
This is the action to use if, for example, an upstream has
renamed their project
.
Note
This has nothing to do with
git merge
or GitLab's merge requests.
As the transfer of the votes and comments requires an already existing destination, if a package has no votes or comments, a
deletion
request
linking to the new package
is identical.
Orphan
Request that a
pkgbase
be disowned. These requests will be granted after two weeks if the current maintainer did not react. The exception is if a package was flagged out-of-date for at least 180 days; orphan requests are then automatically accepted.