---
name: maintaining-aur-packages
description: 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.
user-invocable: true
license: LicenseRef-MutuaL-1.2
metadata:
  author: Amolith <amolith@secluded.site>
---

## Code style

- PKGBUILD is bash; `.install` files are POSIX-sh–compatible functions
- Indent 2 spaces; UTF-8; LF endings; no trailing whitespace
- Single quotes for literals; double quotes when expanding variables
- Quote variables: `"$pkgdir"`, `"$srcdir"`, and all paths
- Prefix custom PKGBUILD variables with `_` to avoid collisions with makepkg internals
- Arrays: `arch`, `license`, `provides`, `conflicts` use `( ... )` syntax
- `arch=('x86_64')` for compiled packages; `arch=('any')` for arch-independent ones
- `license=()` must use [SPDX identifiers](https://spdx.org/licenses/)
- Functions: `prepare()`, `build()`, `check()`, `package()`; only define the ones needed
- No `sudo`, networking, or user config in `build`/`package` functions
- Use `install -Dm755` for binaries; set exact modes explicitly
- Keep checksums in sync with sources
- Keep `.SRCINFO` in lockstep with PKGBUILD; never commit build artifacts

## Package types

When the working directory contains subdirectories with these suffixes, we're maintaining multiple packages for the same software:

- **suffix-less**: Downloads a release archive, builds, and installs from source
- **`-bin`**: Downloads the project's pre-built binary and installs it
- **`-git`**: Clones the primary branch and builds from source; version is determined by `updpkgsums`, not specified manually

If no subdirectories exist, we're maintaining a single package. The current directory name indicates which type.

## Constraints

- 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.
- Use `updpkgsums` for checksums
- Use `namcap` to lint built `.pkg.tar.zst` files
- Use `b2sums` for all packages.

## Creating packages

Follow 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.

1. List the contents of the current working directory.
   - Read any text files present.
   - List subdirectory contents (ignore what looks like the upstream project repo).
   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages for the same software.

2. 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.
   - **`-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:
     ```bash
     pkgver() {
       cd "$pkgname" || exit
       ( set -o pipefail
         git describe --long --abbrev=7 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||
         printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)"
       )
     }
     ```
   - **`-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.

3. 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'`).

4. 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).

5. Adapt those instructions for each package's `build()`, `check()`, `package()`, etc. See [build-patterns.md](references/build-patterns.md) for language-specific templates.

6. Present **all** diagnostics, whether seemingly relevant or not, with reasoning for each. Resolve genuine issues before proceeding. Some issues are expected for AUR packages.

7. Update checksums with `updpkgsums` in each package directory.

8. Run `makepkg -Cf` yourself. Work through any build issues.

9. Run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.

10. Give the user a copyable `makepkg -csi` command (with `cd` if multiple packages). This handles deps, rebuild, and installation in one step.

11. Run `makepkg --printsrcinfo > .SRCINFO` (with `cd` if multiple packages).

12. 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.

13. Clean all artifacts with `git clean -fdx`.

## Updating packages

Follow this strict workflow.

1. List the contents of the current working directory.
   - Read any text files present.
   - List subdirectory contents (ignore what looks like the upstream project repo).
   - Subdirectories with `-bin` or `-git` suffixes mean multiple packages.

2. We're upgrading to version `$VERSION`. Read the PKGBUILD(s), then edit the version number for non-`-git` packages.

3. Update checksums with `updpkgsums`.

4. Present **all** diagnostics with reasoning. Resolve genuine issues before proceeding.

5. Run `makepkg -Cf`. Work through any build issues.

6. Run `namcap` on `./package-name-*.pkg.tar.zst`. Report all issues with reasoning.

7. Give the user a copyable `makepkg -csi` command (with `cd` if multiple packages).

8. Run `makepkg --printsrcinfo > .SRCINFO` (with `cd` if multiple packages).

9. 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.

10. Clean all artifacts with `git clean -fdx`.

If anything other than `pkgver` is edited during the update, re-run `shellcheck` and `namcap` as appropriate.