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.
  4user-invocable: true
  5license: LicenseRef-MutuaL-1.2
  6metadata:
  7  author: Amolith <amolith@secluded.site>
  8---
  9
 10## Code style
 11
 12- PKGBUILD is bash; `.install` files are POSIX-sh–compatible functions
 13- Indent 2 spaces; UTF-8; LF endings; no trailing whitespace
 14- Single quotes for literals; double quotes when expanding variables
 15- Quote variables: `"$pkgdir"`, `"$srcdir"`, and all paths
 16- Prefix custom PKGBUILD variables with `_` to avoid collisions with makepkg internals
 17- Arrays: `arch`, `license`, `provides`, `conflicts` use `( ... )` syntax
 18- `arch=('x86_64')` for compiled packages; `arch=('any')` for arch-independent ones
 19- `license=()` must use [SPDX identifiers](https://spdx.org/licenses/)
 20- Functions: `prepare()`, `build()`, `check()`, `package()`; only define the ones needed
 21- No `sudo`, networking, or user config in `build`/`package` functions
 22- Use `install -Dm755` for binaries; set exact modes explicitly
 23- Keep checksums in sync with sources
 24- Keep `.SRCINFO` in lockstep with PKGBUILD; never commit build artifacts
 25
 26## Package types
 27
 28When the working directory contains subdirectories with these suffixes, we're maintaining multiple packages for the same software:
 29
 30- **suffix-less**: Downloads a release archive, builds, and installs from source
 31- **`-bin`**: Downloads the project's pre-built binary and installs it
 32- **`-git`**: Clones the primary branch and builds from source; version is determined by `updpkgsums`, not specified manually
 33
 34If no subdirectories exist, we're maintaining a single package. The current directory name indicates which type.
 35
 36## Constraints
 37
 38- You **cannot** interactively authenticate to execute `makepkg` in a way that requires escalation. You do the non-privileged work (build with `makepkg -Cf`, lint with `namcap`, generate `.SRCINFO`), then give the user a single copyable `makepkg -csi` command.
 39- Use `updpkgsums` for checksums
 40- Use `namcap` to lint built `.pkg.tar.zst` files
 41- Use `b2sums` for all packages.
 42
 43## Creating packages
 44
 45Follow this strict workflow. If a planning or todo tool is available, fill it out in detail; the session might get interrupted and need to resume.
 46
 471. List the contents of the current working directory.
 48   - Read any text files present.
 49   - List subdirectory contents (ignore what looks like the upstream project repo).
 50   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages for the same software.
 51
 522. 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.
 53   - **`-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:
 54     ```bash
 55     pkgver() {
 56       cd "$pkgname" || exit
 57       ( set -o pipefail
 58         git describe --long --abbrev=7 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||
 59         printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)"
 60       )
 61     }
 62     ```
 63   - **`-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.
 64
 653. Write a `PKGBUILD` for each package. Set the `# Maintainer:` comment at the top to the user's email address. If you don't know it, ask. If multiple packages, include `conflicts=()` as appropriate 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'`).
 66
 674. Find or ask the user to find and relay the build system/installation methods recommended by the project (e.g. `cargo` for Rust, `go` for Go).
 68
 695. Adapt those instructions for each package's `build()`, `check()`, `package()`, etc. See [build-patterns.md](references/build-patterns.md) for language-specific templates.
 70
 716. Present **all** diagnostics, whether seemingly relevant or not, with reasoning for each. Resolve genuine issues before proceeding. Some issues are expected for AUR packages.
 72
 737. Update checksums with `updpkgsums` in each package directory.
 74
 758. Run `makepkg -Cf` yourself. Work through any build issues.
 76
 779. Run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.
 78
 7910. Give the user a copyable `makepkg -csi` command (with `cd` if multiple packages). This handles deps, rebuild, and installation in one step.
 80
 8111. Run `makepkg --printsrcinfo > .SRCINFO` (with `cd` if multiple packages).
 82
 8312. 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.
 84
 8513. Clean all artifacts with `git clean -fdx`.
 86
 87## Updating packages
 88
 89Follow this strict workflow.
 90
 911. List the contents of the current working directory.
 92   - Read any text files present.
 93   - List subdirectory contents (ignore what looks like the upstream project repo).
 94   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages.
 95
 962. We're upgrading to version `$VERSION`. Read the PKGBUILD(s), then edit the version number for non-`-git` packages.
 97
 983. Update checksums with `updpkgsums`.
 99
1004. Present **all** diagnostics with reasoning. Resolve genuine issues before proceeding.
101
1025. Run `makepkg -Cf`. Work through any build issues.
103
1046. Run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.
105
1067. Give the user a copyable `makepkg -csi` command (with `cd` if multiple packages).
107
1088. Run `makepkg --printsrcinfo > .SRCINFO` (with `cd` if multiple packages).
109
1109. 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.
111
11210. Clean all artifacts with `git clean -fdx`.
113
114If anything other than `pkgver` is edited during the update, re-run `shellcheck` and `namcap` as appropriate.