diff options
Diffstat (limited to 'garden')
| -rw-r--r-- | garden/arch-pkg-guide.md | 925 | ||||
| -rw-r--r-- | garden/index.md | 8 | ||||
| -rw-r--r-- | garden/system.md | 258 |
3 files changed, 1191 insertions, 0 deletions
diff --git a/garden/arch-pkg-guide.md b/garden/arch-pkg-guide.md new file mode 100644 index 0000000..b388078 --- /dev/null +++ b/garden/arch-pkg-guide.md @@ -0,0 +1,925 @@ +title: Arch Linux Packaging Guide + +*Generated using [Claude.ai](https://claude.ai) (Opus 4.5 model)* + +# Complete Guide to Creating Arch Linux Packages + +A comprehensive guide consolidating official Arch Linux documentation on creating, building, and submitting packages to the Arch User Repository (AUR). + +--- + +## Table of Contents + +1. [Overview](#1-overview) +2. [Prerequisites and Setup](#2-prerequisites-and-setup) +3. [Understanding the PKGBUILD File](#3-understanding-the-pkgbuild-file) +4. [PKGBUILD Variables Reference](#4-pkgbuild-variables-reference) +5. [PKGBUILD Functions](#5-pkgbuild-functions) +6. [Building Packages with makepkg](#6-building-packages-with-makepkg) +7. [VCS Package Guidelines](#7-vcs-package-guidelines) +8. [Testing and Quality Assurance](#8-testing-and-quality-assurance) +9. [Submitting to the AUR](#9-submitting-to-the-aur) +10. [Package Maintenance](#10-package-maintenance) +11. [Best Practices and Common Mistakes](#11-best-practices-and-common-mistakes) +12. [Quick Reference](#12-quick-reference) + +--- + +## 1. Overview + +### What is an Arch Linux Package? + +An Arch package is a tar archive compressed with zstd (`.pkg.tar.zst`) containing: + +- **Binary files** to install +- **`.PKGINFO`** - Package metadata (name, version, dependencies, etc.) +- **`.MTREE`** - Hashed list of files with permissions for integrity verification +- **`.BUILDINFO`** - Information for reproducible builds +- **`.INSTALL`** - Optional post-install/upgrade/remove script +- **`.Changelog`** - Optional changelog maintained by the packager + +### The Arch Build System + +The Arch Build System (ABS) is a ports-like system for building packages from source: + +| Component | Description | +|-----------|-------------| +| **PKGBUILD** | Bash script containing build instructions and metadata | +| **makepkg** | Tool that reads PKGBUILDs and creates packages | +| **pacman** | Package manager for installing/removing packages | +| **devtools** | Tools for building in clean chroots (official packages) | + +### Package Repositories + +- **Official Repositories** (core, extra, multilib): Pre-built binary packages maintained by Arch developers +- **Arch User Repository (AUR)**: Community-maintained PKGBUILDs (not pre-built) + +--- + +## 2. Prerequisites and Setup + +### Install Required Tools + +```bash +# Install base development tools (required) +sudo pacman -S base-devel + +# Install additional useful tools +sudo pacman -S namcap devtools git +``` + +The `base-devel` group includes: `autoconf`, `automake`, `binutils`, `bison`, `fakeroot`, `file`, `findutils`, `flex`, `gawk`, `gcc`, `gettext`, `grep`, `groff`, `gzip`, `libtool`, `m4`, `make`, `pacman`, `patch`, `pkgconf`, `sed`, `sudo`, `texinfo`, `which`. + +### Configure makepkg (Optional) + +Edit `/etc/makepkg.conf` or `~/.makepkg.conf`: + +```bash +# Use multiple cores for compilation +MAKEFLAGS="-j$(nproc)" + +# Use multiple cores for compression +COMPRESSZST=(zstd -c -z -q -T0 -) + +# Enable ccache for faster rebuilds (optional) +# BUILDENV=(... ccache ...) +``` + +### Set Up a Working Directory + +```bash +mkdir -p ~/packages +cd ~/packages +``` + +--- + +## 3. Understanding the PKGBUILD File + +### What is a PKGBUILD? + +A PKGBUILD is a Bash script that defines how to build a package. It contains: + +1. **Metadata variables** - Package name, version, description, etc. +2. **Source information** - Where to download source files +3. **Functions** - How to build and package the software + +### PKGBUILD Template + +Use the official prototype as a starting point: + +```bash +cp /usr/share/pacman/PKGBUILD.proto ~/packages/mypackage/PKGBUILD +``` + +### Minimal PKGBUILD Example + +```bash +# Maintainer: Your Name <your.email@example.com> +pkgname=hello-world +pkgver=1.0.0 +pkgrel=1 +pkgdesc="A simple hello world program" +arch=('x86_64') +url="https://example.com/hello-world" +license=('MIT') +depends=('glibc') +source=("https://example.com/${pkgname}-${pkgver}.tar.gz") +sha256sums=('abc123...') + +build() { + cd "$srcdir/$pkgname-$pkgver" + ./configure --prefix=/usr + make +} + +package() { + cd "$srcdir/$pkgname-$pkgver" + make DESTDIR="$pkgdir" install +} +``` + +--- + +## 4. PKGBUILD Variables Reference + +### Mandatory Variables + +| Variable | Description | +|----------|-------------| +| `pkgname` | Package name (lowercase alphanumerics, `@._+-`). Cannot start with `-` or `.` | +| `pkgver` | Upstream version. No hyphens allowed (replace with `_`) | +| `pkgrel` | Arch-specific release number. Starts at `1`, increment for PKGBUILD fixes | +| `arch` | Supported architectures: `('x86_64')` or `('any')` for arch-independent | + +### Recommended Variables + +| Variable | Description | +|----------|-------------| +| `pkgdesc` | Brief description (≤80 chars). Don't include package name | +| `url` | Upstream project URL | +| `license` | SPDX license identifier(s): `('GPL-3.0-or-later')`, `('MIT')`, etc. | + +### Dependency Arrays + +| Variable | Description | +|----------|-------------| +| `depends` | Runtime dependencies (required to run the software) | +| `makedepends` | Build-time only dependencies (not needed at runtime) | +| `checkdepends` | Dependencies for running tests (only needed for `check()`) | +| `optdepends` | Optional dependencies with descriptions: `('python: for scripting support')` | + +**Important:** Always list all direct dependencies, even if they're pulled in transitively. Transitive dependencies can change. + +### Source Arrays + +| Variable | Description | +|----------|-------------| +| `source` | Array of source files (URLs or local filenames) | +| `sha256sums` | SHA-256 checksums for each source (or `'SKIP'` to skip verification) | +| `validpgpkeys` | GPG key fingerprints for signature verification | +| `noextract` | Files to not auto-extract | + +**Source URL best practices:** + +```bash +# Use variables for maintainability +source=("https://github.com/user/repo/archive/v${pkgver}.tar.gz") + +# Rename downloaded files +source=("${pkgname}-${pkgver}.tar.gz::https://example.com/download/${pkgver}.tar.gz") + +# Local files (must be in same directory as PKGBUILD) +source=("fix-build.patch" + "myconfig.conf") +``` + +### Other Useful Variables + +| Variable | Description | +|----------|-------------| +| `provides` | Virtual packages this provides: `('libfoo.so=1-64')` | +| `conflicts` | Packages that conflict with this one | +| `replaces` | Packages this replaces (use sparingly, mostly for renames) | +| `backup` | Config files to backup on upgrade: `('etc/myapp.conf')` | +| `options` | Build options: `('!strip' '!buildflags' 'staticlibs')` | +| `install` | Post-install script filename: `install=${pkgname}.install` | +| `changelog` | Changelog filename | +| `epoch` | Force package to be seen as newer (use sparingly) | +| `groups` | Package groups this belongs to | + +### Architecture-Specific Variables + +Append `_<arch>` to create architecture-specific overrides: + +```bash +source_x86_64=("https://example.com/binary-x86_64.tar.gz") +sha256sums_x86_64=('...') +depends_x86_64=('lib32-glibc') +``` + +--- + +## 5. PKGBUILD Functions + +### Available Variables in Functions + +| Variable | Description | +|----------|-------------| +| `$srcdir` | Directory where sources are extracted | +| `$pkgdir` | Fake root directory for installation (becomes package contents) | +| `$startdir` | Directory containing the PKGBUILD (deprecated, avoid using) | + +### prepare() - Source Preparation + +Optional. Runs after source extraction. Used for patching and source modifications. + +```bash +prepare() { + cd "$srcdir/$pkgname-$pkgver" + + # Apply patches + patch -Np1 -i "$srcdir/fix-build.patch" + + # Generate build files + autoreconf -fiv +} +``` + +### pkgver() - Dynamic Version (VCS Packages) + +Optional. Used to update `pkgver` from VCS sources. See [VCS Package Guidelines](#7-vcs-package-guidelines). + +### build() - Compilation + +Optional (but usually needed). Compiles the source code. + +```bash +build() { + cd "$srcdir/$pkgname-$pkgver" + + # Standard autotools + ./configure --prefix=/usr + make + + # Or CMake + cmake -B build -S . \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=/usr + cmake --build build + + # Or Meson + arch-meson build + meson compile -C build +} +``` + +**Important:** Always use `--prefix=/usr`. Arch packages should never install to `/usr/local`. + +### check() - Testing + +Optional but recommended. Runs the test suite. + +```bash +check() { + cd "$srcdir/$pkgname-$pkgver" + make check + # or: make test + # or: ctest --test-dir build +} +``` + +### package() - Installation + +**Required.** Installs files into `$pkgdir`. + +```bash +package() { + cd "$srcdir/$pkgname-$pkgver" + + # Standard make install + make DESTDIR="$pkgdir" install + + # Install license + install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE" + + # Install documentation + install -Dm644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md" + + # Install config file (add to backup array) + install -Dm644 myapp.conf "$pkgdir/etc/myapp.conf" +} +``` + +**Note:** Everything in `$pkgdir` will be packaged. The directory structure under `$pkgdir` becomes the root filesystem structure. + +### Split Packages + +Build multiple packages from one PKGBUILD: + +```bash +pkgbase=myproject +pkgname=('myproject' 'myproject-docs') +# ... other variables ... + +package_myproject() { + pkgdesc="The main application" + depends=('glibc') + + cd "$srcdir/$pkgbase-$pkgver" + make DESTDIR="$pkgdir" install +} + +package_myproject-docs() { + pkgdesc="Documentation for myproject" + arch=('any') + + cd "$srcdir/$pkgbase-$pkgver" + install -Dm644 docs/* -t "$pkgdir/usr/share/doc/$pkgbase/" +} +``` + +--- + +## 6. Building Packages with makepkg + +### Basic Usage + +```bash +cd ~/packages/mypackage + +# Build the package +makepkg + +# Build and install dependencies automatically +makepkg -s + +# Build, install deps, and install the package +makepkg -si + +# Build and remove makedepends afterward +makepkg -sr + +# Clean build directory after successful build +makepkg -c +``` + +### Useful makepkg Options + +| Option | Description | +|--------|-------------| +| `-s, --syncdeps` | Install missing dependencies with pacman | +| `-r, --rmdeps` | Remove makedepends after build | +| `-i, --install` | Install package after building | +| `-c, --clean` | Clean up work files after build | +| `-f, --force` | Overwrite existing package | +| `-C, --cleanbuild` | Remove `$srcdir` before building | +| `-o, --nobuild` | Download and extract only (no build) | +| `-e, --noextract` | Don't extract sources (use existing `$srcdir`) | +| `-R, --repackage` | Repackage without rebuilding | +| `-g, --geninteg` | Generate integrity checksums | +| `--nocheck` | Skip the check() function | +| `--skippgpcheck` | Skip PGP signature verification | +| `--skipchecksums` | Skip checksum verification | +| `-L, --log` | Log build output to file | + +### Generate Checksums + +```bash +# Generate and append to PKGBUILD +makepkg -g >> PKGBUILD + +# Or use updpkgsums (from pacman-contrib) +updpkgsums +``` + +### Install the Built Package + +```bash +# Using pacman +sudo pacman -U mypackage-1.0.0-1-x86_64.pkg.tar.zst + +# Or using makepkg -i +makepkg -si +``` + +--- + +## 7. VCS Package Guidelines + +### Naming Convention + +VCS packages must be suffixed with the VCS type: + +- `-git` for Git +- `-svn` for Subversion +- `-hg` for Mercurial +- `-bzr` for Bazaar + +### VCS Source Format + +```bash +# Git (most common) +source=("git+https://github.com/user/repo.git") + +# Git with specific branch +source=("git+https://github.com/user/repo.git#branch=develop") + +# Git with specific tag +source=("git+https://github.com/user/repo.git#tag=v1.0.0") + +# Git with specific commit +source=("git+https://github.com/user/repo.git#commit=abc123") + +# SSH URL +source=("git+ssh://git@github.com/user/repo.git") +``` + +For VCS sources, use `SKIP` for checksums: + +```bash +sha256sums=('SKIP') +``` + +### The pkgver() Function + +The `pkgver()` function dynamically generates version numbers from VCS sources. + +**Recommended format:** `RELEASE.rREVISION` or `RELEASE.rREVISION.gHASH` + +**Git with tags (preferred):** + +```bash +pkgver() { + cd "$srcdir/$pkgname" + git describe --long --tags --abbrev=7 | sed 's/^v//;s/\([^-]*-g\)/r\1/;s/-/./g' +} +# Output: 1.2.3.r5.gabc1234 (5 commits after tag v1.2.3) +``` + +**Git without tags:** + +```bash +pkgver() { + cd "$srcdir/$pkgname" + printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short=7 HEAD)" +} +# Output: r150.abc1234 (150 commits, hash abc1234) +``` + +**Mercurial:** + +```bash +pkgver() { + cd "$srcdir/$pkgname" + printf "r%s.%s" "$(hg identify -n)" "$(hg identify -i)" +} +``` + +**Subversion:** + +```bash +pkgver() { + cd "$srcdir/$pkgname" + printf "r%s" "$(svnversion | tr -d 'A-z')" +} +``` + +### Complete VCS PKGBUILD Example + +```bash +# Maintainer: Your Name <email@example.com> +pkgname=myapp-git +_pkgname=myapp +pkgver=1.2.3.r5.gabc1234 +pkgrel=1 +pkgdesc="My application (development version)" +arch=('x86_64') +url="https://github.com/user/myapp" +license=('MIT') +depends=('glibc') +makedepends=('git' 'cmake') +provides=("${_pkgname}") +conflicts=("${_pkgname}") +source=("git+${url}.git") +sha256sums=('SKIP') + +pkgver() { + cd "$srcdir/$_pkgname" + git describe --long --tags --abbrev=7 | sed 's/^v//;s/\([^-]*-g\)/r\1/;s/-/./g' +} + +build() { + cmake -B build -S "$_pkgname" \ + -DCMAKE_BUILD_TYPE=Release \ + -DCMAKE_INSTALL_PREFIX=/usr + cmake --build build +} + +package() { + DESTDIR="$pkgdir" cmake --install build + install -Dm644 "$srcdir/$_pkgname/LICENSE" \ + "$pkgdir/usr/share/licenses/$pkgname/LICENSE" +} +``` + +### VCS Package Rules + +1. **Don't commit pkgver bumps alone** - Only commit when PKGBUILD changes +2. **Use provides/conflicts** - Link to the stable package name +3. **Add VCS tool to makedepends** - `git`, `subversion`, `mercurial`, etc. +4. **pkgrel stays at 1** - Reset when pkgver changes, increment only for PKGBUILD fixes + +--- + +## 8. Testing and Quality Assurance + +### Using namcap + +namcap analyzes PKGBUILDs and packages for common errors: + +```bash +# Check PKGBUILD +namcap PKGBUILD + +# Check built package +namcap mypackage-1.0.0-1-x86_64.pkg.tar.zst + +# Check installed package +namcap -i mypackage +``` + +**Common namcap warnings:** + +| Warning | Meaning | +|---------|---------| +| `dependency X detected and target Y depends on it` | Missing dependency | +| `dependency X included but already satisfied` | Redundant dependency | +| `ELF file has no RELRO` | Security issue (missing hardening) | +| `Dependency included, but may not be needed` | Possible unnecessary dependency | + +**Note:** namcap can produce false positives. Investigate warnings but don't blindly follow all suggestions. + +### Building in a Clean Chroot + +Building in a clean chroot ensures: +- All dependencies are correctly declared +- No accidental linking against packages on your system +- Reproducible builds + +**Using devtools (recommended for AUR maintainers):** + +```bash +# Install devtools +sudo pacman -S devtools + +# Build in clean chroot +pkgctl build + +# Or use the repository-specific script +extra-x86_64-build +``` + +**Using clean-chroot-manager (alternative):** + +```bash +# Install from AUR +yay -S clean-chroot-manager + +# Create chroot +sudo ccm c + +# Build package +sudo ccm s +``` + +### Testing the Package + +```bash +# List package contents +pacman -Qlp mypackage-1.0.0-1-x86_64.pkg.tar.zst + +# View package info +pacman -Qip mypackage-1.0.0-1-x86_64.pkg.tar.zst + +# Install and test +sudo pacman -U mypackage-1.0.0-1-x86_64.pkg.tar.zst + +# Verify installation +pacman -Ql mypackage +pacman -Qi mypackage + +# Test the software actually works +mypackage --version +``` + +### Checking Dependencies + +```bash +# Find libraries linked by an executable +ldd /usr/bin/myapp + +# Better alternative +lddtree /usr/bin/myapp + +# Find which package provides a library +pacman -Qo /usr/lib/libfoo.so +``` + +--- + +## 9. Submitting to the AUR + +### Prerequisites + +1. **Read the guidelines** - Familiarize yourself with [Arch package guidelines](https://wiki.archlinux.org/title/Arch_package_guidelines) +2. **Create an AUR account** - Register at https://aur.archlinux.org +3. **Set up SSH keys** - Required for pushing packages + +### Setting Up SSH Authentication + +```bash +# Generate a dedicated SSH key for AUR +ssh-keygen -t ed25519 -f ~/.ssh/aur + +# Configure SSH +cat >> ~/.ssh/config << EOF +Host aur.archlinux.org + IdentityFile ~/.ssh/aur + User aur +EOF + +# Copy public key to AUR profile +cat ~/.ssh/aur.pub +# Paste this into "My Account" > "SSH Public Key" on AUR website +``` + +### Creating a New AUR Package + +```bash +# Clone the (empty) AUR repository +git -c init.defaultBranch=master clone ssh://aur@aur.archlinux.org/pkgname.git +cd pkgname + +# You'll see: "warning: You appear to have cloned an empty repository." +# This is expected for new packages + +# Add your PKGBUILD +cp ~/packages/mypackage/PKGBUILD . + +# Generate .SRCINFO (REQUIRED) +makepkg --printsrcinfo > .SRCINFO + +# Add files +git add PKGBUILD .SRCINFO + +# Commit +git commit -m "Initial upload" + +# Push +git push +``` + +### The .SRCINFO File + +The `.SRCINFO` file is a machine-readable representation of PKGBUILD metadata. **It must be regenerated and committed whenever PKGBUILD changes.** + +```bash +# Generate .SRCINFO +makepkg --printsrcinfo > .SRCINFO + +# Always commit both files together +git add PKGBUILD .SRCINFO +git commit -m "Update to version X.Y.Z" +git push +``` + +### AUR Submission Rules + +1. **No duplicates** - Don't submit packages already in official repos +2. **Must be useful** - Packages should benefit the community +3. **Must be legal** - Comply with licensing terms +4. **x86_64 only** - Packages must support x86_64 +5. **No replaces for AUR** - Don't use `replaces` unless renaming a package +6. **Maintain your packages** - Respond to comments and keep packages updated + +### Updating an AUR Package + +```bash +cd ~/aur/mypackage + +# Update PKGBUILD +# ... edit PKGBUILD ... + +# Regenerate .SRCINFO +makepkg --printsrcinfo > .SRCINFO + +# Commit and push +git add PKGBUILD .SRCINFO +git commit -m "Update to version X.Y.Z" +git push +``` + +--- + +## 10. Package Maintenance + +### Responding to Feedback + +- Monitor comments on your AUR package page +- Address bug reports and feature requests +- Thank users for helpful feedback +- Don't leave comments for every version update + +### Flagging Out-of-Date Packages + +If you find an unmaintained package: + +1. Flag it as out-of-date with details +2. Email the maintainer if possible +3. After 2 weeks with no response, file an orphan request + +### Adopting Orphaned Packages + +Orphaned packages can be adopted by any registered AUR user: + +```bash +# Clone the existing repository +git clone ssh://aur@aur.archlinux.org/pkgname.git + +# Make your changes and push +``` + +### Deletion Requests + +Submit deletion requests for: +- Duplicate packages +- Packages moved to official repos +- Abandoned/broken packages with no maintainer + +--- + +## 11. Best Practices and Common Mistakes + +### Do's + +✅ **Use HTTPS sources** when available +✅ **Verify sources** with checksums and PGP signatures +✅ **Use `$pkgname` and `$pkgver` variables** in source URLs +✅ **List all direct dependencies** even if transitively satisfied +✅ **Test in a clean chroot** before submitting +✅ **Use `--prefix=/usr`** for configure scripts +✅ **Include licenses** in `/usr/share/licenses/$pkgname/` +✅ **Use `install` command** instead of `cp` for proper permissions +✅ **Add backup array** for config files in `/etc` + +### Don'ts + +❌ **Never install to `/usr/local`** - Arch packages use `/usr` +❌ **Never modify `$srcdir`** outside of `prepare()` +❌ **Don't use `sudo` in functions** - makepkg handles privileges +❌ **Avoid custom variables without `_` prefix** - May conflict with makepkg +❌ **Don't skip checksums** without good reason +❌ **Don't use `replaces` in AUR packages** - Use `conflicts` instead +❌ **Don't leave empty directories** in packages +❌ **Don't include `.git` directories** in packages + +### Common Mistakes + +**Wrong:** Installing with DESTDIR missing + +```bash +package() { + make install # Files go to real system! +} +``` + +**Right:** + +```bash +package() { + make DESTDIR="$pkgdir" install +} +``` + +--- + +**Wrong:** Hardcoded paths + +```bash +source=("https://example.com/myapp-1.0.0.tar.gz") +``` + +**Right:** + +```bash +source=("https://example.com/${pkgname}-${pkgver}.tar.gz") +``` + +--- + +**Wrong:** Missing direct dependency + +```bash +depends=('qt5-base') # Missing qt5-svg even though app uses it +``` + +**Right:** + +```bash +depends=('qt5-base' 'qt5-svg') # Both are direct dependencies +``` + +--- + +**Wrong:** Version with hyphen + +```bash +pkgver=1.0.0-beta1 +``` + +**Right:** + +```bash +pkgver=1.0.0_beta1 +``` + +--- + +## 12. Quick Reference + +### Minimal PKGBUILD Checklist + +``` +☐ pkgname (lowercase, valid characters) +☐ pkgver (no hyphens) +☐ pkgrel=1 +☐ pkgdesc (≤80 chars) +☐ arch=('x86_64') or arch=('any') +☐ url +☐ license (SPDX identifier) +☐ depends (all direct runtime deps) +☐ makedepends (build-only deps) +☐ source (with variables) +☐ sha256sums (or valid checksums) +☐ build() or package() function +☐ package() function (required) +``` + +### Common Commands + +```bash +# Build package +makepkg -s + +# Build and install +makepkg -si + +# Generate checksums +makepkg -g >> PKGBUILD +# or: updpkgsums + +# Generate .SRCINFO +makepkg --printsrcinfo > .SRCINFO + +# Check PKGBUILD with namcap +namcap PKGBUILD + +# Check built package +namcap *.pkg.tar.zst + +# Build in clean chroot +pkgctl build + +# List package contents +pacman -Qlp *.pkg.tar.zst + +# Install local package +sudo pacman -U *.pkg.tar.zst +``` + +### File Locations + +| Location | Purpose | +|----------|---------| +| `/usr/bin/` | Executables | +| `/usr/lib/` | Libraries | +| `/usr/share/` | Architecture-independent data | +| `/usr/share/doc/$pkgname/` | Documentation | +| `/usr/share/licenses/$pkgname/` | License files | +| `/usr/share/man/` | Man pages | +| `/etc/` | System configuration (add to `backup` array) | + +### Useful Links + +- [Creating packages - ArchWiki](https://wiki.archlinux.org/title/Creating_packages) +- [PKGBUILD - ArchWiki](https://wiki.archlinux.org/title/PKGBUILD) +- [Arch package guidelines](https://wiki.archlinux.org/title/Arch_package_guidelines) +- [AUR submission guidelines](https://wiki.archlinux.org/title/AUR_submission_guidelines) +- [VCS package guidelines](https://wiki.archlinux.org/title/VCS_package_guidelines) +- [makepkg man page](https://man.archlinux.org/man/makepkg.8) +- [PKGBUILD man page](https://man.archlinux.org/man/PKGBUILD.5) + +--- + +*This guide consolidates information from the official Arch Linux Wiki and man pages. For the most up-to-date information, always refer to the official documentation.* diff --git a/garden/index.md b/garden/index.md new file mode 100644 index 0000000..45c0e1e --- /dev/null +++ b/garden/index.md @@ -0,0 +1,8 @@ +title: Digital Garden + +# garden + +A loosely organised collection of notes, thoughts and references — things I want to remember and occasionally share. + +Unlike blog posts these notes are living documents; they grow and change over time. + diff --git a/garden/system.md b/garden/system.md new file mode 100644 index 0000000..e404c0b --- /dev/null +++ b/garden/system.md @@ -0,0 +1,258 @@ +title: Overview of Knowledge‑Management Systems + +*Generated using [duck.ai](https://duck.ai) (GPT-OSS model)* + +# Overview of Knowledge‑Management Systems + +Modern knowledge‑work demands a reliable way to capture, organize, retrieve, and act on information. Four of the most popular frameworks are **Getting Things Done (GTD)**, **Zettelkasten**, **PARA (Projects, Areas, Resources, Archives)**, and **CODE (Capture‑Organize‑Distill‑Express)**. They can be implemented as part of a broader **Personal Knowledge Management (PKM)** practice and combined with the **Bullet Journal** method for analog workflows. + +Below each system is explained in depth, followed by a side‑by‑side comparison and practical tips for using them both digitally and on paper. + +--- + +## 1. Getting Things Done (GTD) + +### History +- **Creator:** David Allen, a productivity consultant. +- **First published:** *Getting Things Done: The Art of Stress‑Free Productivity* (2001). +- **Evolution:** The core five‑step workflow has remained stable; later editions added the “Two‑Minute Rule” and refined the weekly review. + +### Core Principles + +1. **Capture** – Anything that has your attention (tasks, ideas, commitments) is recorded in an external “inbox”. +2. **Clarify** – Each item is processed: decide if it’s actionable, and if so, define the next physical action. +3. **Organize** – Actions are placed into appropriate lists (Next Actions, Waiting For, Projects, Someday/Maybe). +4. **Reflect** – Weekly review of all lists to ensure they’re current and trustworthy. +5. **Engage** – Choose what to work on based on context, time, energy, and priority. + +### Digital Implementation + +| Tool | How it fits GTD | Example Setup | +|------|----------------|---------------| +| Todoist / Things | Inbox → “Quick Add” → automatic project tagging | Use the “Inbox” project for capture; a filter view shows “Next Actions”. | +| Notion | Database with views for “Projects”, “Next Actions”, “Someday”. | Create a master table; use roll‑up fields for weekly review. | +| Evernote / OneNote | Capture notes, then move to “Actionable” notebook after clarification. | Tag items with `@next`, `@waiting`, etc. | + +### Typical Digital Workflow +1. **Capture** – Press the “Quick Add” button in Todoist; the entry lands in the *Inbox* project. +2. **Clarify** – In the *Inbox* view, click each item, choose “Add to Project” or “Mark as Someday”. +3. **Organize** – Projects become separate Todoist projects; next‑action tasks get the `@next` label. +4. **Reflect** – A saved filter `@next & !@waiting` shows the current actionable list; run it every morning. +5. **Engage** – Use Todoist’s “Today” view (context‑aware) to pick tasks that match your time/energy. + +### Analog (Pen & Paper) Implementation + +- **Inbox notebook** – a small pocket‑size notebook for capture. +- **Processing sheet** – a one‑page checklist: “Is it actionable? → Next action / Defer / Trash”. +- **Project index** – a simple table of project names, outcomes, and next actions. +- **Weekly review log** – a dedicated page where you tick off each list’s status. + +### Analog Example +- **Morning capture:** Write every loose thought on a pocket‑size “Inbox” notebook. +- **Processing:** At 9 am, flip each line, ask “Is it actionable?” If yes, write the next physical step on a sticky note and attach it to the relevant project page in a binder. +- **Weekly review:** Open the binder, scan the “Projects” list, cross‑check each project’s outcome, and move completed items to the “Archive” section. + +### Core Resources +| Type | Title | Link / Reference | +|------|-------|------------------| +| Book | *Getting Things Done* (2001, updated 2022) | ISBN 978‑0143126560 | +| Official Site | GTD® – The Official Site | <https://gettingthingsdone.com> | +| Podcast | “The GTD® Podcast” (hosted by David Allen) | Apple/Spotify | +| Apps (GTD‑friendly) | Todoist, Things, OmniFocus, Nirvana | – | +| Community | r/productivity, GTD Connect (forum) | – | + +--- + +## 2. Zettelkasten + +### History +- **Originator:** German sociologist **Niklas Luhmann** (1927‑1998). +- **Method name:** *Zettelkasten* (German for “slip box”). +- **Timeline:** Luhmann built a physical box of ~90 000 index cards from the 1960s onward; his 2005 book *Communicating with Slip Boxes* popularized the technique among scholars. + +### Core Concepts + +- **Atomic notes** – each note contains a single idea, expressed in your own words. +- **Unique IDs** – traditionally a timestamp (e.g., `2025-10-08-1432`) that serves as a permanent reference. +- **Links & Backlinks** – notes are connected via explicit references, forming a network of ideas. +- **Emergent structure** – the system’s organization evolves as you add more notes; there is no rigid hierarchy. + +### Digital Implementation + +| Platform | Features that support Zettelkasten | +|----------|-----------------------------------| +| Obsidian | Markdown files, bidirectional links, graph view, plugins for automatic ID generation. | +| Roam Research | Inline linking, daily notes, “References” pane for backlinks. | +| Logseq | Hierarchical blocks with backlinks, export to plain‑text markdown. | + +### Typical Digital Workflow (Obsidian) +1. **Inbox note** – `inbox.md` receives raw ideas via quick capture hotkey. +2. **Create atomic note** – Press “Create new note from selection”; Obsidian auto‑generates a timestamp ID (`2025-10-08-1432`). +3. **Write** – One paragraph, a single idea, include source citation. +4. **Link** – Insert `[[2025-10-08-1432]]` in related notes; backlinks appear automatically. +5. **Review** – Use the “Graph View” to spot clusters; weekly, follow a random link chain to discover new synthesis. + +### Analog Implementation + +- **Index cards** (e.g., 3×5 cm). Write one idea per card, assign a numeric ID (e.g., `2025‑001`). +- **Linking** – on the back of a card, list IDs of related cards. +- **Master index** – a simple ledger where each ID is logged with a short title for quick lookup. +- **Storage** – a box with dividers for “Inbox”, “Processed”, and “Archive”. + +### Core Resources + +| Type | Title | Link / Reference | +|------|-------|------------------| +| Book | *How to Take Smart Notes* – Sönke Ahrens (2017) | ISBN 978‑1542866507 | +| Software | Obsidian, Roam Research, Logseq, Zettlr | – | +| Blog series | “Zettelkasten Method” by Zettelkasten.de | <https://zettelkasten.de> | +| Community | r/Zettelkasten, Zettelkasten Forum | – | + +--- + +## 3. PARA (Projects, Areas, Resources, Archives) + +### History +- **Creator:** Tiago Forte, productivity strategist and founder of **Fortelabs**. +- **First introduced:** 2017 in the “Building a Second Brain” online course. +- **Goal:** Provide a simple, universal filing system that works across any tool (files, notes, apps). + +### Structure + +| Category | Definition | Typical Contents | +|----------|------------|------------------| +| **Projects** | Temporary outcomes with a clear deadline. | “Write blog post on GTD”, “Launch product MVP”. | +| **Areas** | Ongoing responsibilities that have no end date. | “Health”, “Finances”, “Professional development”. | +| **Resources** | Reference material useful for multiple projects/areas. | Articles, templates, research notes. | +| **Archives** | Inactive items kept for future reference. | Completed project folders, old resources. | + +### Digital Implementation + +- **Notion** – a top‑level page for each category; sub‑pages for individual projects. +- **Obsidian** – separate vault folders: `Projects/`, `Areas/`, `Resources/`, `Archive/`. +- **File system** – simple folder hierarchy on cloud storage (e.g., Google Drive). + +### Typical Digital Setup (Notion) +- **Top‑level pages:** `Projects`, `Areas`, `Resources`, `Archive`. +- **Projects page:** Table with columns – *Name*, *Outcome*, *Next Action*, *Due*. +- **Areas page:** List of ongoing responsibilities (e.g., “Health”, “Finances”). +- **Resources page:** Sub‑pages for topics; each contains linked notes, PDFs, web‑clippings. +- **Archive page:** Drag‑and‑drop completed projects or outdated resources; keep for reference. + +### Analog Implementation + +- **Binder system** – four main sections labeled Projects, Areas, Resources, Archives. +- **Dividers** – each project gets a tab; areas are permanent sections; resources are loose‑leaf papers; archives are stored in a back pocket. +- **Index** – a table of contents page listing each item with a short description and page number. + +### Analog Setup +- **Four‑section binder:** Use tabbed dividers labeled Projects, Areas, Resources, Archive. +- **Project sheets:** One‑page project brief (goal, deadline, next step). +- **Area logs:** Ongoing checklists (e.g., weekly health metrics). +- **Resource packets:** Loose‑leaf papers, printed articles, annotated PDFs placed in the Resources section. +- **Archive pocket:** Back pocket of the binder for completed items. + +### Core Resources +| Type | Title | Link / Reference | +|------|-------|------------------| +| Course | *Building a Second Brain* (BASB) – Tiago Forte | <https://fortelabs.co> | +| Article | “The PARA Method” – Forte Labs blog | <https://fortelabs.com/blog/para/> | +| Template | Notion PARA template (free) | Notion community | +| Book | *Building a Second Brain* (2022) | ISBN 978‑1732267615 | +| Community | r/secondbrain, Forte Labs Discord | – | + +--- + +## 4. CODE (Capture‑Organize‑Distill‑Express) + +### History +- **Origin:** Popularized by **Nat Eliason** in a 2020 blog post “The CODE Method for Knowledge Work”. +- **Purpose:** Bridge the gap between raw information consumption and concrete output, especially for writers and creators. + +### Steps + +1. **Capture** – Gather raw material (ideas, quotes, data). +2. **Organize** – Sort into categories (e.g., themes, topics). +3. **Distill** – Summarize the essence; create “core notes”. +4. **Express** – Use the distilled knowledge to produce output (writing, teaching, building). + +### Digital Example + +- **Capture**: Use a web‑clipper (e.g., Pocket) or a note‑taking app. +- **Organize**: Tag items with topics; move to a “To‑Distill” folder. +- **Distill**: Write a concise summary in a separate note, linking back to the source. +- **Express**: Pull distilled notes into a writing project (e.g., a blog post). + +### Analog Workflow +- **Capture:** Carry a small notebook; write down quotes, stats, or ideas. +- **Organize:** At the end of the day, transfer entries onto index cards grouped by theme. +- **Distill:** On a separate sheet, write a concise paragraph that captures the essence of each theme. +- **Express:** Use the distilled paragraphs as bullet points when drafting a letter, article, or presentation. + +### Core Resources +| Type | Title | Link / Reference | +|------|-------|------------------| +| Blog post | “The CODE Method” – Nat Eliason (2020) | <https://nateliason.com/blog/code-method> | +| Video | “CODE Method for Writers” – Nat Eliason (YouTube) | YouTube | +| Template | “CODE Knowledge Pipeline” – Notion template | Notion community | +| Community | r/knowledgework, Nat Eliason Discord | – | + +--- + +## 5. Personal Knowledge Management (PKM) in Practice + +PKM is the umbrella practice of **collecting, curating, and applying** information to support personal goals. The methods above are **toolkits** within PKM. A robust PKM workflow typically includes: + +1. **Input channels** – reading, listening, conversations. +2. **Capture mechanisms** – digital (apps, browser extensions) and analog (notebooks). +3. **Processing** – clarifying, tagging, linking. +4. **Storage** – hierarchical (PARA) or networked (Zettelkasten). +5. **Retrieval** – search, graph navigation, or index lookup. +6. **Output** – writing, teaching, building, decision‑making. + +Combining multiple frameworks can mitigate each method’s blind spots. For instance, GTD’s strong action‑oriented lists pair well with Zettelkasten’s deep idea network, while PARA provides a high‑level filing system that keeps projects and resources tidy. + +--- + +## 6. Bullet Journal (Analog Rapid‑Logging) + +### History +- **Creator:** Ryder Carroll, a former graphic designer. +- **First published:** *The Bullet Journal Method* (2018). +- **Philosophy:** Combine a planner, diary, and sketchbook into a single analog system that encourages mindfulness and intentionality. + +### Core Elements + +| Element | Symbol | Purpose | +|---------|--------|---------| +| **Task** | `•` | Action to be done. | +| **Event** | `○` | Scheduled occurrence. | +| **Note** | `–` | Information or observation. | +| **Migration** | `>` | Move unfinished tasks to the next day/month. | +| **Signifiers** | `*`, `!`, `?` | Highlight importance, inspiration, or question. | + +### Structure + +1. **Index** – first few pages list page numbers and titles. +2. **Future Log** – yearly overview for long‑term events. +3. **Monthly Log** – calendar + task list for the month. +4. **Daily Log** – rapid‑logging of tasks, events, notes. +5. **Collections** – dedicated pages for topics (e.g., “Books to Read”, “Project Ideas”). + +### Digital Adaptation + +- **GoodNotes / Notability** – use a digital notebook template; handwriting is captured as searchable ink. +- **OneNote** – create sections for Index, Future Log, etc., and type or handwrite entries. + +### Typical Digital Adaptation (GoodNotes) +- Import a dot‑grid PDF template. +- Use Apple Pencil to handwrite daily logs; GoodNotes makes the ink searchable, allowing quick retrieval of a task or note. +- Export a month’s log as PDF for backup or sharing. + +### Core Resources +| Type | Title | Link / Reference | +|------|-------|------------------| +| Book | *The Bullet Journal Method* (2018) | ISBN 978‑0525536431 | +| Official Site | Bullet Journal (bulletjournal.com) | <https://bulletjournal.com> | +| Community | r/bulletjournal, Bullet Journal Facebook groups | – | +| Templates | Printable dot‑grid journals (free) | Various sites | |