starkpm — starkOS

Overview

Installing a built package means extracting it directly onto the real system. After installation, every extracted file is recorded in an index directory: starkpm keeps a full record of installed files, automatically resolves dependency order, and reads the build script (spkgbuild) from the port directory to obtain the variables and functions it needs before building.

spkgbuild format

spkgbuild is the build script used by portbuild to generate the package. Example:

description="This is example package"
homepage="https://example.com/"
maintainer="starkOS Team, starkos at disroot dot org"

name=foobar
version=1.0.0
release=1
backup="etc/example.conf etc/foobar.conf"
noextract="foobar.tar.xz"
source="https://dl.example.com/foobar.tar.xz
        $name-$version.tar.gz::https://github.com/archive/$version.tar.gz
        example.conf"
nostrip="lib.*/ld-.*\.so$
        lib.*/libc-.*\.so$
        lib.*/libpthread-.*\.so$
        lib.*/libthread_db-.*\.so$"

build() {
    cd $name-$version

    ./configure --prefix=/usr
    make
    make DESTDIR=$PKG install

    install -d $SRC/example.conf $PKG/etc/example.conf
}

depends is defined in a separate file, one dependency per line. Before creating a new port, it's recommended to build it first with fakeroot to make sure the script doesn't fail and doesn't leave unregistered files on the system.

Field	Description
description	Short description of the package.
homepage	URL of the software's website.
maintainer	Maintainer's name and email.
name	Package name; must match the port's directory name.
version	Package version.
release	Package release number, useful when the script changes without the version changing.
backup	Files that should be backed up when upgrading the package (no leading '/').
noextract	Files that should not be extracted, space-separated.
source	Space-separated source URLs. <new-name>::<url> can be used to save the file under a different name.
depends	All required dependencies, one per line, in a separate file.

Global configuration

Defined in /etc/starkpm.conf. Default values (commented out):

#
# Configuration file for starkpm
#

export CFLAGS="-O2 -march=x86-64 -pipe"
export CXXFLAGS="${CFLAGS}"
export FCFLAGS="${CFLAGS}"
export FFLAGS="${CFLAGS}"
export MAKEFLAGS="-j$(nproc)"
export LDFLAGS="-Wl,-O1 -Wl,--as-needed -Wl,-z,pack-relative-relocs"

# SOURCE_DIR="/var/cache/starkpm/sources"
# PACKAGE_DIR="/var/cache/starkpm/packages"
# WORK_DIR="/var/cache/starkpm/work"
# CBUILD_DIR="/var/lib/starkpm/cbuild"
# CURL_OPTS=""
# COMPRESSION_MODE="xz"
# NO_STRIP="no"
# IGNORE_CHECKSUM="no"
# KEEP_DOC="no"
# KEEP_GOING="no" 
# KEEP_LIBTOOL="no"
# KEEP_LOCALE="no"
# NOCOLOR="no"
# THEME="starkos"   # variants: 'dracula', 'nord', 'starkos'

Main tools

portadd

Installs and upgrades packages already built by portbuild. Installing means extracting the <name>-<version>-<release>.spkg.xz package with tar onto the real system and saving the list of extracted files. Upgrading does the same, replacing the old files and removing any that no longer exist in the new package (like Slackware's pkgtool).

Usage:
    portadd [ <options> <package.spkg.txz> ]

Options:
    -u, --upgrade              upgrade package
    -r, --reinstall            reinstall package
    -c, --ignore-conflict      ignore conflicts when installing
    -v, --verbose              show installed files
    -h, --help                 show this help
        --no-backup            skip backup when upgrading
        --print-dbdir          print the path to the package database
        --root=<path>    install into a custom root directory

Example:
    portadd foobar-1.0-1.spkg.txz -uc --no-backup
        upgrades foobar-1.0-1 without backing up its
        previous configuration and without checking for conflicts

portbuild

Builds a package from a port. Reads spkgbuild to get the build information before generating the package, in the format <name>-<version>-<release>.spkg.xz. Must be run from inside the port's directory.

Usage:
    portbuild [ <options> <arguments> ]

Options:
    -q, --quiet                show only status messages and errors
    -i, --install              install the package on the system
    -u, --upgrade              upgrade package
    -r, --reinstall            reinstall package
    -c, --ignore-conflict      ignore conflicts when installing
    -v, --verbose              verbose install
    -f, --force-rebuild        force rebuild
    -m, --skip-checksum        skip checksum verification
    -g, --genchecksum          generate checksum
    -o, --download             download sources only
    -x, --extract              extract sources only
    -p, --pkgfiles             generate the package file list
    -w, --keep-work            keep the work directory
    -h, --help                 show this help
    -C, --clean                remove downloaded sources and built packages
    --config=<config>    use a custom configuration file
    --srcdir=<path>      override the sources path
    --pkgdir=<path>      override the built package path
    --workdir=<path>     override the work directory path
    --no-backup                skip configuration backup when upgrading

Example:
    portbuild -iw    builds and installs the package, keeping the work directory

Note: with no options, portbuild only downloads the sources and builds the
package using the default values for the rest of the options.

portdel

Removes a package from the system by reading the file list recorded in PKGDB_DIR.

Usage:
    portdel [ <options> <package name> ]

Options:
    -h, --help             show this help
    -v, --verbose          show removed files
    --root=<path>    remove the package from a custom root directory

Example:
    portdel firefox -v
        removes firefox, showing the removed files.

portrebuild

Rebuilds the base packages in the correct order, including the toolchain.

Usage:
    portrebuild <options>

Options:
    -t, --toolchain   rebuild the toolchain
    -b, --base        rebuild the base ports
    -h, --help        show this help

Example:
    portrebuild       rebuilds the toolchain and base, in that order
    portrebuild -t    rebuilds only the toolchain
    portrebuild -b    rebuilds only the base ports

portbase

Removes every package except those in the base system and any the user specifies.

Usage:
    portbase <options>

Options:
    -n  dry-run
    -y  don't ask for confirmation
    -h  show this help

portsync

Synchronizes ports and keeps the system's repositories up to date.

Usage:
    portsync [options]

Options:
    -p, --prune              clean the local git repository
    -r, --reset              reset the git repositories
    -s, --source <repos>     sync only the given repos (space-separated)
    -h, --help               show this help

Examples:
    portsync                 syncs all repos
    portsync --source main   syncs only 'main'
    portsync -s main custom  syncs 'main' and 'custom'
    portsync -r -s main      resets and syncs only 'main'

portnews

starkpm's system news manager. Invoked as portnews or via stark news.

portnews                       List unread news with a TUI
portnews status                Show news statistics
portnews unread                List unread news
portnews read                  List read news
portnews ignore                List ignored news
portnews cat N                 Show unread news item N
portnews cat read N            Show read news item N
portnews cat ignore N          Show ignored news item N
portnews N                     Show unread news item N (shortcut)
portnews mv N <dst>            Move unread news item N to the destination category
portnews mv all <dst>          Move all unread items to the destination
portnews mv <src> N <dst>      Move news item N from source to destination
portnews mv <src> all <dst>    Move all news items from source to destination
portnews rm <cat> N            Remove news item N from read|ignore|unread
portnews rm <cat> all          Remove all news items from read|ignore|unread
portnews sync                  Sync news from the ports repo (requires root)
portnews restore               Restore all news items to unread from the source
portnews purge orphan          Remove local news items not present in the source
portnews purge all             Remove all news data
portnews create NAME           Create a news template
portnews help                  Show this help

stark — the main tool

stark is the front-end for portbuild, portadd, and portdel: it moves into the port's directory, calls portbuild to build and then portadd to install. It also adds extra features, such as searching packages, checking dependencies and dependents, orphans, duplicate ports, or listing what's installed. Run stark help to see every available function.

Command	Description
sync <arg>	Updates the ports database (portsync arguments).
build <ports> <arg>	Builds ports.
install <ports> <arg>	Installs ports and their dependencies.
upgrade <ports> <arg>	Upgrades ports.
sysup <arg>	Full system upgrade.
remove <ports> <arg>	Removes installed ports.
deplist <ports>	Prints every dependency of the given ports.
redeps <ports> <arg>	Looks for redundant dependencies.
cache <arg>	Cleans the package and/or source cache.
cat <port>	Shows the port's spkgbuild.
config	Shows starkpm's configuration.
dependent <port>	Shows reverse dependencies.
depends <port>	Shows dependencies.
dup	Shows duplicate ports.
files <port>	Shows the files installed by the port.
foreign	Shows foreign ports (outside the repos).
info <port>	Shows information about the port.
installed	Shows all installed ports.
integrity	Checks the integrity of installed ports.
isinstalled <port>	Checks whether a port is installed.
locate <file>	Shows the location of a file in the ports repo.
missingdep	Shows missing dependencies.
news <args>	News manager (see stark news help).
orphan	Shows installed orphan ports.
outdate	Shows outdated ports.
path <port>	Shows the port's path in the repo.
provide <file>	Shows which port provides a file.
purge [ports]	Removes installed ports and their orphaned dependencies.
search <pattern>	Searches for ports in the repo.
trigger [ports]	Runs the system's triggers.
world [ports]	Shows, adds to, or removes from the world list.
help	Shows this help.

Global options available in most commands: --append-repo, --prepend-repo, and --override-repo (to append, prepend, or override custom local repos), --repo-file, --config-file, --alias-file, and --mask-file to use files other than the defaults.

# stark install -cv firefox
Builds and installs firefox and its dependencies, ignoring file conflicts
and with verbose output

Failure tolerance (KEEP_GOING)

KEEP_GOING lets the process continue if a port fails to build during a batch upgrade or install: starkpm doesn't stop the whole operation, it carries on with the rest of the queue and shows a summary of the failures at the end, so no completed work is lost.

Custom build (cbuild)

cbuild lets you override a port's build configuration without modifying the repository's ports. Three functions are available inside any build() in a spkgbuild:

01
cbuild_restore <dest> [name]

Copies a saved configuration file into the source tree before building. Returns 1 if no saved configuration exists, so the port can fall back to its default values. Example with the "linux" port:
```
cbuild_restore "$SRC/$name-${version%.*}/.config" || cp $SRC/x86_64-dotconfig .config
```
02
cbuild_save <src> [name]

Saves a configuration file for future builds. Useful after running interactive tools like make menuconfig. Example with the "linux" port:
```
cbuild_save "$SRC/$name-${version%.*}/.config"
```
03
cbuild_options [name]

Loads a shell snippet to override build variables: configure flags, cmake options, LLVM targets, and so on. Example with "llvm", "clang" and "lld":
```
llvm:          cbuild_options       uses "llvm" by default (llvm.opt file)
clang and lld: cbuild_options "llvm" uses the "llvm" profile, overriding the port name
```

Configuration files are stored in /var/lib/starkpm/cbuild/ with explicit extensions:

Extension	Content
name.cfg	Configuration files to copy into the source tree.
name.opt	Shell snippets with build options or variables.
name.dep	Custom dependency list that overrides the port's depends file.

The .dep override is handled transparently in stark's dependency resolution: if a .dep file exists for a port, it's used instead of its depends file, letting you drop dependencies that are no longer needed given the chosen build options. A port can combine .cfg, .opt, and .dep independently.

Example with the Linux kernel — after running make menuconfig, copy the .config here:

/var/lib/starkpm/cbuild/linux.cfg

The port will pick it up automatically on the next build:
cbuild_restore "$SRC/linux-$version/.config" || make defconfig
cbuild_save    "$SRC/linux-$version/.config"

Example for LLVM targets:

$ cat /var/lib/starkpm/cbuild/llvm.opt
BUILD_LLVM_TARGETS="AMDGPU;X86"

The CBUILD_DIR path can be overridden in /etc/starkpm.conf:

CBUILD_DIR="/your/custom/path"

To filter the ports that use cbuild:

grep cbuild_ /usr/ports/*/*/spkgbuild | awk -F/ '{print $5}' | sort -u

Extra tools

starkpm also includes several scripts to make common tasks easier.

01
schroot

Mounts the necessary filesystems and enters a chroot environment. Automatically mounts /dev, /proc, /sys, /run, /tmp, and /etc/resolv.conf. If no command is given, it launches /bin/sh.
```
Usage:
    schroot <chroot-dir> [command]

Examples:
    schroot /mnt/mysystem
    schroot /mnt/mysystem portsync
    schroot /mnt/mysystem stark sysup -y
    schroot /mnt/mysystem /bin/bash
```
02

portcreate

Script for creating the template for a new port.
03

updateconf

Script for updating pending configuration files (*.spkgnew).

revdep

Reverse-dependency script worth running after upgrading or removing packages, to detect broken packages. Give it a package name if you only want to check that one.

Usage:
    revdep [option] [arg]

Options:
    -a, --all                        show every affected file
    -r, --rebuild                    rebuild and reinstall the broken package
    -p, --package <pkg>              check only a specific package
    -f, --no-filter                  skip the excluded directories, files, and libraries filter
    -e, --exclude <pkg1 pkg2 pkgN>   exclude packages when rebuilding (with -r/--rebuild)
    -y, --yes                        don't ask for confirmation when rebuilding (with -r/--rebuild)
    -h, --help                       show this help

05
hook

A hook is a shell script containing the commands that should run before (pre) or after (post) installing, upgrading, or removing a package. It's placed in the port's directory and stark runs it automatically at those points. It can also be triggered by hand:
```
Usage:
    stark hook <stage> <action> <port>

Options:
    stark hook <pre|post> <install|remove> <port>

Example:
    stark hook post install linux
```

Repository file

/etc/starkpm.repo defines the port repository directories and URLs used for syncing and updating. Example of the default file:

#
# /etc/starkpm.repo : starkpm repo file
#
# format:
#    <repo directory> <repo url> <repo branch, "main" by default>
#

/usr/ports/main       https://codeberg.org/stark-OS/main
/usr/ports/community  https://codeberg.org/stark-OS/community
#/usr/ports/kde-lxqt   https://codeberg.org/stark-OS/kde-lxqt
#/usr/ports/mate       https://codeberg.org/stark-OS/mate
#/usr/ports/xfce       https://codeberg.org/stark-OS/xfce
#/usr/ports/multilib   https://codeberg.org/stark-OS/multilib
#/usr/ports/nonfree    https://codeberg.org/stark-OS/nonfree
#/usr/ports/s6         https://codeberg.org/stark-OS/s6
#/usr/ports/testing    https://codeberg.org/stark-OS/testing

The URL is optional: you only need it if you want to be able to sync that repository.

Building starkpm from source

starkpm is part of starkOS's base system, but it can be built and installed manually by running the install script:

# ./INSTALL.sh

If you're packaging it for installation elsewhere, prefix the command with DESTDIR: DESTDIR=/tmp/path ./INSTALL.sh

portadd

portbuild

portdel

portrebuild

portbase

portsync

portnews

cbuild_restore <dest> [name]

cbuild_save <src> [name]

cbuild_options [name]

schroot

portcreate

updateconf

revdep

hook