1---
  2name: maintaining-aur-packages
  3description: Creates and updates AUR packages following Arch packaging standards. Use when creating new AUR packages, updating existing AUR PKGBUILDs, bumping package versions, or when the user mentions AUR, PKGBUILD, makepkg, pacman packaging, or Arch Linux packages.
  4---
  5
  6## Code style
  7
  8- PKGBUILD is bash; `.install` files are POSIX-sh–compatible functions
  9- Indent 2 spaces; UTF-8; LF endings; no trailing whitespace
 10- Single quotes for literals; double quotes when expanding variables
 11- Quote variables: `"$pkgdir"`, `"$srcdir"`, and all paths
 12- Prefix custom PKGBUILD variables with `_` to avoid collisions with makepkg internals
 13- Arrays: `arch`, `license`, `provides`, `conflicts` use `( ... )` syntax
 14- `arch=('x86_64')` for compiled packages; `arch=('any')` for arch-independent ones
 15- `license=()` must use [SPDX identifiers](https://spdx.org/licenses/)
 16- Functions: `prepare()`, `build()`, `check()`, `package()`; only define the ones needed
 17- No `sudo`, networking, or user config in `build`/`package` functions
 18- Use `install -Dm755` for binaries; set exact modes explicitly
 19- Keep checksums in sync with sources
 20- Keep `.SRCINFO` in lockstep with PKGBUILD; never commit build artifacts
 21
 22## Package types
 23
 24When the working directory contains subdirectories with these suffixes, we're maintaining multiple packages for the same software:
 25
 26- **suffix-less**: Downloads a release archive, builds, and installs from source
 27- **`-bin`**: Downloads the project's pre-built binary and installs it
 28- **`-git`**: Clones the primary branch and builds from source; version is determined by `updpkgsums`, not specified manually
 29
 30If no subdirectories exist, we're maintaining a single package. The current directory name indicates which type.
 31
 32## Constraints
 33
 34- The agent **cannot run `makepkg`**. Always give the user a copyable code block of `makepkg` commands instead.
 35- Same applies to `makepkg --printsrcinfo > .SRCINFO`.
 36- Use `updpkgsums` for checksums (agent can run this).
 37- Use `namcap` to lint built `.pkg.tar.zst` files (agent can run this).
 38- Use `b2sums` for all packages.
 39
 40## Creating packages
 41
 42Follow this strict workflow. If a planning or todo tool is available, fill it
 43out in detail; the session might get interrupted and need to resume.
 44
 451. List the contents of the current working directory.
 46   - Read any text files present.
 47   - List subdirectory contents (ignore what looks like the upstream project repo).
 48   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages for the same software.
 49
 502. Ask for: package name (`provides=`), description (`pkgdesc=`), license (`license=()`), and the license path inside the project repo (for `install`ing). For each non-`-git` package, ask for the current version and source URL.
 51   - **`-git` packages**: Use `"$pkgname::git+https://...#branch=BRANCH"` as the source entry (the `$pkgname::` prefix ensures makepkg clones into a directory matching `$pkgname`; the `#branch=` fragment selects the branch). Add `git` to `makedepends`. Use `b2sums=('SKIP')` — VCS sources have no static content to checksum. Include this versioning function:
 52     ```bash
 53     pkgver() {
 54       cd "$pkgname" || exit
 55       ( set -o pipefail
 56         git describe --long --abbrev=7 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||
 57         printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)"
 58       )
 59     }
 60     ```
 61   - **`-bin` packages**: Use `bin-name-$pkgver::https://...` in `source`, then `install` `bin-name-$pkgver` as `bin-name`. Obtain the license from the original repo. For GitHub sources, the raw URL is `https://raw.githubusercontent.com/USER/REPO/refs/tags/{TAG}/LICENSE`. For non-GitHub sources, ask for the raw tagged LICENSE URL.
 62
 633. Write a `PKGBUILD` for each package. `Maintainer` comment: `Amolith <amolith@secluded.site>`. If multiple packages, include `conflicts=()` so they can't coexist. Packages with `-git` or `-bin` suffixes use versioned provides: `provides=("pkgname=${pkgver}")`. Use `b2sums` (except `-git` sources, which use `'SKIP'`).
 64
 654. Ask to find and relay the build system/installation methods recommended by the project (e.g. `cargo` for Rust, `go` for Go).
 66
 675. Adapt those instructions for each package's `build()`, `check()`, `package()`, etc. See [build-patterns.md](references/build-patterns.md) for language-specific templates.
 68
 696. Present **all** diagnostics, whether seemingly relevant or not, with reasoning for each. Resolve genuine issues before proceeding.
 70
 717. Update checksums with `updpkgsums` in each package directory.
 72
 738. Give the user a copyable code block of `makepkg -Ccsi` commands. Include `cd` if multiple packages. Work through any build issues.
 74
 759. After the user builds, run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.
 76
 7710. Give the user `makepkg --printsrcinfo > .SRCINFO` commands (with `cd` if multiple packages).
 78
 7911. If only PKGBUILDs and `.SRCINFO`s were created, enter each package directory and `git add` + `git commit` them. If other tracked files were modified, show the diff and ask which to commit. Create a `.gitignore` in each repo listing everything not committed, using appropriate globs.
 80
 8112. Clean all artifacts with `git clean -fdx`.
 82
 83## Updating packages
 84
 85Follow this strict workflow.
 86
 871. List the contents of the current working directory.
 88   - Read any text files present.
 89   - List subdirectory contents (ignore what looks like the upstream project repo).
 90   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages.
 91
 922. We're upgrading to version `$VERSION`. Read the PKGBUILD(s), then edit the version number for non-`-git` packages.
 93
 943. Update checksums with `updpkgsums`.
 95
 964. Present **all** diagnostics with reasoning. Resolve genuine issues before proceeding.
 97
 985. Give the user a copyable code block of `makepkg -Ccsi` commands. Include `cd` if multiple packages. Work through any build issues.
 99
1006. After the user builds, run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.
101
1027. Give the user `makepkg --printsrcinfo > .SRCINFO` commands.
103
1048. If only `PKGBUILD` and `.SRCINFO` were modified, `git add` and `git commit` them. If other tracked files were modified, show the diff and ask which to commit.
105
1069. Clean all artifacts with `git clean -fdx`.
107
108If anything other than `pkgver` is edited during the update, re-run `shellcheck` and `namcap` as appropriate.