# Pkglab documentation

### Jaap Boender

### April 23, 2009

## 1 Introduction

Pkglab is a tool for exploring open-source distributions, currently supporting Debian-style (Debian, Ubuntu) and RPM-based (Mandriva, Fedora) distributions, as well as pkgsrc summary files. This document is intended as a guide to its usage.

The basic mode of operation of Pkglab is to firstly create a universe by merging one or more waterways; a waterway consists of one or more distributions. Then, the different operations provided by Pkglab (see below) can be applied to this universe.

## 2 Command-line options

Pkglab has the following command-line options:

Option | Behaviour | Default value
-architecture | Set the default architecture | i386
-history file | Use file for command history | $HOME/.pkglab-history
-script file | Execute the script file |
-merge waterway | Merge waterway |

## 3 Example session

We start by merging the Debian Lenny distribution:

./pkglab.opt -merge deb:data/debian/history/2009214-debian-5.0-Packages
Completing conflicts... * 100.0%
pkglab version 1.4 by the MANCOOSI Project
>

The packages variable contains all the packages in the universe, currently 22 311:

> count(packages)
22311
>

Let’s see if there are any non-installable packages:

> check(packages,packages)
Conflicts and dependencies... * 100.0%
Solving * 100.0%
Conflicts and dependencies... * 100.0%
Solving * 100.0%
<diagnosis:closure size 22311, 0 failures>
>

There are no non-installable packages.

## 4 Objects and operators

Pkglab knows several different types of objects:

Strings
  (denoted: "…") The name of a file or a waterway.
Units
  (denoted: kde) A name; combined with a version and an architecture it forms a package.
Packages
  (denoted: kde’5:47@all) One specific version of a unit, for a specific architecture (or for all architectures).
Archives
  (denoted: %name) A mapping between dates and package sets; used to track the contents of a distribution through times
Dates
  (denoted: YYYY-MM-DD)
Date ranges
  (denoted: [YYYY-MM-DD;YYYY-MM-DD])
Specifications
  (denoted: [. kde (>= ’5.2) .]) A selector on the versions of a unit, in this case all versions of the unit kde greater than or equal to 5.2. The version is optional; [. kde .] is a valid specification as well. The spaces between the [. brackets and the specification are necessary!
Sets
  (denoted: {a, b, …})
Diagnoses
  The result of a check operation: a list of packages that are not installable with their reasons.
Functions
  (denoted: $x -> …$x …)
Booleans
  (denoted: true or false)

It is possible to use variables: like in Unix shells, variable names are prefixed by a dollar sign ($). Assignment is done as follows:

> $a <- select([. kde (>= ’5.2) .])

Pkglab has the following operators:

Operator | Function
| | Set union
& | Set intersection
`\` | Set difference
not and or | Boolean operators
= <> > < >= <= | Comparison (for versions, numbers and sets)
set `~ /` regexp / | Package selection by regular expression

There are inbuilt variables to show all packages, archives, source packages and units in the universe: they are called packages, archives, sources and units respectively.

## 5 Directives

#abundance set
  Test set for abundance; i.e. check if all packages have their dependencies satisfied.
#dump filename expression
  Dump the result of expression to the file filename.
#exit
  Quit Pkglab.
#help
  Show help (also: #help "functions" or #help "directives")
#merge waterway
  Merge waterway with the universe.
#show expression
  Like #dump, but show the expression on screen.
#type expression
  Show the type of expression.
#quit
  The same as #exit.

## 6 Functions

check(set1, set2)
  Check whether all packages in set1 are installable separately using only the packages in set2. Returns a diagnosis.
check_together(set1, set2)
  Check whether all packages in set1 are installable together using only the packages in set2. Returns a diagnosis.
closure(set)
  Give the transitive closure of the dependencies and pre-dependencies of set, ignoring dependencies that cannot be resolved. Returns a package set.
conflict_list(package)
  Gives the conflict specification of package. Returns a list of specifications.
conflicts(set)
  Gives the set of packages that have a conflict with a package in set. Returns a package set.
contents(archive, date)
  Gives the packages that are in archive on date. Returns a package set.
count(set)
  Returns the number of elements in set.
dep_closure(set)
  Like closure, but uses only the dependencies of set.
dep_path(set, pkg1, pkg2)
  Shows a dependency path (if available) between pkg1 and pkg2 using only packages from set. Returns either Nothing (if no dependency path can be found) or a list of packages.
depends(package)
  Gives the dependency specification of package. Returns a list of lists of version specifications; each list of version specifications represents a disjunction, so that the equivalent of the dependency "A and (B or C)" would be [ [ [. A .] ]; [ [. B .]; [. C .] ] ].
elements(set)
  Returns a list that contains the elements of set.
exists(set, function)
  function must return a boolean; exists(x,f) returns true if there is an element in x for which f returns true; false otherwise.
forall(set, function)
  Like exists, but forall(x,f) returns true if f returns true for all elements of x, and false otherwise.
filter(set, function)
  function must return a boolean; filter(x,f) returns the set of all elements in x for which f returns true.
install(set1,set2)
  If it is possible to install all packages in set1 together using only the packages in set2, returns a subset of set2 in which all dependencies of set1 are satisfied. Otherwise returns the empty set.
installed_size(package)
  The size after installation of package package. Returns an integer.
is_empty(set)
  Returns true if set is empty (has no elements). Returns false otherwise.
load_packages(filename)
  If the file filename contains a list of package names (in the form package’version@arch), then load_packages returns a package set containing these packages.
map(set,function
  Apply function to all elements of set. Returns a set of the same type as set.
member(element, set)
  Check whether element belongs to set. Returns a boolean.
pre_closure(set)
  . Like closure, but uses only the pre-dependencies of set. Returns a package set.
provides(package)
  Gives the units explicitly provided by package. Returns a list of version specifications.
range(archive)
  Gives the dates available in archive. Returns a list of date ranges (an archive need not be continuous).
select(specification)
  Gives the packages that satisfy specification. Returns a package set.
size(package)
  Like installed_size, but gives the size of the package itself (i.e. before installation)
source(package)
  Returns the source package from which package was created.
strong_dep(set, package1, package2)
  Checks whether package2 is a strong dependency of package1 in set; this is the case if (and only if) it is NOT possible to install package1 in set without also installing package2.
success(diagnosis)
  Returns true if diagnosis does not contain any failures, and false otherwise.
trim(set)
  Given a package set set, removes the non-installable packages from it (in the context of set).
unit(package)
  Returns the unit of package.
versions(unit)
  Returns a set of all packages that have unit as their unit. Returns a package set.
what_provides(unit)
  Gives all packages that provide unit. Returns a package set.

> This document was translated from LATEX by H E V E A.