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
• 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 installing). 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:

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