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:

```bash
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:

```bash
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:

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

To clear cached Debian package downloads:

```bash
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:

```bash
python3 tools/plasma-next list
```

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

```bash
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:

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

To build the entire suite in dependency order:

```bash
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:

```bash
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:

```bash
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:

```bash
python3 tools/plasma-next clean libdrm
```

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](MAINTAINING.md) for recipe changes and release configuration.