Overview
Installing a built package consists of extracting it directly onto the real system. After installation, all extracted files are recorded in an index directory: starkpm keeps full track of installed files, automatically resolves dependency order, and reads the build script (sbuild) from the port directory to obtain the variables and functions needed before building.
sbuild format
sbuild 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 any files unregistered on the system.
| Field | Description |
|---|---|
| description | Short description of the port. |
| homepage | URL of the software's website. |
| maintainer | Name and email of the maintainer. |
| name | Port name; must match the port's directory name. |
| version | Version of the port. |
| release | Release version of the port, useful when the script changes without the version changing. |
| backup | Files that must be backed up when updating the port (no leading '/'). |
| noextract | Files that must not be extracted, separated by spaces. |
| source | Source URLs, separated by spaces. <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'
Port aliases
An alias makes installing or updating a port install another one in its place, without changing the
name it's known by on the rest of the system. It's defined in /etc/starkpm.alias,
one alias per line, with the format <real name> <alias name>:
#
# /etc/starkpm.alias : starkpm alias file
#
# format:
# <real package> <aliased package>
#
# example:
# openssl libressl
#
rust rust-bin
You can also manage aliases directly using alias stark, without having to edit the file manually:
$ stark alias help
Usage:
stark alias <command> [args]
Commands:
list list aliased ports
add <real> <alias> add/update alias: <real> is a dep of <alias> (installed port)
rm <real> remove alias for <real>
help show this help
Masked packages
Excludes ports from stark sysup, useful for temporarily freezing a problematic version without uninstalling it. It's defined in /etc/starkpm.mask, one port per line:
#
# /etc/starkpm.mask : exclude packages from sysup
#
ffmpeg
firefox
webkitgtk
You can also manage masked packages directly with stark mask:
$ stark mask help
Usage:
stark mask <command> [args]
Commands:
list list masked ports (excluded from 'stark sysup')
add <ports> add ports to mask
rm <ports> remove ports from mask
help show this help
Repository file
/etc/starkpm.repo defines the directories and URLs of the port repositories used for syncing and updating. You can add directories without a URL to define local repositories.
#
# /etc/starkpm.repo : starkpm repo file
#
# format:
# <repo directory> <repo url> <repo branch, "main" by default>
#
/usr/ports/local
/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: it's only needed if you want to be able to sync that repository.
Main tools
-
01
portadd
Installs and updates packages already built by portbuild. Installing consists of extracting the <name>-<version>-<release>.spkg.xz package with tar onto the real system and saving the list of extracted files. Updating does the same, replacing 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 on install -v, --verbose show installed files -h, --help show this help --no-backup skip backup on upgrade --print-dbdir show path of 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 -
02
portbuild
Builds a package from a port. Reads sbuild to get the build information before generating the package, with the format <name>-<version>-<release>.spkg.xz. Must be run inside the port directory.
Usage: portbuild [ <options> <arguments> ] Options: -q, --quiet show only status and error messages -i, --install install the package on the system -u, --upgrade upgrade package -r, --reinstall reinstall package -c, --ignore-conflict ignore conflicts on install -v, --verbose verbose installation -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 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 sources path --pkgdir=<path> override built package path --workdir=<path> override work directory path --no-backup skip configuration backup on upgrade --jobs=N override parallel build jobs (default: JOBS in config, or nproc) Example: portbuild -iw builds, installs the package and keeps the work directory Note: with no options, portbuild only downloads the sources and builds the package with the rest of the options at their defaults. -
03
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. -
04
portrebuild
Rebuilds base packages in the correct order, including the toolchain.
Usage: portrebuild <options> Options: -t, --toolchain rebuild the toolchain -b, --base rebuild base ports -h, --help show this help Example: portrebuild rebuilds toolchain and base, in that order portrebuild -t rebuilds the toolchain only portrebuild -b rebuilds base ports only -
05
portbase
Removes all packages except base system packages and any the user specifies.
Usage: portbase <options> Options: -n dry-run -y don't ask for confirmation -h show this help -
06
portsync
Syncs ports and keeps the system's repositories up to date.
Usage: portsync [options] Options: -p, --prune clean the local git repository -r, --reset reset 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' -
07
portnews
starkpm's system news manager. Invoked as portnews or via stark news.
portnews - system news manager for starkpm Usage: run 'portnews' or 'stark news' wrapper portnews List your unread news portnews status Show your news statistics portnews check Notify if you have unread news; exit 0 only if it did portnews unread List unread news portnews read List read news portnews ignore List ignore news portnews cat N Show unread news item N portnews cat read N Show read news item N portnews cat ignore N Show ignore news item N portnews N Show unread news item N (shortcut) portnews mv N <dst> Move unread news N to destination category portnews mv all <dst> Move all unread news to destination portnews mv <src> N <dst> Move news N from source to destination category portnews mv <src< all <dst< Move all news from source to destination portnews sync Sync news from ports repository (requires root) portnews restore Mark all news as unread again portnews purge orphan Remove from your agenda news no longer in source portnews create NAME Create news template file portnews help Show this help Directories: /usr/ports/main/NEWS Ports repository news (from git) /var/lib/starkpm/news/source Synced copy shared by all users (root writes, read-only for users) $XDG_STATE_HOME/portnews Your agenda: unread/ read/ ignore/ (per user) (default: ~/.local/state/portnews) Workflow: 1. News are maintained in git at /usr/ports/main/NEWS 2. Run 'doas portnews sync' to copy them to the shared source directory 3. Each user manages their own agenda: new news start as unread. Run portnews as your own user (not through doas) 4. 'restore' marks every news as unread again in your agenda Examples: doas portnews sync # Sync from ports repo portnews # List your unread news portnews 1 # Show first unread news item portnews cat 1 # Show first unread news item portnews cat read 1 # Show first read news item portnews cat ignore 2 # Show second ignored news item portnews mv 1 read # Move unread #1 to read (short form) portnews mv all ignore # Ignore all unread news (short form) portnews mv read 2 unread # Move read #2 back to unread (full form) portnews mv ignore all unread # Move all ignored back to unread (full form) portnews read # List read news portnews ignore # List ignore news portnews restore # Mark all news as unread again portnews purge orphan # Drop news that no longer exist in source portnews create icu-update # Create news template -
08
stark
stark is the front-end for portbuild, portadd and portdel: it changes into the port's directory, calls portbuild to build and then portadd to install. It also adds extra features, such as searching for packages, checking dependencies and dependents, orphans, duplicate ports, or listing what's installed.
Usage: stark <options> [<arg>] Options: search <pattern> find ports in repo -n, --name search in port names only sync <arg> update ports database (use portsync arg) -p, --prune prune local git repository -r, --reset reset git repositories build <ports> <arg> build ports (use portbuild arg, except '-i', '-u', '-r', '-g', & '-p') -f force rebuild package -k keep going building next package on error -m skip checksum checking -o fetch sources only -q, --quiet show only status messages and errors -w keep working directory -y skip ask user confirmation -C, --clean remove downloaded sources and prebuilt packages --log log build process (/var/log/name-version-release-date.log) --jobs=<N> override parallel build jobs (default: JOBS in config, or nproc) install <ports> <arg> install ports (use portbuild arg, except '-i' & '-u') -c ignore conflict when installing package -f force rebuild package -k keep going installing next package on error -m skip checksum checking -n skip dependencies -o fetch sources only -q, --quiet show only status messages and errors -r reinstall -w keep working directory -y skip ask user confirmation --exclude=* exclude dependencies, comma separated --no-backup skip backup when reinstalling package --jobs=<N> override parallel build jobs (default: JOBS in config, or nproc) upgrade <ports> <arg> upgrade ports (use portbuild arg, except '-i' & '-r') -c ignore conflict when installing package -f force rebuild package -k keep going upgrading next package on error -m skip checksum checking -n skip dependencies -o fetch sources only -q, --quiet show only status messages and errors -w keep working directory -y skip ask user confirmation --exclude=* exclude dependencies, comma separated --no-backup skip backup when upgrading package --jobs=<N> override parallel build jobs (default: JOBS in config, or nproc) sysup <arg> full system upgrade (use portbuild arg, except '-i', '-r' & '-u') -c ignore conflict when installing package -f force rebuild package -k keep going upgrading next package on error -m skip checksum checking -n skip dependencies -o fetch sources only -q, --quiet show only status messages and errors -w keep working directory -y skip ask user confirmation --exclude=* exclude dependencies, comma separated --no-backup skip backup when upgrading package --jobs=<N> override parallel build jobs (default: JOBS in config, or nproc) remove <ports> <arg> remove installed ports (use portdel arg) -y skip ask user confirmation deplist <ports> print all dependencies for ports -q skip installed ports --exclude=* exclude dependencies, comma separated redeps <ports> <arg> find redundant dependencies -w, --world check redundant entries in world -f, --fix fix (remove) redundant port deps / world entries cache (no args) clean packages AND sources cache -p, --pkg clean packages cache only -s, --src clean sources cache only alias <arg> manage aliased ports (run 'stark alias help' for usage) cat <port> print sbuild config print starkpm config depends <port> print dependencies dup print duplicate ports files <port> print files installed foreign print foreign ports help print this help hook <stage> <action> <port> run port hook on demand (run 'stark hook' for help) info <port> print information installed print all installed ports integrity check installed port integrity isinstalled <port> check whether port is installed (status 0=installed, 1=not installed) locate <file> print location of file in ports repo mask <arg> manage masked ports (run 'stark mask help' for usage) missingdep print missing dependencies news <args> news manager (run 'stark news help' for usage) orphan print orphan installed ports outdate print outdated ports path <port> print path in repo provide <file> print ports provided file purge <ports> remove installed ports and its orphan dependencies required <port> print reverse dependencies (required by) trigger <ports> run system trigger world <ports> print/add/remove world list Global options: --append-repo=<repo path> append custom local repo path (lowest priority, multiple) --prepend-repo=<repo path> prepend custom local repo path (highest priority, multiple) --override-repo=<repo path> override repo in $REPO_FILE with custom local repo (only these repos are used, multiple) --repo-file=<repo file> use custom repo file (default: $REPO_FILE) --config-file=<config file> use custom config file (default: $CONFIG_FILE) --alias-file=<alias file> use custom alias file (default: $ALIAS_FILE) --mask-file=<mask file> use custom mask file (default: $MASK_FILE)
Global options available on most commands: --append-repo, --prepend-repo and --override-repo (to add, prepend, or override custom local repos), --repo-file, --config-file, --alias-file and --mask-file to use alternative files instead of the defaults.
# stark install -cv firefox
Builds and installs firefox and its dependencies, ignoring file conflicts
and with verbose output
Continuing after failures (KEEP_GOING)
KEEP_GOING lets things continue if a port fails to build during a batch upgrade or install; starkpm doesn't stop the whole operation: it continues with the rest of the queue and presents a summary of failures at the end, avoiding losing work already done.
Custom build configuration (cbuild)
cbuild lets you override a port's build configuration without modifying the ports in the repository. Three functions are available inside any build() in an sbuild:
-
01
cbuild_restore <dest> [name]
Copies a saved configuration file into the source tree before building. Returns 1 if no 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 fragment to override build variables: configure flags, cmake options, LLVM targets, etc. 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 saved in /var/lib/starkpm/cbuild/ with explicit extensions:
| Extension | Content |
|---|---|
| name.cfg | Configuration files to copy into the source tree. |
| name.opt | Shell fragments with build options or variables. |
| name.dep | Custom dependency list overriding 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, allowing you to remove dependencies that are no longer needed due to 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 use it 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 ports that use cbuild:
grep cbuild_ /usr/ports/*/*/sbuild | awk -F/ '{print $5}' | sort -u
CBUILD_JOBS
Overrides the number of parallel build jobs on your processor at runtime with
--jobs=<number>. By default, CBUILD_JOBS reads MAKEFLAGS
exported from starkpm.conf if nothing is specified. If specified, it overrides the
values of all builders supported via environment variables and also exports
the CBUILD_JOBS environment variable, which can be used specifically within a
port. The main goal is to manage resource-intensive ports, such as
webkitgtk or qt6-webengine, limiting the number of jobs on
hardware that lacks the capacity to build the port successfully.
# portbuild --jobs=4
# stark sysup --jobs=4
# stark build|install|upgrade <port1> <port2> <port3> --jobs=4
Extra tools
starkpm also includes several scripts to make common tasks easier.
-
01
schroot
Mounts the required 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
[command] If 'command' is unspecified, schroot will launch /bin/sh. Arguments: Directory to use as new root filesystem [command] Command to execute inside chroot (optional) Description: This script mounts necessary filesystems and enters a chroot environment. It automatically mounts: /dev, /proc, /sys, /run, /tmp, and /etc/resolv.conf Several sessions on the same directory share the mounts; they are removed when the last session exits. Examples: schroot /mnt/mysystem schroot /mnt/mysystem portsync schroot /mnt/mysystem stark sysup -y schroot /mnt/mysystem /bin/bash schroot /mnt/mysystem /bin/mksh -c portsync Notes: - If you want to run a command using a specific shell, use: shell -c 'command' - Arguments are passed directly to the command, preserving their structure -
02
portcreate
Script to create the template for a new port.
Usage: portcreate [-b builder]
Create a port template directory with sbuild file. Options: -b Specify build system (default: autotools) Available: autotools, meson, cmake, go, python, rust -h Show this help message Examples: portcreate myport # Creates autotools template portcreate -b meson myport # Creates meson template portcreate -b cmake myport # Creates cmake template portcreate -b go myport # Creates go template portcreate -b python myport # Creates python template portcreate -b rust myport # Creates rust template -
03
updateconf
Script to update pending configuration files (*.snew).
Usage: updateconf [-h|--help] Review the .snew files that starkpm leaves when an update would overwrite a configuration file listed in 'backup='. For each one the differences against the installed file are shown and you choose what to do: U Update replace the current file with the new .snew version (your local changes are lost) D Discard delete the .snew and keep the current file (the new defaults are lost) E Edit open the current file in $EDITOR to merge by hand, then show the diff again; if it ends up identical, the .snew is removed K Keep leave both files as they are; the .snew shows up again the next time you run updateconf A .snew identical to the current file, or whose current file does not exist, is removed without asking. A summary of what was done is printed at the end. Environment: EDITOR editor used by Edit, arguments allowed (default: vim) SNEW_DIRS directories searched for .snew files (now: /etc /boot /opt /usr /var) Examples: updateconf review every pending .snew file EDITOR=nano updateconf use nano for Edit SNEW_DIRS=/etc updateconf look only in /etc -
04
revdep
Reverse dependency script, worth running after upgrading or removing packages, to detect broken packages. Specify a package name if you only want to check that one.
Usage: revdep [option] [arg] Options: -a, --all show all affected files -r, --rebuild rebuild and reinstall the broken package -p, --package <pkg> check only a specific package -f, --no-filter skip the filter of excluded directories, files and libraries -e, --exclude <pkg1 pkg2 pkgN> exclude packages from rebuild (with -r/--rebuild) -y, --yes don't ask for confirmation on rebuild (with -r/--rebuild) -h, --help show this help -
05
hook
A hook is a shell script with the commands that must 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 moments. It can also be run manually:
Usage: stark hook <stage> <action> <port> Options: stark hook <pre|post> <install|remove> <port> Example: stark hook post install linux
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 somewhere else, prepend DESTDIR to the command: DESTDIR=/tmp/path ./INSTALL.sh