path: root/docs/05-using_apkg.md

# Using autils

autils is a collection of POSIX shell scripts for source-based package management on Alice Linux.

For full command details, see the man pages: `man apkg`, `man reposync`, etc.

## Installation

```sh
make install
```

This installs all scripts to `/usr/bin` and man pages to `/usr/share/man/man8`. Override with:

```sh
make install DESTDIR=/tmp/root PREFIX=/usr/local
```

## Core concepts

The package manager, **apkg**, builds packages from source using `abuild` recipe files and installs them as `.spm` packages via the **spm**(8) backend. Package recipes live in git repositories referenced by the `APKG_REPO` environment variable.

Configuration is done through environment variables: there is no config file.

## Basic usage

### Building a package

From inside a recipe directory:

```sh
cd /path/to/repo/mypkg
apkg
```

This fetches sources, verifies checksums, builds, and creates a `.spm` in `$APKG_PACKAGE_DIR`.

### Installing and upgrading

```sh
apkg -i mypkg          # build and install
apkg -i                # same, from inside the recipe directory
apkg -I firefox        # install with automatic dependency resolution
apkg -u mypkg          # upgrade (rebuild and reinstall)
apkg -f mypkg          # force rebuild even if .spm already exists
apkg -o mypkg          # download sources only, don't build
```

### Removing packages

```sh
apkg -r mypkg          # remove a package
apkg-purge mypkg       # show what would be removed (dry-run)
apkg-purge -p mypkg    # remove package and its unneeded dependencies
```

### Searching and listing

```sh
apkg -s icon           # search packages by name pattern
apkg -s -v icon        # search with version info
apkg -a                # list all installed packages
apkg -a -v             # list installed packages with versions
apkg -S libpng.so      # find which package owns a file
apkg -l                # list outdated packages on the system
```

### Dependency queries

```sh
apkg -d mypkg          # list direct dependencies of a package
apkg -D mypkg          # list all dependencies recursively, in install order
apkg -j mypkg          # list packages that depend on mypkg
```

### System upgrade

```sh
apkg -U
```

This checks all installed packages for outdated versions, resolves the full dependency tree, installs any new packages, then upgrades existing ones. Set `APKG_NOPROMPT=1` to skip the confirmation prompt (useful for scripting). Packages listed in `APKG_MASK` are skipped.

### Checksums and file lists

```sh
apkg -g mypkg          # regenerate .shasum file
apkg -k mypkg          # regenerate .files list from the .spm
```

### Triggers

After installing or upgrading packages, apkg can refresh system caches:

```sh
apkg -t                # run triggers for all installed packages
apkg -t mypkg          # run only triggers relevant to mypkg
```

Triggers include: fontconfig cache, GDK-Pixbuf loaders, GIO modules, GSettings schemas, GTK input method modules, icon theme cache, udev hardware database, X font indices, desktop MIME cache, and shared MIME database. Each trigger only fires if the package actually provides files that need it.

## Helper scripts

### Package inspection

```sh
apkg-deps mypkg        # show runtime library dependencies (via ldd)
apkg-foreign           # list installed packages not found in any repo
apkg-orphan            # list packages with no dependents installed
```

### Cleanup

```sh
apkg-clean             # list stale .spm and source files
apkg-clean | xargs rm  # actually remove them
apkg-clean -p          # list only stale packages
apkg-clean -s          # list only stale sources
```

### Dependency maintenance

```sh
apkg-redundantdeps mypkg       # find transitive deps listed explicitly
apkg-redundantdeps              # check all packages
apkg-redundantdeps -f mypkg     # fix by removing redundant entries
```

### Scaffolding

```sh
apkg-genabuild https://example.com/pkg-1.2.3.tar.gz
apkg-genabuild https://github.com/user/repo/archive/v1.0.tar.gz
```

Derives `name` and `version` from the URL and creates a directory with a skeleton `abuild`. Recognizes GitHub tag archives, PyPI packages (prefixes `python-`), and CPAN packages (prefixes `perl-`). An optional second argument overrides the name.

## Standalone utilities

### revdep: find broken library links

Scans system binaries and libraries for missing shared library dependencies. Run after major upgrades, especially those with library version bumps.

```sh
revdep         # plain output
revdep -v      # verbose progress
```

**Note:** revdep only reports problems; it does not rebuild anything. Use `apkg -f` to rebuild affected packages.

### updateconf: merge .new config files

When packages are upgraded, new default config files are installed with a `.new` suffix to avoid overwriting local changes. Run `updateconf` as root to interactively handle them:

```sh
updateconf
```

For each `.new` file it shows a diff and prompts:
- **U**: update: replace current with new
- **D**: discard: delete the `.new` file, keep current
- **E**: edit: open current file in `$EDITOR` (default: `vi`)
- **K**: keep: leave both files as-is

### reposync: sync git repositories

Syncs git-based package repos using `REPOSYNC_*` environment variables:

```sh
export REPOSYNC_CORE="https://codeberg.org/emmett1/alicelinux.git|main|/var/lib/alicelinux"
export REPOSYNC_EXTRA="https://codeberg.org/emmett1/extra.git|main|/var/lib/alicelinux/extra"
reposync
```

Options:
- **`-n`**: dry-run
- **`-l`**: log to `/var/log/reposync.log`
- **`-f`**: force fresh clones
- **`-h`**: help

## Working in a chroot

```sh
apkg-chroot /mnt/alice                  # enter interactive shell
apkg-chroot /mnt/alice apkg -i mypkg    # run apkg inside chroot
```

Mounts `/dev`, `/proc`, `/sys`, `/run`, copies `/etc/resolv.conf`, and cleans up on exit. Must be run as root.

## Environment variables

### Core paths

- **`APKG_REPO`** (default: `$PWD`): Space-separated repo directories, searched in order
- **`APKG_PACKAGE_DIR`** (default: `$PWD`): Where built `.spm` files are stored
- **`APKG_SOURCE_DIR`** (default: `$PWD`): Source tarball cache
- **`APKG_WORK_DIR`** (default: `$PWD`): Build working tree (extraction + fakeroot)
- **`APKG_ROOT`** (default: `/`): Alternative install root

### Build behavior

- **`APKG_NOPROMPT`**: Skip confirmation prompt in `-I` and `-U`
- **`APKG_KEEP_WORKDIR`**: Keep build tree on failure (for debugging)
- **`APKG_ALIAS`**: Dependency substitution: `real:alias` pairs (e.g. `openssl:libressl`)
- **`APKG_MASK`**: Packages to skip during `-l` and `-U`

### Logging

- **`APKG_LOG`**: Enable build logging
- **`APKG_LOG_DIR`**: Directory for log files (filename: `$name.log`)

### Compiler

- **`CFLAGS`**, **`CXXFLAGS`**: Compiler flags (used by cmake builds)
- **`CROSS_COMPILE`**: Prefix for `strip` (e.g. `x86_64-linux-musl-`)

## Common workflows

### Building and installing a new package

```sh
cd $APKG_REPO
apkg-genabuild https://example.com/mypkg-1.0.tar.gz
cd mypkg
# edit abuild as needed, add depends file
apkg -I mypkg
```

### Full system maintenance

```sh
reposync                     # sync repos
apkg -U                      # system upgrade
revdep                       # check for broken libraries
updateconf                   # merge config files
apkg-clean | xargs rm        # clean up stale files
apkg-orphan                  # review packages to potentially remove
```

### Debugging a failed build

```sh
APKG_KEEP_WORKDIR=1 apkg -f mypkg
# inspect $APKG_WORK_DIR/apkg-src-mypkg and apkg-pkg-mypkg
```