breadpack/README.md

breadpack

breadpunk.club's in-house package management system (prototype).

[TOC]

global options

breadpack
    [--file PATH]
    [--lockfile PATH]
    [--requestsfile PATH]
    SUBCOMMAND [OPTIONS …]

• --file sets a custom path for breadpack.json. Defaults to /bread/breadpack.json.
• --lockfile sets a custom path for breadpack-lock.json. Defaults to /bread/breadpack-lock.json.
• --requestsfile sets a custom path for breadpack-requests.rec. Defaults to /bread/breadpack-requests.rec.

for users

list installed packages

breadpack list [--json] [--upgradable]

This list is generated from the cached version data on breadpunk-lock.json. An admin will need to run breadpack check to update this list.

• --json enables JSON output, useful for scripting.
• --upgradable restricts the output to upgradable packages only.

request a package

breadpack request <package_name> [-c|--comment COMMENT]

• package_name: Name of the package or application that you want installed.
  This does not have to be a perfect APT package name; all package requests are human-reviewed.
• -c or --comment: Add an optional comment for the admins, for example to explain why you want a package installed or what it is.

for admins

lint the breadpack.json file

breadpack lint

build the lockfile

breadpack lock

Caution! This rebuilds the lockfile from scratch and is mainly inteded for first installation and/or fixing corrupted files. This may cause some updates to be skipped!

This command will fail if the lockfile already exists.

check for updates

breadpack check [--json] [--save|--no-save]

• --json enables JSON output, useful for scripting.
• --save and --no-save toggle whether to or not to save to breadpack-lock.json. --save is enabled by default.

file formats

breadpack.json

This file is managed by humans. It is recommended to commit it to a Git repo.

{
    "version": 0,
    "categories": {
        "irc": "Anything related to Internet Relay Chat"
    },
    "packages": [
        {
            "name": "weechat",
            "category": "irc",
            "type": "apt",
            "apt_name": "weechat"
        }
    ]
}

version

The breadpack.json version number to ensure compatibility in case of format updates later on. Should be set to 0 for now.

categories

A simple object mapping string keys to string values. The keys are category names and the values are category descriptions.

The keys can be used as the value for category in package.

packages

A list of packages to display publicly and monitor for updates.

• name: Package display name. Must be unique.
• category: Category name from categories. Optional.
• type: The package's type: one of apt or manual.
  Other types, such as pip, might be handled later.

Type-specific options are explained below.

apt package options

• apt_name: The APT package name. Optional, defaults to name.

manual package options

• version_file: Path to a VERSION file. Optional; when not set, breadpack will be unable to track the current installed version.
• latest_version_script: Path to an executable script returning the latest known package version. Optional; when both version_file and latest_version_script are not set, breadpack will be unable to check for updates.

breadpack-lock.json

This file is automatically generated by breadpack and is used to detect changes in the package versions made by any manual upgrades.

This file SHOULD NOT be manually edited. Should the file be corrupted or be re-generated from scratch, updates may not be properly detected.

{
    "version": 0,
    "packages": [
        {
            "name": "weechat",
            "last_checked": "2020-02-31T13:37:42",
            "current_version": "12.42",
            "latest_version": "13.3.7"
        }
    ]
}

breadpack-requests.rec

A recfile that should be made writable to all users:

-rw--w---- root bakers 4242 Feb 31 13:37 breadpack-requests.rec

The Python script will automatically amend requests in the following form:

Date: [ISO 8601 datetime]
User: $USER
Processed: no
Package: $package_name
# if no comment was specified, this will not appear
Comment: $comment

The model descriptor can be written as follows:

%rec: PackageRequest
%type: Date date
%type: Processed bool
%type: User line
%type: Package line
%mandatory: Package
%allowed: Date User Processed Package Comment
%sort: Processed Date
%doc: Package requests made via breadpack

setup

dependencies

For APT support, install python3-apt.