User’s Manual

The user’s manual covers using a mini-buildd installation – i.e., everything you can do with it given someone else had already set it up for you as a service.

Introduction

The core functionalities of mini-buildd are, 1st the arch-multiplexed clean building, and 2nd providing a repository. You don’t need to worry about 1st, mini-buildd just does it for you.

The 2nd however, the repository, goes public and hits “global Debian namespace”; so, as a big picture, it’s important first to understand how mini-buildd’s (default) setup tries to deal with this.

First of all, each instance has it’s own identity string, which will be used in the name of the keyring package, and will also appear in the apt repository in the Origin field.

Second, each instance instance may have N repositories, which each have their own identity string, determining the actual distribution names (CODENAME-ID-SUITE) to be used for uploads or in apt lines.

Both identities should be “globally unique” to avoid any confusion or conflicts with other existing repositories.

Note

Exceptions are the generic Sandbox and Developer repositories, with the de-facto standard names test and debdev; these should never be used publicly or for anything but testing.

Third, when people are mixing repositories together, we want to avoid package clashes, like same PACKAGE-VERSION from two different repositories. Also, we want guaranteed upgradeability between two different base distributions, and from experimental to non-experimental suites. Hence, at least in the Default Layout, we also have a version restriction, which resembles that of Debian Backports:

Default Layout

The Default Layout’s Suites and Semantics Overview

Suite

Flags

Version restriction

Example(test/jessie)

Repository

Semantic

Consumer

experimental

U E 6R

~<R><C>+0

~test80+0

No auto

Use at will

Developer.

snapshot

U E 12R

~<R><C>+0

~test80+0

No auto, but upgrades

Continuous integration

Developer, beta tester.

unstable

U M 9R

~<R><C>+[1-9]

~test80+3

No auto, but upgrades

Proposed for live

Developer, beta tester.

testing

M 3R

~<R><C>+[1-9]

~test80+2

No auto, but upgrades

QA testing

Quality Assurance.

hotfix

U M 4R

~<R><C>+[1-9]

~test80+2+hotfix1

No auto, but upgrades

Hotfix proposed for live

Quality Assurance.

stable

6R

~<R><C>+[1-9]

~test80+1

No auto, but upgrades

Live

End customer.

U: Uploadable M: Migrates E: Experimental NR: keeps N Rollback versions <R>: Repository Identity <C>: Codename version.

Note

The hotfix suite fills the kludge in a situation when a new version is in unstable/testing (but no yet ready for stable), but you need but to do important bug fixes to what is in stable immediately (it does migrate to stable directly).

User Setup

As a minimal setup, you should have a web browser installed; you can instantly browse mini-buildd, and use all functionality that do not require extra permissions.

To be able use advanced functionality (for example, create package subscriptions, access restricted API calls, or upload your GnuPG public key), create a user account:

  1. Register a user account.

  2. Setup your profile (package subscriptions, GnuPG key upload).

To access mini-buildd from the command line via mini-buildd-api, install mini-buildd-utils:

# apt-get install python-mini-buildd

To upload packages, install dput and add mini-buildd’s dput config to your ~/.dput.cf:

# apt-get install dput
? mini-buildd-api get_dput_conf ENDPOINT >>~/.dput.cf

Note

After ~/.dput.cf has been set up this way, you can use [USER@]ID-like shortcuts instead of HOST, and these will also appear in the bash auto-completion of mini-buildd-api.

Using the repository

Sources Lists

On the web interface, look for “Overview” in the “Repositories” section. Youd should be able to find all available APT source lines are available there for cut-and-paste fun.

You can get also get APT source lines in an automated fashion via

  • API call get_sources_list.

  • the <id>-archive-keyring package (allows for symlinks from /etc/apt/sources.list.d/).

Upload a package

Upload Options

New in version 1.0.26.

An Upload Option is some value induced to mini-buildd via special entries in the changelog of an upload. Thus, an upload may overwrite some defaults, or request special handling.

For example, consider an upload with this debian/changelog:

mini-buildd (1.0.25~test80+1) jessie-test-unstable; urgency=medium

  * Adds this.
  * Adds that.
  * Fixes something else.
  * MINI_BUILDD_OPTION: lintian-mode=ignore
  * MINI_BUILDD_OPTION: lintian-mode[armel]=disabled
  * MINI_BUILDD_OPTION: auto-ports=buster-test-unstable

This would

  • ignore lintian errors for this upload,

  • not run lintian at all for builds on arch armel

  • and finally (after successful install) do an automated port to buster.

Changelog entries denoting such an upload option need to be of the form:

* MINI_BUILDD_OPTION: <key>[[<alt>]]=<value>

<alt> may be used to make the value more specific – i.e., the only use case currently is to make the value arch-specific.

These options generally override resp. values (if any) in mini-buildd’s configurations (for this one package build).

These Upload Options are known:

Key

Alt

Value

Description

lintian-mode

[arch]

Str

disabled (don’t run this check), ignore (run but ignore results), errfail (run and fail on errors), warnfail (run and fail on warnings).

piuparts-mode

[arch]

Str

See lintian-mode.

autopkgtest-mode

[arch]

Str

See lintian-mode.

internal-apt-priority

Int

APT priorities for internal repos on build.

auto-ports

CSV

List of distributions (comma-separated) to automatically run ports for after successful install.

deb-build-options

[arch]

Str

Set DEB_BUILD_OPTIONS for build (see man dpkg-buildpackage).

deb-build-profiles

[arch]

Str

Set DEB_BUILD_PROFILES for build (see man dpkg-buildpackage).

Deprecated since version 1.99.16: * ignore-lintian=True: Use lintian-mode. * run-lintian=False: Use lintian-mode.

Deprecated since version 1.0.26: * BACKPORT_MODE: Use {lintian|piuparts|autopkgtest}-mode. * AUTO_BACKPORTS: Use auto-ports.

FAQ

Todo

BUG: reprepro fails with debian/ as symlink in Debian native packages

Please follow 4 for this subject.

In such a case, builds will be fine, but reprepro will not be able to install the package; you will only be able to see reprepro’s error “No section and no priority for” in the daemon.log.

For the moment, just avoid such a setup (which is imho not desireable anyway). However, as it’s a legal setup afaik it should work after all.

Using the API

The API consists of several commands with optional arguments (authentity and authority protected via django’s user management).

On the web interface, you can see a list of all commands via the API menu.

There are several ways to access the API:

Via the Web Interface

API calls are integrated in the web interface at appropriate places. Credentials are handled by whatever your browser uses.

Chances are that this is all you need, and no extra packages need to be installed on your system.

Via Shell: mini-buildd-api

Note

Install mini-buildd-utils.

Credentials are handled via python3-keyring, which should just work. i.e., choose the right backend for you – if not, you might need to configure the desired backend manually 5.

See https://github.com/jaraco/keyring.

Via Python: mini_buildd.client

Note

Install python3-mini-buildd.

For example, one can have configuration-like little python helper scripts, like for bulk migrating a package.

#!/usr/bin/python3
# pylint: disable=invalid-name  # https://github.com/PyCQA/pylint/issues/516

from mini_buildd.client import Client

CLIENT = Client("http://localhost:8066")

status = CLIENT.api("status")
print(f"Status:\n{status}")
print(f"Repositories:\n{status['repositories']}")

migration = CLIENT.api("migrate", args={"package": "mbd-test-cpp", "distribution": "buster-test-unstable"})
print(f"Migration:\n{migration}")

events = CLIENT.event(types=["MIGRATED"], package="mbd-test-cpp")
print(f"Found events:\n{events}")

You might find some more information in the client doc here, or directly in the source code.

Automatic ports

Internal ports

External ports

Repository maintenance

Todo

IDEA: Dependency check on package migration.

Todo

IDEA: Custom hooks (prebuild.d source.changes, preinstall.d/arch.changes, postinstall.d/arch.changes).

FAQ

Todo

FAQ: aptitude GUI does not show distribution or origin of packages

To show the distribution of packages, just add %t to the package display format 1. For example, I do prefer this setting for the Package-Display-Format:

aptitude::UI::Package-Display-Format "%c%a%M%S %p %t %i %Z %v# %V#";

The origin cannot be shown in the package display format 2. However, you may change the grouping to categorize with “origin”. For example, I do prefer this setting for the Default-Grouping:

aptitude::UI::Default-Grouping "task,status,pattern(~S~i~O, ?true ||),pattern(~S~i~A, ?true ||),section(subdirs,passthrough),section(topdir)";

This will group installed packages into an Origin->Archive hierarchy.

Additionally to aptitude’s default “Obsolete and locally installed” top level category (which only shows packages not in any apt archive), this grouping also more conveniently shows installed package _versions_ which are not currently in any repository (check “Installed Packages/now”).

Todo

BUG: apt secure problems after initial (unauthorized) install of the archive-key package

  • aptitude always shows <NULL> archive

You can verify this problem via:

# aptitude -v show YOURID-archive-keyring | grep ^Archive
Archive: <NULL>, now
  • BADSIG when verifying the archive keyring package’s signature

Both might be variants of 3 (known to occur for <= squeeze). For both, check if this:

# rm -rf /var/lib/apt/lists/*
# apt-get update

fixes it.

Todo

FAQ: Multiple versions of packages in one distribution

This is not really a problem, but a uncommon situation that may lead to confusion.

Generally, reprepro does allow exactly only one version of a package in a distribution; the only exception is when installed in different components (e.g., main vs. non-free).

This usually happens when the ‘Section’ changes in the corresponding ‘debian/control’ file of the source package, or if packages were installed manually using “-C” with reprepro.

Check with the “show” command if this is the case, i.e., s.th. like:

$ mini-buildd-api show ENDPOINT my-package

you may see multiple entries for one distribution with different components.

mini-buildd handles this gracefully; the remove, migrate and port API calls all include an optional ‘version’ parameter to be able to select a specific version.

In the automated rollback handling, all versions of a source package are shifted.