Ben’s reference manual

Mehdi Dogguy and Stéphane Glondu
version 0.6, May 30, 2012

This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL-2 in the Debian GNU/Linux distribution or on the World Wide Web at the GNU web site. You can also obtain it by writing to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Introduction

Ben is the name of a set of utilities written in OCaml and available through the ben command. The major feature of Ben is to provide a full featured transition tracker to follow the evolution of a set of packages in the Debian archive.

The aim of this document is to describe the features of Ben and its configuration.

2. Getting the source code

Ben is maintained in a Git repository available online at http://anonscm.debian.org/gitweb/?p=collab-maint/ben.git. Getting the sources is as simple as:

git clone git://anonscm.debian.org/collab-maint/ben.git

The source tree has a debian/ directory. It is a native Debian package, so you can use the standard building tools in order to build it.

3. Query language

The main feature of Ben is a transition tracker. The transition tracker selects a set of affected packages and computes a state for each of them. There exist already various ways to do that. One solution would be to use the dctrl-tools. We chose to make our own language. This allows us to perform more fine-grained queries, optimize queries and extend the query language easily.

A ben query is decribed by the following BNF formulae:

<query> ::= "true"
          | "false"
          | "!" <query>            /* Boolean negation     */
          | <query> "|" <query>    /* Boolean OR operator  */
          | <query> "&" <query>    /* Boolean AND operator */
          | "(" <query> ")"
/*set 2*/ | <field> "~" "/" <regex> "/"
          | <field> "~" '"' <string> '"'
          | "source"
          | <comparison> '"' <string> '"'

<field> ::= '.' <string>

<comparison> ::= '<<' | '<' | '>' | '>>' | '=' | '<=' | '>='

The first rules are the usual boolean constants and operators. The sixth rule is useful to group queries and override boolean operators' priotity.

The second set are the various type of queries implemented to match against different criteria. It matches against a package field (in lowercase).

We believe the syntax of queries is easy to grasp. Nonetheless, here are some exemples:

• .build-depends ~ /lib.*ocaml-dev/
  This query matches all packages that build-depend on a package whose name matches the Perl regular expression lib.*ocaml-dev.

• .depends ~ "libapt-pkg4.12"
  This one is simpler than the first one in the sense that libapt-pkg4.12 is considered as a plain string and not a regular experssion.

• >= "3.0"
  The query >= "3.0" matches all packages with a version number equal to or higher than "3.0".

• source
  This matches all source packages.

Now that the concept of query is explained, we will focus on other parts of Ben. We will see how we can use the queries for each frontend.

4. Frontends

Ben is a set of utilities available through the ben command. Each utility is called a frontend and there are four:

• download

• query

• monitor

• tracker

All frontends share a set of options and each one defines its own specific set. The shared set of command-line options is:

The rest of this section describes each frontend.

4.1. download

This frontend is the simplest one as it has no command-line options, except the shared ones. It downloads all Sources.bz2 files and all Packages.bz2 files for selected architectures and areas. You may invoke it by running:

$ ben download [options]

The requested files will be downloaded in $BEN_CACHE_DIR, if set, or in the current directory.

4.2. query

This utility is pretty much like grep-dctrl(1). Given a list of Packages or Sources files, it performs a query and outputs the result.

Using it is as simple as shown below:

$ ben query ".package ~ /gentoo/" Packages

Unlike grep-dctrl(1), ben query doesn’t have the necessary machinery to filter its output yet.

4.3. monitor

The monitor fontend builds a monitoring page for a transition. A transition is decribed by three queries:

• is_affected: matches source packages that are part of this transition; this query is evaluated against all source and binary packages and, for binary packages, their source package is picked;

• is_good: matches binary packages that are considered to be ready (fixed) for this transition;

• is_bad: matches binary packages that are considered to be broken (not fixed) for this transition.

Not that some packages can be neither good nor bad. For example, there are many packages that build-depend on some library but do not link against it. Thus, they do not need any dependency on the library at runtime.

An example of a complete description of a transition is:

is_affected = .build-depends ~ /libicu-dev/;
is_good = .depends ~ /libicu44/;
is_bad = .depends ~ /libicu42/;

There are other optional fields:

• title
  This puts a nice title in the HTML page.

• notes
  This can be used to put remarks about the transition or notes about the status of some packages or the whole transition.
  
  Ben recognizes some special texts and turns them into links. The following formats are recognized:

monitor understands the following list of command-line options:

4.4. tracker

This frontend uses monitor to generate a summary page about all known transitions. An example of such summary can be found at http://release.debian.org/transitions/.

tracker has a notion of profiles that gives a hint on the actual state of the transition. The default profiles are:

• planned for known planned transitions or requested but not processed or acknowledged yet;

• permanent is a special profile made to keep an eye on some set of packages, not necessarily a transition;

• ongoing for the actual list of (known) on-going transitions;

• finished has a list of some transitions that are almost finished (e.g. new binary packages migrated but old binary packages left in testing to not decrease installability, or a finished transition with a number of still broken packages in testing).

Technically, each profile is a sub-directory of the global config directory
[http://release.debian.org/transitions/config/]
. The latter can be specified by a command-line option.

By default, tracker looks for a directory named config which should contain a file named global.conf, unless otherwise told. It reads data (.ben files) from the config directory and outputs the result in the base directory.

tracker has the following command-line options:

5. Reporting issues

Ben doesn’t have a bug tracker yet. If you experience a bug or if you’re looking for some help, feel free to contact us directly.

Version 0.6
Last updated 2012-07-06 22:27:32 UTC