plasma-next/docs/BUILD.md

Building Plasma Next

Run commands from the repository root. Generated files are stored under build/ and are excluded from Git.

Set up the build environment

The Linux host needs Python 3.12 or later, debootstrap, the Debian archive keyring, sudo and util-linux namespace utilities. Network access is required to download sources and install build dependencies.

Create the controller and clean base image before the first build:

python3 tools/plasma-next setup

Use the same command to update tools in an existing controller.

Setup requests sudo access, authenticates the configured Debian snapshot and creates the following environment:

Component	Location	Use
Debian controller	build/controller/	Persistent environment containing sbuild and repository tools
Clean base image	build/chroots/trixie-amd64.tar	Starting point for each package build
Package build root	build/tmp/	Separate environment created for each sbuild run

Repeating setup reuses the base image. Each package gets a fresh build root with its declared Build-Depends installed through APT. Compilation runs with networking disabled.

APT download cache

APT caching is enabled by default. Setup installs apt-cacher-ng inside the controller. Each cached build starts a temporary cache process on a loopback port and stops it when the command exits. Downloaded Debian packages are retained in build/apt-cache/ for subsequent builds.

The build root connects to the cache over loopback HTTP. The cache fetches the original HTTPS repositories using TLS certificate verification. APT still verifies repository signatures and package hashes. The local file repository is used directly.

Package cleanup and environment reset preserve the APT cache. Cache activity and startup logs are stored in build/records/apt-cache/.

To disable caching for the environment and skip installing apt-cacher-ng during setup:

python3 tools/plasma-next setup --no-apt-cache

Subsequent builds download dependencies directly. Running setup again without this option enables caching. Disabling caching preserves existing cached downloads and leaves any previously installed apt-cacher-ng package in place.

To bypass an enabled cache for a single build:

python3 tools/plasma-next build libdrm --no-apt-cache

To clear cached Debian package downloads:

python3 tools/plasma-next clean-apt-cache

Clearing the cache preserves source archives, logs and build artifacts. The next cached build creates it again.

Select and build packages

List the available projects and their versions:

python3 tools/plasma-next list

To build a single project, supply its catalog name. Libdrm is a small example with no private build prerequisites:

python3 tools/plasma-next build libdrm

For a project whose private prerequisites have not been built, include --with-deps. This example builds Konsole and its required Plasma Next projects:

python3 tools/plasma-next build konsole --with-deps

To build the entire suite in dependency order:

python3 tools/plasma-next build --all

Multiple project names can also be supplied in one command.

To set the parallel job count for a build and its selected prerequisites:

python3 tools/plasma-next build konsole --with-deps --jobs 6

-j 6 is equivalent to --jobs 6. The value must be a positive integer. When omitted, the utility uses jobs from config/release.json.

--with-deps includes additional Plasma Next projects, ordered by the recipes' private Build-Depends. Without it, required private packages must already be available in the local build repository. Debian build dependencies are always installed by sbuild, regardless of this option.

Building automatically downloads and prepares sources, creates the Debian source package with dpkg-source, invokes sbuild and imports successful results into the local repository. The job count comes from --jobs or the default in config/release.json. Recipes use Debian's DEB_BUILD_OPTIONS=parallel=N setting, including when built directly with Debian tools. Without that setting, their explicit build commands use one job. Each recipe also defines its upstream test settings.

Before accepting a build, the utility checks Lintian results, artifact hashes, file ownership within the source package, installation paths, runtime header placement and dependencies on Debian Qt libraries. Repository integrity is checked after import. SignOn OAuth2 has an explicit filename-length warning allowlist.

Completed builds are reused when recorded inputs and artifact hashes match. Changing only the requested job count does not rebuild an accepted package. A failed build can be retried with the same command. Changing an accepted build's inputs requires a new Debian revision or explicit removal of its accepted state. Published package changes require a new revision.

Prepare sources separately

Use these commands when sources are needed before compilation or for building with Debian tools outside the controller.

To assemble a project's complete source tree without compiling it:

python3 tools/plasma-next prepare konsole

Other source preparation options:

Command	Use
fetch konsole	Download and verify archives without extracting them
prepare konsole --offline	Assemble the source tree using cached archives only
prepare --all	Prepare every project in the catalog

Prefix these commands with python3 tools/plasma-next.

Preparation downloads missing inputs unless --offline is set. Archives are checked against the locked sizes and SHA-256 hashes, including on cache reuse. Cargo vendor trees are assembled from pinned upstream crate archives. Rust bootstrap files come from official upstream archives. Native integration sources come from tracked files.

Prepared trees contain the complete debian/ recipe, helpers, patches and required payloads. Original archives are placed alongside them for dpkg-source. They can be built independently with dpkg-buildpackage or sbuild in an environment providing their Build-Depends.

--offline controls source downloads only. It does not make sbuild's APT dependency installation offline. fetch, prepare and build also accept --with-deps.

Find results and diagnose failures

Path	Contents
build/results/	Binary and source packages, build metadata and sbuild .build logs
build/records/build-logs/<project>.log	Source creation, build and repository operation log
build/repository/	Local APT repository supplying private build dependencies
build/sources/	Prepared source trees and generated source archives
build/cache/	Verified downloaded source archives
build/apt-cache/	Cached Debian package downloads
build/records/apt-cache/	apt-cacher-ng request, error and startup logs
build/prepared/	Source preparation records
build/input/modules/	Per-project build plans
build/state/	Accepted build identities and artifact hashes

When a build fails, inspect its project log and corresponding .build log. Failed builds do not receive an accepted build record. Retry after correcting the cause. Cleanup is optional unless generated files need to be discarded.

Clean package files or reset the environment

To discard a project's prepared sources and failed results before retrying:

python3 tools/plasma-next clean libdrm

To also discard its accepted build and local repository entries, allowing a fresh build at the same version:

python3 tools/plasma-next clean libdrm --accepted

Replace the project name with --all to clean every project with removable files. Add --accepted when accepted builds should also be removed.

Operation	Removes	Keeps
clean	Prepared sources, preparation records, generated source archives and unaccepted results	Downloads, original archives, logs, accepted results, accepted records and repository entries
clean --accepted	The above plus accepted results, build records, build plans and local repository entries	Downloads, cached original archives, logs and exported repository copies
reset-environment	Controller, base image, temporary roots, staged tools and configuration, and base image verification record	Source downloads, APT cache, prepared sources, results, build plans, build records, logs and local repository

clean --all skips projects with nothing removable. Related downloads and logs alone do not select a project. --with-deps also selects private build prerequisites. Downstream consumers are kept unless explicitly selected.

Use --accepted to allow a fresh build at the same version. Repository removal requires the controller and sudo. Run setup first if the controller was removed.

To recreate the controller and base image while keeping package results:

python3 tools/plasma-next reset-environment
python3 tools/plasma-next setup

For a fresh environment with no accepted package builds, clean the packages first while the controller is still available, then reset and recreate the environment:

python3 tools/plasma-next clean --all --accepted
python3 tools/plasma-next reset-environment
python3 tools/plasma-next setup

Reset clears staged files from build/input/ while preserving build/input/modules/, which holds package build plans.

Cleanup and reset acquire the operation lock. Reset refuses to remove directories containing active mounts.

Export an APT repository

Audit and export run on the host and require dpkg-deb and readelf. Signed exports also require gpg and gpgv on the host.

Export requires accepted builds for every project in the release catalog. It verifies that results match the current recipes and locked inputs, checks artifact hashes and audits runtime library placement before copying the repository.

To inspect the repository layout without signing it, create an unsigned preview:

python3 tools/plasma-next export --output build/delivery-preview

For publication, create a signed export using the GnuPG home containing the release key. Replace the path and fingerprint with the signing key's values:

python3 tools/plasma-next export --output build/delivery-signed \
  --signing-home /path/to/private/gnupg --key FULL_FINGERPRINT

Each export requires a new output directory. Signing requires both options. Use the full primary key fingerprint configured in config/release.json for --key. GnuPG may sign with a signing subkey belonging to that primary key. The utility exports the public key, signs InRelease and Release.gpg, and verifies both signatures. Private keys remain in the supplied GnuPG home.

Repository setting	Value
Suite	stable
Codename and client distribution	trixie
Component	main
Contents	Binary packages, source packages and APT indexes
Client instructions	docs/INSTALL.txt, copied as README.txt

Export creates a local directory. Upload it separately to publish the repository. See MAINTAINING.md for recipe changes and release configuration.