examples/README.md

   1 This directory contains simple examples which combine `aur(1)` programs. They
   2 typically have fixed options, are expected to be modified by the user, and are
   3 documented line-by-line.
   4
   5 ## sync-devel
   6
   7 The aim of this script is to take all VCS (version control) packages in a local
   8 repository, update the source files to the latest upstream revision, and build
   9 them if there are any changes. VCS packages typically have `pkgver` set to the
  10 upstream revision at the time of AUR package submission, and so are not
  11 automatically updated by commands such as `aur-sync -u`.
  12
  13 The sample script retrieves the contents of the local repository with `aur-repo
  14 --list`, and performs two updates:
  15
  16 1. Retrieve new AUR revisions with `aur-fetch(1)` and inspect them with
  17    `aur-view(1)`
  18 2. Retrieve new upstream revisions with `aur-srcver(1)`
  19
  20 If PKGBUILD directories are not available in `AURDEST`, they are cloned anew
  21 with `aur-fetch -e`. If the local repository exclusively contains AUR packages,
  22 `aur-fetch` can be used without `--existing`.
  23
  24 The full version (`epoch:pkgver-pkgrel`) is then compared to the contents of the
  25 local repository with `aur-vercmp(1)`. If there is an update, the package is
  26 built with `aur-build(1)`.
  27
  28 ## vercmp-devel
  29
  30 A simplified version of `sync-devel` which does only runs `aur-srcver` and
  31 `aur-vercmp` on targets in the local repository.
  32
  33 Note: `aur-fetch` is not run in this script, and it is assumed all PKGBUILD
  34 directories are available. This suggests to use a persistent directory for
  35 `AURDEST`, instead of the default `$XDG_CACHE_HOME/aurutils/sync` used by
  36 `aur-sync(1)`.
  37
  38 ## sync-asroot
  39
  40 `aur-build` operates as a regular user, with the following exceptions:
  41
  42 * installation of package dependencies with `makepkg -s`;
  43 * updating the local repository with `pacman -S`;
  44 * interacting with an nspawn container with `aur-chroot`.
  45
  46 Instead of elevating to the root user for these tasks, `aur-build` can be run as
  47 root, dropping privileges where necessary. `sync-asroot` does do by running
  48 `makepkg`, `gpg`, `repo-add` and `aur-build--pkglist` with `runuser -u <user>`.
  49 Sources are also retrieved this way with `runuser -u <user> aur sync`.
  50
  51 Other possible agents are `runuser`, `setpriv`, and `systemd-run`.
  52
  53 > **Note**
  54 > Dropping privileges allows to restrict elevated commands during the build process.
  55 >
  56 > For example, if `sudo` is run in the same session as `makepkg` (for example through
  57 > `makepkg --syncdeps`), commands in the PKGBUILD or upstream sources may run `sudo`
  58 > without authorization for a period of `timeout_timestamp`. This defaults to 5 minutes.
  59 >
  60 > The following steps can be taken to avoid this:
  61 >
  62 > 1. specify a build user without `sudoers` access;
  63 > 2. set `timeout_timestamp` to 0;
  64 > 3. disable the `setuid` bit with `setpriv --no-new-privs`.
  65 >
  66 > **Warning**
  67 > The considerations above do _not_ apply to chroot builds. Building packages with `makechrootpkg`
  68 > gives the build process unfettered access to the host, regardless of how the build user is configured:
  69 >
  70 > 1. `makechrootpkg` executes any commands contained in the user's `makepkg.conf(5)` as root;
  71 > 2. arbitrary paths on the host can be overwritten with `makechrootpkg --bind`;
  72 > 3. any pacman commands inside the nspawn container can be run with `sudo`, including `pacman -U`.
  73
  74 ## sync-list
  75
  76 When using `aur-sync(1)` or `aur-build(1)`, packages accumulate in (one or
  77 several) local repositories. To avoid unused packages, a list of packages can be
  78 created such that the local repository only contains this list (and any
  79 dependencies).
  80
  81 The script `sync-list` creates a copy of the local repository, and removes any
  82 entries that are not part of the list or its dependencies with
  83 `repo-remove`. Existing packages are symlinked in the temporary
  84 directory. Targets are then passed to `aur-sync(1)`, with a temporary
  85 `pacman.conf` file pointing to the temporary directory. Finally, the state is
  86 transfered to the local repository with `rsync --delete`.
  87
  88 Other approaches include:
  89
  90 1. Only update the desired targets, e.g. `xargs -a list.txt aur sync` instead of
  91    `aur sync -u`
  92 2. Recreate the local repository on every build
  93 3. Use a "secondary" repository (e.g. `custom-testing`), moving packages to the
  94    "primary" repository after a certain time.
  95
  96 The second approach implies running `repo-add` for each package, which may be
  97 slow for a large set of packages. The first alternative is sufficient to avoid
  98 unused upgrades with `aur-sync -u`. Cleanups can then be done periodically:
  99
 100 ```bash
 101 $ grep -Fxvf list.txt <(aur repo --list | cut -f1) | xargs -r repo-purge -f custom
 102 ```
 103
 104 ## sync-rebuild
 105
 106 Package rebuilds are commonly done when package dependencies are updated in an
 107 incompatible way, such that the original package is no longer functional.
 108 `pkgrel` increments ensure that the rebuilt packages are propagated to all
 109 clients of the local repository.
 110
 111 Assuming a list of rebuild targets is known, `sync-rebuild` performs the
 112 following steps:
 113
 114 1. Retrieve and inspect all source files with `aur sync`
 115 2. Retrieve all versions of packages in the local repository
 116 3. If `pkgver` matches the local repository version, set `pkgrel` in the
 117    `PKGBUILD` to the local repository version, incremented by `0.1`. Otherwise,
 118    leave the `PKGBUILD` unmodified.
 119 4. Build the package with `aur-build`. If the build fails, restore the original
 120    `PKGBUILD`
 121 5. Print any targets which are cached by `pacman` but not available in the local
 122    repository.
 123
 124 In step 3, the local repository version is written explicitly to the `PKGBUILD`
 125 in case the incremented version is lost, or otherwise restored (e.g. with
 126 `git-reset`). The fractional part is always increased; for example, a `pkgrel`
 127 of `35.9` is increased to `35.10`, not `36`.
 128
 129 `aur-repo` can be used to retrieve a list of packages that depend on specific
 130 package. For example:
 131
 132 ```bash
 133 aur repo --search '^python.*' --search-by depends --list
 134 ```
 135
 136 > **Note**
 137 > By default, AUR packages are rebuilt in dependency order. When using
 138 > `--no-sync` or non-AUR packages, targets are rebuilt in sequential order. In
 139 > this case, `arch-rebuild-order` can be used as follows:
 140 >
 141 > `$ arch-rebuild-order --repos=custom <targets...>`
 142 >
 143 > If one dependency fails to build, `sync-rebuild` will try rebuilding the package
 144 > that depends on it anyway. To avoid this, use the `--fail-fast` option.
 145
 146 ## view-delta
 147
 148 `aur-view(1)` uses `vifm(1)` or a comparable file manager set in
 149 `AUR_PAGER` to inspect and edit build files.
 150
 151 `view-delta` assumes that files are not edited before the build process,
 152 and takes the following approach:
 153
 154 1. display diffs side-by side with `git-delta`;
 155 2. display remaining files with `bat` for syntax highlighting.
 156
 157 A pager (defaults to `less`) is used for navigation. To allow aborting
 158 the inspection process with a non-zero exit code, a confirmation prompt
 159 is displayed.
 160
 161 `view-delta` can be used as any other file manager taking a directory
 162 argument:
 163
 164 ```bash
 165 view-delta <path to build files>  # directly
 166 AUR_PAGER=view-delta aur view ... # with aur-view
 167 AUR_PAGER=view-delta aur sync ... # with aur-view wrappers
 168 ```