diff options
Diffstat (limited to 'docs/using_autils.md')
| -rw-r--r-- | docs/using_autils.md | 245 |
1 files changed, 0 insertions, 245 deletions
diff --git a/docs/using_autils.md b/docs/using_autils.md deleted file mode 100644 index bbf2ce69..00000000 --- a/docs/using_autils.md +++ /dev/null @@ -1,245 +0,0 @@ -# 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 -``` |