Skip to content

Latest commit

 

History

History
119 lines (87 loc) · 4.21 KB

CONTRIBUTING.md

File metadata and controls

119 lines (87 loc) · 4.21 KB
Raw

Introduction

The Regolith Desktop project is consumed by users via Linux packages. These packages are built via GitHub actions in this repository. It can be considered a general-purpose system for building and hosting packages for Debian-based systems.

Terms

  • distro - A global-level name referring to a Linux distribution (eg: debian, ubuntu)
  • codename - The name of a given release of a distro (eg: focal, bullseye)
  • arch - The system architecture of target machines (eg: amd64, arm64)
  • stage - May be one of unstable, testing, release. Modeled from Debian releases
  • repository - A collection of packages for a given distro + codename + arch + stage
  • manifest - A file containing lists of built package sets of: <package name> <source ref> <commit id>

Package Variants Supported

  • Debian

Package Builder

Overview

Package building starts from a root model which specifies the upstream package repositories and source locations. This package model specifies the following attributes per package:

"package-name": {
  "source": "https://...git",
  "ref": "..."
}

The builder traverses the package model and generates a manifest for each package. This manifest is used to determine what (if anything) has been updated upstream and needs to be built. The package manifest is a text file with one package per line. The line contains:

package-name git-repo-url branch commit-ref

The manifest is generated by simply retrieving the git ref of the upstream repo at the specified branch. After a manifest is generated, it is compared to the previously generated manifest. If there is no differences than the build is complete (NOP). In the case there are changes, the new manifest is committed along with the newly built packages.

For the case that changes are found, for each package that has changed is built and the results are committed to a target-specific repository.

Praxis

TBD

Customization

Package builds can be customized in a few ways. Customization is specified at the /stage/<stage>/<distro-name>/<codename>/<arch> levels. There are two forms of customization: module mutation and build host mutation. In the former, a JSON file may be specified that becomes merged with the general package model before manifest generation. This merging allows for:

  1. Additional packages to be specified for a given stage/distro/codename/arch
  2. Existing packages to specify an alternate source (git url, branch, commit ref)
  3. Remove a package from the general model. This is useful when a given distro already supplies a dependency natively.

For build host mutation, if the file setup.sh (example) is present in the directory it is executed on the docker build host before manifest merging begins.

Repo Layout
Path Description
/stage General package model per target
/docs Documentation
/.github/workflows The build system
Build Triggers

Package builds are launched via GitHub workflow triggers. The following events are supported:

  • Check manifest and build new packages upon:
    • Git repo push to main
    • Manually start build via Actions tab
    • Repository notification event. 1P packages specify GitHub workflows that signal voulage of a change. (example)

How To

Implement a Package Builder

Copy .github/scripts/ext-template.sh to another file, implement the functions in the shell script. When invoking main.sh, pass the new extension as the second parameter. See ext-debian.sh as an example.

Build and Publish Locally

The script local-build.sh will invoke the build and packaging functions as occurs in automation. This can be used to test packages build before committing to git or debug problems with packages or the build system. Example:

cd .github/scripts
./local-build.sh ../.. ext-debian.sh regolith-i3status-rust https://github.com/regolith-linux/regolith-i3status-rust.git debian_source focal