Arch Linux PKGBUILD Creation

Overview

PKGBUILD files are Arch Linux package build scripts with strict validation requirements. This skill ensures compliance with Arch package guidelines, FHS (Filesystem Hierarchy Standard), and mandatory namcap testing.

Core principle: Every PKGBUILD MUST pass namcap validation for both the PKGBUILD file AND the generated package before deployment.

Sub-Skills Available

This skill is split into specialized sub-skills for different package types:

Load sub-skills as needed using the skill tool when working with these specialized package types.

Mandatory Workflow

digraph pkgbuild_workflow {
    "Start: Package request" [shape=doublecircle];
    "1. Check existing packages" [shape=box];
    "2. Write PKGBUILD" [shape=box];
    "3. Run namcap on PKGBUILD" [shape=box];
    "PKGBUILD passes?" [shape=diamond];
    "devtools installed?" [shape=diamond];
    "4a. Build in clean chroot" [shape=box];
    "4b. Build with makepkg (warn user)" [shape=box];
    "5. Run namcap on package" [shape=box];
    "Package passes?" [shape=diamond];
    "6. Test installation" [shape=box];
    "7. Generate .SRCINFO" [shape=box];
    "Complete" [shape=doublecircle];
    "Fix violations" [shape=box];

    "Start: Package request" -> "1. Check existing packages";
    "1. Check existing packages" -> "2. Write PKGBUILD";
    "2. Write PKGBUILD" -> "3. Run namcap on PKGBUILD";
    "3. Run namcap on PKGBUILD" -> "PKGBUILD passes?";
    "PKGBUILD passes?" -> "Fix violations" [label="NO"];
    "Fix violations" -> "3. Run namcap on PKGBUILD";
    "PKGBUILD passes?" -> "devtools installed?" [label="YES"];
    "devtools installed?" -> "4a. Build in clean chroot" [label="YES (preferred)"];
    "devtools installed?" -> "4b. Build with makepkg (warn user)" [label="NO"];
    "4a. Build in clean chroot" -> "5. Run namcap on package";
    "4b. Build with makepkg (warn user)" -> "5. Run namcap on package";
    "5. Run namcap on package" -> "Package passes?";
    "Package passes?" -> "Fix violations" [label="NO"];
    "Package passes?" -> "6. Test installation" [label="YES"];
    "6. Test installation" -> "7. Generate .SRCINFO";
    "7. Generate .SRCINFO" -> "Complete";
}

Building Methods: Clean Chroot vs Direct makepkg

PREFERRED METHOD: Clean Chroot Building

Building in a clean chroot prevents:

• •Missing dependencies (unwanted linking from your system)
• •Incomplete depends=() arrays
• •Building for stable repos while having testing packages installed

When to use each method:

CRITICAL: If using direct makepkg, ALWAYS warn the user that the package was NOT built in a clean chroot and may have incorrect dependencies.

Clean Chroot Quick Start

One-command build (recommended for most users):

# For AUR/extra packages (most common)
extra-x86_64-build

# The script automatically:
# - Creates chroot in /var/lib/archbuild/ (if needed)
# - Updates the chroot
# - Builds your package in isolation
# - Use -c flag to reset chroot if needed

Available build scripts:

Common flags:

• •-c : Clean/reset the chroot before building (use after breakage)
• •-I package.pkg.tar.zst : Pre-install custom dependencies

Example with custom dependencies:

# Build package that depends on another custom package
extra-x86_64-build -- -I ~/custom-dep-1.0-1-x86_64.pkg.tar.zst

For advanced manual chroot setup, see @clean-chroot-reference.md (custom location, custom configs).

Fallback: Direct makepkg Build

Use ONLY when clean chroot is not available.

# Build package
makepkg -f

# CRITICAL: After building, ALWAYS inform user:
echo "⚠️  WARNING: Package built with direct makepkg (NOT in clean chroot)"
echo "⚠️  Dependencies may be incomplete or incorrect"
echo "⚠️  For production use, install 'devtools' and rebuild in clean chroot"

When this is acceptable:

• •Local development/testing
• •Quick prototyping
• •No plans to distribute package

When this is NOT acceptable:

• •AUR submission
• •Distribution to others
• •Official packaging

PKGBUILD Structure Template

See @pkgbuild-template.sh in this directory for a complete annotated template.

Quick structure overview:

• •Variables: pkgname, pkgver, pkgrel, pkgdesc, arch, url, license, depends, makedepends
• •prepare(): Patching, fixing paths (optional)
• •build(): Compile sources (usually required)
• •check(): Run test suite (optional but recommended)
• •package(): Install to $pkgdir (MANDATORY)

Quick Reference: Critical Requirements

Step-by-Step Implementation

Step 1: Check for Existing Packages

BEFORE creating any PKGBUILD:

# Check official repositories
pacman -Ss package-name

# Check AUR
yay -Ss package-name  # or paru -Ss
# Or visit: https://aur.archlinux.org/packages/?K=package-name

If package exists:

• •Official repo: DO NOT create PKGBUILD (use existing)
• •AUR exists: Check if you can improve it or use different name with conflicts=()

Step 2: Create PKGBUILD

Mandatory fields:

• •pkgname, pkgver, pkgrel, arch, pkgdesc, url, license
• •source, checksums (sha256sums or sha512sums)
• •depends (if any runtime dependencies)
• •package() function

Optional but recommended fields:

• •install="$pkgname.install" : Specifies a post-install script with user instructions

Package naming conventions:

• •VCS packages: suffix -git, -svn, -hg, -bzr, -cvs, -darcs (see archlinux-pkgbuild/vcs-packages sub-skill)
• •Prebuilt binaries: suffix -bin (when sources available)
• •Python packages: python-pkgname (see archlinux-pkgbuild/language-ecosystems sub-skill)
• •Language-specific: See archlinux-pkgbuild/language-ecosystems sub-skill for naming conventions
• •All lowercase, no leading hyphen/dot

Dependency types:

• •depends=() : Runtime requirements (libraries, interpreters)
• •makedepends=() : Build-time only (compilers, build tools)
• •checkdepends=() : Test suite requirements
• •optdepends=() : Optional features ('package: what it enables')

Use tools to find dependencies:

# Find library dependencies
find-libdeps /path/to/built/files

# Alternative: check with ldd
ldd /path/to/binary

# Find provided libraries
find-libprovides /path/to/built/files

CRITICAL: Validate Package Availability

Before finalizing your PKGBUILD, MUST verify all dependencies exist:

# Check official repos
pacman -Ss package-name

# Check AUR (using yay or paru)
yay -Ss package-name
# OR
paru -Ss package-name

# Validate all dependencies at once
for pkg in depend1 depend2 makedepend1 optdepend1; do
    pacman -Ss "^$pkg$" || yay -Ss "^$pkg$" || echo "MISSING: $pkg"
done

Rules:

• •Every depends=(), makedepends=(), and optdepends=() entry MUST exist in official repos or AUR
• •Use exact package names (check pacman -Ss or aur.archlinux.org)
• •For AUR dependencies, document in comments (AUR packages can't auto-install)
• •Invalid dependencies = namcap errors + installation failures

Step 3: FHS Compliance and System Package Locations

For detailed FHS paths and vendor config rules, see @fhs-and-vendor-config.md in this directory.

Critical Quick Reference:

Key Rule: Vendor configs go to /usr/lib/, user overrides go to /etc/.

Step 4: Checksums

Generate checksums:

# Easy way: auto-update checksums
updpkgsums

# Manual way: download and compute
makepkg -g >> PKGBUILD  # Append checksums

Checksum types (prefer stronger):

• •sha512sums (best)
• •sha256sums (good)
• •b2sums (Blake2, also good)
• •md5sums (weak, avoid)

Use SKIP for VCS sources:

source=("git+https://github.com/user/repo.git")
sha256sums=('SKIP')

Step 5: Build Package

Choose build method based on availability:

# Check if devtools is installed
if command -v extra-x86_64-build &> /dev/null; then
    # PREFERRED: Clean chroot build
    extra-x86_64-build
    echo "✓ Built in clean chroot (dependencies verified)"
else
    # FALLBACK: Direct build with warning
    makepkg -f
    echo "⚠️  WARNING: Built with direct makepkg (NOT in clean chroot)"
    echo "⚠️  Dependencies may be incomplete. Install 'devtools' for clean builds."
fi

For custom dependencies (clean chroot only):

extra-x86_64-build -- -I custom-package-1.0-1-x86_64.pkg.tar.zst

Step 6: Validation with namcap

MANDATORY validation steps:

# 1. Check PKGBUILD
namcap PKGBUILD

# 2. Check generated package
namcap *.pkg.tar.zst

# 3. Detailed analysis (RECOMMENDED)
namcap -i PKGBUILD
namcap -i *.pkg.tar.zst

CRITICAL: DO NOT proceed if namcap reports errors.

For comprehensive validation procedures, error explanations, and fixes: See @validation-guide.md

Step 7: Test Installation

# Install locally
sudo pacman -U *.pkg.tar.zst

# Test functionality
$pkgname --version
$pkgname --help

# Check installed files
pacman -Ql $pkgname

# Verify dependencies (clean chroot builds should be correct)
pacman -Qi $pkgname | grep Depends

# Remove after testing
sudo pacman -R $pkgname

Step 8: AUR Submission (if applicable)

Generate .SRCINFO:

makepkg --printsrcinfo > .SRCINFO

Set up AUR SSH:

# Add to ~/.ssh/config
Host aur.archlinux.org
    IdentityFile ~/.ssh/aur
    User aur

Clone and commit:

# Clone (empty for new packages)
git clone ssh://aur@aur.archlinux.org/pkgname.git
cd pkgname

# Add files
cp /path/to/PKGBUILD .
makepkg --printsrcinfo > .SRCINFO

# Commit
git add PKGBUILD .SRCINFO
git commit -m "Initial commit: pkgname $pkgver-$pkgrel"

# Push
git push origin master

Tracking Upstream Releases with nvchecker

nvchecker automates checking for new upstream releases. Use pkgctl version commands for integration.

Quick Start

# Auto-generate .nvchecker.toml from PKGBUILD source array
pkgctl version setup

# Check for new upstream releases
pkgctl version check

# Update PKGBUILD to new version
pkgctl version upgrade

.nvchecker.toml Configuration

Place .nvchecker.toml in the same directory as PKGBUILD. The pkgctl version setup command auto-creates this by analyzing your source=() array.

Example for GitHub releases:

[pkgname]
source = "github"
github = "owner/repo"

Example for PyPI:

[python-package]
source = "pypi"
pypi = "package-name"

Example for GitLab:

[pkgname]
source = "gitlab"
gitlab = "group/project"

See also:

• •pkgctl-version(1) man page for full documentation
• •Example configs in official packages (e.g., https://gitlab.archlinux.org/archlinux/packaging/packages/pacman/-/blob/main/.nvchecker.toml)
• •nvchecker documentation: https://nvchecker.readthedocs.io/

Workflow

1. •Initial setup: pkgctl version setup (creates .nvchecker.toml)
2. •Periodically check: pkgctl version check
3. •When new version found: pkgctl version upgrade (updates pkgver)
4. •Review changes, update pkgrel=1, rebuild, test
5. •Commit to AUR

Note: nvchecker is particularly useful for maintaining multiple packages or tracking fast-moving projects.

Common Mistakes and Red Flags

Critical Errors (MUST FIX)

Warning Signs (CHECK CAREFULLY)

PKGBUILD Functions Reference

Installation Commands Reference

# Install files with correct permissions
install -Dm644 file.txt "$pkgdir/usr/share/doc/$pkgname/file.txt"  # Regular file
install -Dm755 binary "$pkgdir/usr/bin/binary"                      # Executable
install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"  # License

# Create directories
install -dm755 "$pkgdir/usr/share/$pkgname"

# Copy entire directories
cp -r dir "$pkgdir/usr/share/$pkgname/"

# Remove unwanted files
rm -rf "$pkgdir/usr/share/doc"  # If upstream installs docs incorrectly

Configuration File Handling

User-modifiable config files MUST be listed in backup=() to prevent pacman from overwriting user changes.

Quick Rules

backup=(
    'etc/myapp/main.conf'     # Relative to root, NO leading slash
)

Include in backup=(): All /etc files users might customize, especially credential files
Exclude: Templates in /usr/share, generated files, service files

Pacman behavior: Modified files → Creates .pacnew (user merges manually)

Security: Sensitive Configuration Files

If config files contain credentials/secrets (database passwords, API keys):

• •Use 0660 permissions (not world-readable)
• •Set ownership via tmpfiles.d type z
• •Example: z /etc/webapps/app/database.php 0660 root http - -

If application writes to config (web installers):

• •Files owned by root, group set to app user (e.g., root:http)
• •Use 0660 for group-writable, not world-readable (security)
• •Directory can remain root:root (only files need group access)

Detailed reference: See @config-file-handling.md for:

• •backup=() rules and .pacnew workflow
• •Sensitive config file permissions (0660 vs 0640 vs 0644)
• •Using tmpfiles.d type z for ownership/permission changes
• •Security patterns for web applications

Post-Install Scripts (.install files)

Use .install files to provide post-installation instructions, perform setup tasks, or notify users of manual configuration requirements.

When to Use .install Files

.install File Structure

# /path/to/pkgname.install
post_install() {
    cat <<EOF

==> Package Name
==> ============

1. First setup step:
   - Detailed instructions
   - Commands to run

2. Second setup step:
   - More instructions

For more information: https://upstream.docs

EOF
}

post_upgrade() {
    # IMPORTANT: Only include upgrade-relevant information
    # DO NOT blindly call post_install() unless ALL instructions apply to upgrades
    
    # If upgrade needs specific instructions (migrations, breaking changes):
    cat <<EOF

==> Upgrade Notes
==> =============

- Review configuration files (check .pacnew files)
- Database migration steps (if applicable)
- Breaking changes in this version
- Service restart commands

EOF
    
    # ANTI-PATTERN: Don't do this unless initial setup truly applies to upgrades
    # post_install  # ❌ Wrong if it contains one-time setup instructions
}

pre_remove() {
    # Optional: cleanup before removal
    # Use sparingly - most cleanup should be manual
}

post_remove() {
    # Optional: notify about leftover data
    cat <<EOF

==> Removal Complete
==> =================

User data remains in /var/lib/pkgname/
Remove manually if needed: sudo rm -rf /var/lib/pkgname

EOF
}

PKGBUILD Integration

Reference the .install file in PKGBUILD:

# In PKGBUILD
pkgname=myapp
install="$pkgname.install"  # Add after optdepends=(), before source=()

The .install file must:

• •Be named $pkgname.install
• •Be in the same directory as PKGBUILD
• •NOT be listed in source=() (it's metadata, not a source file)
• •Use proper shell syntax (functions, no syntax errors)

Best Practices

CRITICAL: post_install vs post_upgrade Distinction

post_install(): One-time initial setup instructions

• •Database creation and schema import
• •Initial configuration file setup
• •Web server configuration from scratch
• •User/group creation
• •First-time setup wizards
• •Installation verification steps

post_upgrade(): Upgrade-relevant information ONLY

• •Configuration file changes (.pacnew review)
• •Database migrations/schema updates
• •Breaking changes between versions
• •Service restart requirements
• •Deprecated feature warnings
• •Changelog references

Decision Rule:

If instruction is ONLY needed on first install → post_install() only
If instruction is ONLY needed on upgrade → post_upgrade() only  
If instruction applies to BOTH → Consider calling post_install() from post_upgrade()

⚠️  ANTI-PATTERN: Always calling post_install() from post_upgrade()
Only do this if ALL post_install instructions genuinely apply to upgrades.

Examples:

❌ WRONG - Upgrade shows unnecessary one-time setup:

post_install() {
    cat <<EOF
1. Create database and import schema  # ❌ Only needed once
2. Configure web server               # ❌ Only needed once
3. Run installation wizard            # ❌ Only needed once
EOF
}
post_upgrade() {
    post_install  # ❌ Confuses users with irrelevant steps
}

✅ CORRECT - Clear separation:

post_install() {
    cat <<EOF
1. Create database: createdb myapp
2. Import schema: psql myapp < /usr/share/myapp/schema.sql
3. Configure: edit /etc/webapps/myapp/config.php
4. Start service: systemctl start myapp
EOF
}

post_upgrade() {
    cat <<EOF
1. Check for new config options (.pacnew files)
2. Run migrations: myapp-migrate --run
3. Restart service: systemctl restart myapp
Changelog: https://github.com/project/releases
EOF
}

✅ ACCEPTABLE - When instructions truly apply to both:

post_install() {
    cat <<EOF
Review configuration at /etc/myapp/config.yaml
Restart service: systemctl restart myapp
EOF
}

post_upgrade() {
    post_install  # ✅ OK - these steps apply to upgrades too
}

Example: Web Application

# webapp.install
post_install() {
    cat <<EOF

==> Webapp Installation
==> ====================

1. Create database:
   $ sudo -u postgres createdb webappdb

2. Configure:
   $ sudo nano /usr/share/webapps/webapp/config.php

3. Set up web server (Apache example):
   $ sudo ln -s /etc/httpd/conf/extra/webapp.conf /etc/httpd/conf/extra/
   $ sudo systemctl restart httpd

4. Complete setup:
   Visit: http://localhost/webapp/install

Documentation: https://webapp.example/docs

EOF
}

post_upgrade() {
    post_install
}

Validation

# Check .install syntax
bash -n pkgname.install

# Verify it's referenced in PKGBUILD
grep "^install=" PKGBUILD

# Verify it's included in package
namcap *.pkg.tar.zst | grep -i install

Note: The .install file is automatically included in the package when install= is set. Do NOT manually install it in package().

Specialized Package Types

For specialized package types, load the appropriate sub-skill:

• •VCS packages (-git, -svn, -cvs): Use archlinux-pkgbuild/vcs-packages
• •Systemd services (DynamicUser, tmpfiles.d, sandboxing, init conversion): Use archlinux-pkgbuild/systemd-services
• •Compiled languages (Go, Rust, Haskell, OCaml, Free Pascal, Java): Use archlinux-pkgbuild/compiled-languages
• •Interpreted languages (Node.js, Python, Ruby, PHP, Perl, R, Shell, Lisp): Use archlinux-pkgbuild/interpreted-languages
• •Build systems (CMake, Meson): Use archlinux-pkgbuild/build-systems
• •Cross-platform (Wine, MinGW, Electron, CLR): Use archlinux-pkgbuild/cross-platform
• •Desktop integration (GNOME, KDE, Eclipse, Fonts): Use archlinux-pkgbuild/desktop-integration
• •System packages (DKMS, kernel modules, lib32, nonfree, web apps, split): Use archlinux-pkgbuild/system-packages

Advanced Clean Chroot Techniques

For advanced clean chroot usage (tmpfs builds, custom dependencies, major rebuilds, different repositories), see @clean-chroot-reference.md in this directory.

Quick troubleshooting:

Resources

• •Arch Package Guidelines: https://wiki.archlinux.org/title/Arch_package_guidelines
• •PKGBUILD(5) man page: https://man.archlinux.org/man/PKGBUILD.5
• •FHS specification: https://man.archlinux.org/man/file-hierarchy.7
• •AUR submission: https://wiki.archlinux.org/title/AUR_submission_guidelines
• •namcap: https://wiki.archlinux.org/title/Namcap
• •Clean chroot building: https://wiki.archlinux.org/title/DeveloperWiki:Building_in_a_clean_chroot
• •devtools: https://man.archlinux.org/man/extra/devtools/pkgctl-build.1
• •nvchecker/pkgctl-version: https://man.archlinux.org/man/extra/devtools/pkgctl-version.1