starkpm — starkOS

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

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

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.

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 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

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

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'

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 to unread from the source
portnews purge orphan          Remove local news 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 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. Run stark help to see all available functions.

Command	Description
sync <arg>	Updates the port 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 all dependencies 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 sbuild.
config	Shows starkpm's configuration.
dependent <port>	Shows reverse dependencies.
depends <port>	Shows dependencies.
dup	Shows duplicate ports.
files <port>	Shows 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 system triggers.
world [ports]	Shows, adds to, or removes from the world list.
help	Shows this help.

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 <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 to create the template for a new port.
03

updateconf

Script to update pending configuration files (*.snew).

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

portadd

portbuild

portdel

portrebuild

portbase

portsync

portnews

cbuild_restore <dest> [name]

cbuild_save <src> [name]

cbuild_options [name]

schroot

portcreate

updateconf

revdep

hook