Parch

source: handbook ch. 33, 51

Building packages

makepkg turns a PKGBUILD into an installable .pkg.tar.zst. This page walks through the full local workflow on an Arch-based host: toolchain setup, fetching PKGBUILDs, building, and testing the result. It assumes you already understand the PKGBUILD format from the reference.

Prerequisites

  • An Arch-based host (Parch GNU/Linux or Arch Linux) with a current pacman -Syu.
  • An unprivileged build user; makepkg refuses to run as root.
  • The packages below (root required to install them).
Install the packaging toolchain (root required)
# pacman -S --needed base-devel pkgctl namcap pacman-contrib
  • base-devel: gcc, make, and the rest of the compiler stack.
  • pkgctl: devtools front end for cloning and chroot builds.
  • namcap: PKGBUILD and package linter.
  • pacman-contrib: provides updpkgsums and pactree.

Step by step

  1. Create a build directory

    Keep one directory per package, outside any repository checkout, so builds never interfere with your system files.

    Working layout
    $ mkdir -p ~/builds/example-todo && cd ~/builds/example-todo

  2. Get a PKGBUILD

    To study or rebuild an official package, clone its build recipe:

    Clone an official PKGBUILD with pkgctl
    $ pkgctl repo clone linux-firmware
$ cd linux-firmware

    For your own package, write the PKGBUILD in this directory instead. For software whose sources are covered in the application development section, you can package the same tree you develop in.

  3. Check syntax and generate checksums

    Validate before building
    $ bash -n PKGBUILD
$ namcap PKGBUILD
$ updpkgsums        # fills or rewrites the sha256sums array in place

  4. Fetch sources only (optional)

    To download and extract the sources without compiling, useful for inspecting what you are about to build:

    Download and extract, no build
    $ makepkg -o
$ ls src/

    After editing files under src/, rebuild them with makepkg -e, which reuses the existing src/ tree instead of re-extracting and would otherwise discard your edits.

  5. Build the package

    Full build with dependency installation
    $ makepkg -s

    On success the directory contains example-todo-1.4.2-1-x86_64.pkg.tar.zst. -s installs missing build dependencies via pacman; add -c to clean the work tree afterwards, or -si to also install the finished package immediately.

  6. Inspect the result

    List what the package contains
    $ pacman -Qpl example-todo-1.4.2-1-x86_64.pkg.tar.zst
$ namcap example-todo-1.4.2-1-x86_64.pkg.tar.zst

makepkg flags that matter

FlagLong formEffect
-s--syncdepsInstall missing dependencies with pacman first.
-i--installInstall or upgrade the package after a successful build.
-c--cleanRemove leftover build files from the work tree.
-o--nobuildDownload and extract sources, then stop before build().
-e--noextractDo not extract sources, use what is already in src/.
-g--genintegGenerate the integrity arrays and print them (prefer updpkgsums).
-r--rmdepsRemove build dependencies after the build.
-f--forceOverwrite an existing package file of the same version.
-R--repackageRe-run only package() on the previous build.
-L--logWrite the build output to a log file.
-d--nodepsSkip dependency checks (escape hatch, use with care).
--checkRun the check() function.
--packagelistPrint the package file names this PKGBUILD would produce.
--printsrcinfoPrint .SRCINFO to stdout.
--skippgpcheckSkip source PGP verification. Only for sources you already trust.

Test in a clean chroot

A host build succeeds with whatever happens to be installed on your machine. A clean chroot build proves the dependency lists are complete, which is exactly what reviewers and the build service will see. pkgctl build wraps devtools' makechrootpkg and manages the chroot for you:

Clean chroot build
$ cd ~/builds/example-todo
$ pkgctl build

It builds the package inside a minimal container with only the declared depends, makedepends, and checkdepends installed, then drops the finished package next to the PKGBUILD. If the build fails there but succeeds on the host, your dependency arrays are incomplete or your build() reads something from the host that it should not. Rebuild the chroot from scratch with pkgctl build --clean after toolchain updates.

Sign packages with GPG

Signing lets others verify a package came from you:

Create a key and enable signing
$ gpg --full-generate-key
$ gpg --list-secret-keys --keyid-format=long

Copy the long key ID (40 hex characters) into ~/.makepkg.conf:

~/.makepkg.conf
PACKAGER="Your Name <you@example.com>"
GPGKEY="C4A91FF52A0B8E9A5C3D71F6B2E84D930FA7C612"

With GPGKEY set, makepkg signs every package it produces. To sign or re-sign an existing file, run makepkg --sign. A detached signature appears next to the package as a .sig file.

Local test repository

For testing several packages together, index them into a local repository and point pacman at it:

Create a local repo and install from it
$ mkdir -p ~/repo/x86_64
$ cp example-todo-1.4.2-1-x86_64.pkg.tar.zst ~/repo/x86_64/
$ repo-add ~/repo/x86_64/parch-local.db.tar.gz ~/repo/x86_64/*.pkg.tar.zst

Add the repository to /etc/pacman.conf (root required):

/etc/pacman.conf
[parch-local]
SigLevel = Optional TrustAll
Server = file:///home/YOUR-USERNAME/repo/x86_64/

Then # pacman -Syu example-todo installs from your local repo exactly the way users will install from world.

Troubleshooting

  • Checksum mismatch: confirm the source change is legitimate upstream, then re-run updpkgsums. Never blind-patch a mismatch; investigate first.
  • Builds on the host, fails in the chroot: a missing makedepends entry or a hardcoded host path in build().
  • makepkg refuses to run as root: run it as your normal user; pacman operations it triggers will ask for sudo.
  • pacman cannot find the local package: re-run repo-add after copying new package files, the database is not scanned automatically.