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-list
  39
  40 When using `aur-sync(1)` or `aur-build(1)`, packages accumulate in (one or
  41 several) local repositories. To avoid unused packages, a list of packages can be
  42 created such that the local repository only contains this list (and any
  43 dependencies).
  44
  45 The script `sync-list` creates a copy of the local repository, and removes any
  46 entries that are not part of the list or its dependencies with
  47 `repo-remove`. Existing packages are symlinked in the temporary
  48 directory. Targets are then passed to `aur-sync(1)`, with a temporary
  49 `pacman.conf` file pointing to the temporary directory. Finally, the state is
  50 transfered to the local repository with `rsync --delete`.
  51
  52 Other approaches include:
  53
  54 1. Only update the desired targets, e.g. `xargs -a list.txt aur sync` instead of
  55    `aur sync -u`
  56 2. Recreate the local repository on every build
  57 3. Use a "secondary" repository (e.g. `custom-testing`), moving packages to the
  58    "primary" repository after a certain time.
  59
  60 The second approach implies running `repo-add` for each package, which may be
  61 slow for a large set of packages. The first alternative is sufficient to avoid
  62 unused upgrades with `aur-sync -u`. Cleanups can then be done periodically:
  63
  64 ```bash
  65 $ grep -Fxvf list.txt <(aur repo --list | cut -f1) | xargs -r repo-purge -f custom
  66 ```
  67