Dorodango Manual 0.0.0

Table of Contents

Next:   [Contents][Index]


This manual is for dorodango, version 0.0.1.

Dorodango is a package manager written in and for R6RS Scheme.

From Wikipedia:

Dorodango is a Japanese art form in which earth and water are molded to create a delicate shiny sphere, resembling a marble or billiard ball.

Using dorodango, you can easily install and distribute collections of R6RS libraries as well as programs using these libraries. It can handle dependencies, so when a program requires several libraries, and each of those has further dependencies, dorodango allows you to install all the prerequisites for that program in one go.

Next: , Previous: , Up: Top   [Contents][Index]

1 Getting Started

Next: , Up: Getting Started   [Contents][Index]

1.1 Installation

Dorodango comes in a tarball, which includes all its dependencies and an installation script. The installation script will probe for a supported Scheme implementation (currently Ikarus and Ypsilon), and uses dorodango to install itself and all dependencies into a selectable destination (see Destinations for details).

It is recommended to install dorodango outside of the location(s) managed by it. There are several ways to achieve this:

  1. Install dorodango in /usr/local/, and use dorodango’s default configuration, which will install packages into ~/.local/.
  2. Install dorodango in some other place other than ~/.local/, and symlink the doro script to some directory in your PATH.
  3. Install dorodango into the default location, ~/.local/, and configure it to use some other location by default.

For option 1, installation works like this:

tar -xjf dorodango-full-0.0.1.tar.bz2
cd dorodango-0.0.1/dorodango
./setup --prefix /usr/local

The R6RS implementation is probed for automatically in the above example, but you can explicitly choose using the -i or --implementation option:

./setup --implementation ikarus --prefix /usr/local

Note that --implementation must go before other arguments.

After running setup like above, you should now have /usr/local/bin/doro, and as /usr/local/bin is ordinarily in PATH, running doro --help should display a help message.

Besides the doro script, the installation process also creates a helper program r6rs-script in the same directory (i.e. /usr/local/bin in the running example). This script is specific to the implementation chosen when installing dorodango, and is used for running Scheme programs installed by dorodango.

Option 2 works nearly the same, except that you use a different argument after --prefix, and afterwards make doro available in your PATH.

For option 3, you don’t need to specify --prefix, but you should configure a different default destination for dorodango to use. See Configuration File, for more information on configuring dorodango.

Previous: , Up: Getting Started   [Contents][Index]

1.2 Quickstart

For the unpatient, this section presents the minium you need to know to use dorodango for installing software.


So, you’ve successfully installed dorodango, and were able to get the help message via doro --help? Then it’s time to tell dorodango where it can find software (see Packages) to install. Create the file ~/.config/dorodango/config.scm and add this line:

(repository experimental "")

This tells dorodango the location of the author’s experimental repository, and gives it the name ‘experimental’. You could add further repositories with different names and locations, and dorodango will consider them all when installing packages.

Updating the package database

This is all configuration that is needed; if you now run doro update, you should see something like the following:

Loading available information for repository `experimental'

Now dorodango has obtained the information of available packages from the repository. You can verify that by running doro list --all, which should produce output resembling the following:

u conjure                    0-20091204
u dorodango                  0-20091204
u fidfw                      0-20091204

The rightmost columns indicates the package state (‘u’ means "uninstalled"), the other columns are the package name and version.

Installing software

You can now install any of the listed packages, using doro install package-name:

% doro install spells
The following NEW packages will be installed:
  spells srfi{a}
Do you want to continue? [Y/n] 
Installing srfi (0-20091204) ...
Installing spells (0-20091204) ...

As demonstrated in the above verbatim, dorodango knows that the package ‘spells’ depends on ‘srfi’, and will automatically install that package as well.

Other important commands

Now you you know how to achieve the primary task of dorodango: installing software. There are a few other things you probably want to do at times:

doro upgrade

Attempts to upgrade each package to the newest available version.

doro remove

Allows you to remove packages from your system.

Getting help

For each command, you can invoke doro command --help, and it will show you what options and argument that command requires:

% doro remove --help
Usage: doro remove PACKAGE...
  Remove packages.

  --no-depends  ignore dependencies
  --help        show this help and exit

Next: , Previous: , Up: Top   [Contents][Index]

2 Overview

Dorodango is used via the doro command-line program, which allows you to automatically download, install, remove and upgrade R6RS library collections and programs that might be included with them.

A library collection, possibly including programs and documentation, together with some metadata, which, for example, describes the dependencies on other software, is called a package. Packages are distributed in ZIP files referred to as “bundles”; each bundle may contain one or more packages.

If you already are familiar with other package managers, such as Debian’s APT, having more than one package bundled in the same file might seem unusual to you, but don’t worry: bundles are mostly transparent to the user. Most of the time, you will deal with packages, and bundles are of concern mostly when using dorodango to package your or other people’s software.

Next: , Up: Overview   [Contents][Index]

2.1 Anatomy of a Package

A package is the "unit of software" dorodango works with. It has a name, and a version, which may be used to form dependency relationships among packages. It also may have other attributes, like a description and a homepage URL. Besides the metadata, a package also contains files, which are grouped into categories. Each category of a package conceptionally contains a set of files, along with their desired installation locations. The categories currently handled by dorodango are:


R6RS libraries, and files required by them (either at runtime or at expand-time).


R6RS programs.


README files, HTML documentation, etc.

Next: , Previous: , Up: Overview   [Contents][Index]

2.2 Destinations

Now the files contained in these categories must be installed somewhere, and usually into different locations. The rules that describe where software is installed into are provided by a destination. You can select the destination by invoking the doro command line tool with the ‘--prefix’ option, see Global Options. For each destination, dorodango maintains a database of installed and available packages.

Currently, all destinations have the same rules which should be suitable for POSIXish platforms, and especially for FHS platforms:


Installed into PREFIX/share/r6rs-libs.


Installed into PREFIX/share/libr6rs-PACKAGE-NAME/programs, and a shell wrapper in PREFIX/bin is created which starts the Scheme program via r6rs-script, which is created automatically when dorodango initializes a destination.


Installed into PREFIX/share/doc/libr6rs-PACKAGE-NAME.

Previous: , Up: Overview   [Contents][Index]

2.3 Repositories

The bundles in which the packages are installed from are fetched from repositories. A repository is accessed via HTTP and is essentially a directory that contains bundles along with a file listing their locations and the packages within them.

Next: , Previous: , Up: Top   [Contents][Index]

3 Reference

doro is a command-line interface for downloading, installing and inspecting packages containing R6RS libraries and programs.

doro accepts, besides global options, a command and command-specific options. Each command is geared to a particuliar task, for example installing, removing or upgrading packages.

The following subsections document the available commands, grouped by related tasks.

Next: , Up: Reference   [Contents][Index]

3.1 Global Options


Do not read any configuration file. This option can be used to ensure that doro will just use built-in defaults.


Use configuration file file, instead of the default one. See Configuration File for configuration file syntax.


Use an FHS destination located below the directory prefix. This option has the same effect as adding an FHS destination to the configuration file and using it for this invocation of doro.


Run non-interactively. This assumes “yes” on most questions. Confirmation prompts for actions that are “risky” (in the sense that their effects may be potentially unexpected or unwanted) cause program termination with a non-zero exit code, after displaying an error message.


Like --non-interactive, but silently assume “yes” on all questions, even risky ones.

Next: , Previous: , Up: Reference   [Contents][Index]

3.2 Command Reference

Note that all commands take a --help option showing brief usage information, although that option is not explicitly listed below.

3.2.1 Querying

The following commands gather information; either from the package database, uninstalled bundles, or about the configuration.

Command: list

Produces a list of packages, along with their installation status and version on standard output.


Show all packages, including uninstalled, but available ones. By default only installed packages are listed.

-b bundle

Temporarily adds bundle’s contents to the package database.

Command: show package ...

Shows information about one or more packages. This command lists package, name, version and dependencies in RFC822-like style on standard output. Each package may be either:

-b bundle

Temporarily adds bundle’s contents to the package database.

Command: show-bundle bundle ...

Shows the contents of one or more bundles on standard output. The content listing consist of each package’s information, as shown by the the show command, plus the package’s the list of files in each category. See Packages.

Command: config

Shows the current configuration in YAML-like style.

3.2.2 Package managment

Command: update

Download information about available packages from all repositories of the selected destination.

Command: install package ...

Install the listed packages. Each package argument can be a package name, in which case the newest available version is installed. If the package in question is already installed, it will be upgraded. One may also explicitly specify a specific version to be installed using the syntax ‘package-name=version’.

-b bundle

Temporarily adds bundle’s contents to the package database.


Disable dependency resolution. This option allows for installing packages with unresolved dependencies.

Command: remove package ...

Remove the listed packages from the system.


Disable dependency resolution. This option allows for removing packages that still have others depending on them.

Command: upgrade

Upgrade all packages to the newest available version.

Command: init

This command can be used to explicitly initialize a destination for use with a particuliar Scheme implementation. The initialization is otherwise done implicitly upon first opening the database for that destination, and uses the default-implementation configuration clause (see default-implementation).

-i impl

Select the implementation to use for that destination.

3.2.3 Development

The following commands are of use if you want to create your own packages and repositories.

Command: create-bundle directory ...

Create a bundle from the directories given as arguments.

-o filename

Output the bundle to filename. When this option is not given, dorodango will try to name the bundle based on the package contained in it. Should the bundle contain multiple packages, this option is mandatory.

-d directory

Output directory for the created bundle file. This option only has an effect when --output is not provided.


Rewrite the versions of all packages in the created bundle by appending version. This is useful, for e.g. creating “snapshot” bundles from a VCS, where one could append the current date to the upstream version.

Command: scan-bundles directory ...

Search the directories passed as arguments for bundles and produce an “available file” containing information about found bundles on standard output.

-o filename

Create a symbolic link tree in target-directory, using the bundle at bundle-directory.


Allow the command to operate even when target-directory already exists.


Create a symbolic link for every file. Without this option, doro will create symbolic links to directories when this doesn’t change the created symlink tree.


Create symbolic links just for the packages listed in the comma- or space-seperated list packages.


Create symbolic links for all but the packages listed in the comma- or space-seperated list packages.

Previous: , Up: Reference   [Contents][Index]

3.3 Configuration File

The configuration file stores permanent settings for dorodango, and can be selected with the --config option, see Global Options. It’s syntax is S-expression-based clauses. In the following, we will dissect an example configuration file; note however, that for most users, a much simpler configuration will suffice (see Quickstart). Also the --prefix global option can be used to work with multiple destinations without explicitly setting them up in the configuration file. Anyway, without further ado, here’s a configuration that uses all possible clauses:

(repository experimental "")
(repository unstable "")
(destination unstable
  (fhs "/home/alice/scheme")
  (repositories unstable))
(destination experimental
  (fhs "/home/alice/scheme-experiments")
  (database "/home/alice/scheme-experiments/db"))
(default-destination experimental)
(default-implementation ypsilon)

3.3.1 Repositories

A repository clause defines a repository, which may be located on an HTTP server or a local file system. The repository is given a name, and a location is specified as an URI:

(repository <name> <location-uri>)

In the running example, <name> is experimental, and <location-uri> is the string "", denoting an HTTP repository at the apparent location.

3.3.2 Destinations

Destinations are where a package’s files are installed to; they have an associated package database that keeps track of installed packages. In principle, destinations come in “flavors”, but at the time of writing, there’s only a single flavor: fhs, which puts the files in subdirectories of the specified prefix directory that are (at least roughly) in line with the FHS, which specifies the directory layout of UNIX-like systems. This means one can use an fhs destination to install to /usr/local, and have files ending up in familiar locations.

In the configuration file, destinations are given a name so they can be referred to by doro’s --destination option. See Global Options.

Unless specified otherwise via the repositories sub-clause, all repositories listed up to the point of the destination’s declaration will be used with this destination. A repository must be declared before being referenced in a destination’s repositories clause.

The database sub-clause allows to define the location of the package database on disk; if it is left out, dorodango will use a default location, based on the destination’s prefix.

3.3.3 Defaults

The default-implementation clause specifies the Scheme implementation to use by default when setting up new destinations. The implementation associated with a destination will be used by R6RS programs installed into that destinationq. One can explicitly initialize a destination using the doro init command, thus overriding the default.

If default-implementation is not specified, dorodango will use a built-in default (ikarus at the time of writing).

Using the default-destination clause one can specify which configured destination will be used when none is explicitly specified via the --destination global option. If there is no default-implementation clause, the first destination specified is considered the default.

3.3.4 Formal Grammar

A complete BNF-style grammar for the configuration file:

<configuration> -> <clause>*
<clause> ->  <repository> | <destination>
   | <default-destination> | <default-implementation>

<repository> -> (repository <name> <uri>)

<destination> -> (destination <name> <destination-spec> <option>*)
<option> -> (database <directory>)
   | (repositories <name>*)
<destination-spec> -> (fhs <directory>)

<default-destination> -> (default-destination <name>)
<default-implementation> -> (default-implementation <implementation>)
<implementation> = ikarus | ypsilon

<directory> -> <string>
<name> -> <symbol>
<uri> -> <string>

Next: , Previous: , Up: Top   [Contents][Index]

4 Packaging Guide

“Packaging” refers to the act of supplying the metadata dorodango needs in order to deal with a set of libraries and/or programs. You should make yourself familiar with dorodango’s overall concepts (see Overview) as prerequiste to this chapter.

Next: , Up: Packaging Guide   [Contents][Index]

4.1 A simple Example

Let’s say you want to package a program named ‘example’, which contains a few libraries and a program. These files are present in its source tree:


A short note explaining usage of the software.


Contains the library (example foo).


Contains the library (example bar).


A program that use the above libraries.

For packaging this software, we add a file pkg-list.scm in the top-level directory, which will contain the metadata in S-expression syntax, a bit like the R6RS library form. The following metadata can be supplied:

Of these, only the name and version are mandatory, the rest are optional.

Hence a minimal package form listing package name looks like this:

(package (example (0))
  (depends (srfi)))

This already specifies the ‘srfi’ package as the only dependency; further dependencies may of course be listed.

Inspecting our work with using doro’s show-bundle command, passing it the top-level directory where the pkg-list.scm file resides in:

% doro show-bundle example
Package: example
Version: 0
Depends: (srfi)
Category: documentation

The package is nearly empty, besides the README file, which was added to the ‘documentation’ category automatically. We need rules dealing with the libraries and the program, which are missing:

(package (example (0))
  (depends (srfi))
    (sls -> "example"))
    (("programs" "hello.sps") -> "hello")))

The rule inside the library form says “put all files with an ‘sls’ extension below the example directory”, while the programs rule tells dorodango to place the file programs/hello into the top-level directory of the ‘programs’ category as file hello.

Now we have everything in its proper place, and we are done with packaging this small example:

% doro show-bundle example
Package: example
Version: 0
Depends: (srfi)
Category: libraries
Category: programs
Category: documentation

For good measure, we should also add the synopsis, description and homepage properties to the package:

(package (example (0))
  (depends (srfi))
  (synopsis "'Hello World' example")
  (description "This package contains a program that displays"
               "a familiar greeting.")
  (homepage "")
    (sls -> "example"))
    (("programs" "hello.sps") -> "hello")))

Previous: , Up: Packaging Guide   [Contents][Index]

4.2 The Metadata File

A metadata file must be named pkg-list.scm and must be either in the top-level directory or an immediate sub-directory of a bundle to be considered by dorodango. It contains one or more package forms, thus declaring which packages are inside the bundle.

The package form declares the name and version of the package, and lists its properties, some of which are defined and used by dorodango, but there also may be additional properties used by other software or humans.

This leads to the following BNF-style grammar for the file’s contents:

<pkg-list> -> <pkg-form>+
<pkg-form> -> (package (<name> <version>) <property>*)
<property> -> <synopsis> | <description> | <homepage> 
   | <depends> | <category> | <hook> | <user-defined>
<synopsis> -> (synopsis <string>)
<description> -> (description <string>*)
<homepage> -> (homepage <string>)
<depends> -> (depends <pkg-reference>*)
<category> -> (<category-name> <file-rule>*)
<category-name> -> libraries | programs | documentation | man
<hook> -> (installation-hook (<hook-option>*) <hook-body>)
<user-defined> -> (<property-name> <property-value>)

As should be recognizable from the above grammar, properties are identified by a keyword, and have specific contents depending on that keyword. Currently, the following keywords are defined and used by dorodango:


A short single line describing the package briefly.


A longer, possibly multi-line description of the package.


This should carry an URL on which information about the software contained in the package can be found.


Declares the package’s dependencies.


These are used for categorizing files contained in the package, so they can be installed into the approriate place in the filesystem, depending on the destination.


A package may specify actions to be executed during installation using this property.

4.2.1 Package Versions

Each package has a version that can be ordered, so that a “newer” relation can be established. A version has two representations, one as a text string (for use in file names and for human consumption in general) and another one as S-expression, allowing easy embedding into and manipulation in Scheme.

The S-expression representation is a sequence of lists of integers, for example ‘(1 2) (3)’, which is textually rendered as ‘1.2-3’ – each list of integers is concatenated using a dot as separator, and those groups are then concatenated with a dash separating them.

4.2.2 The package description

The properties synopsis and description are used convey the purpose of the package to the user.

The value of the synposis property should be single string shortly describing the package, such that it could be used in a sentence starting with “package is a(n) …”.

The description property contains a longer description of the package, specified via a sequence of strings. These sequence is handled like like this:

4.2.3 Dependencies

A package can declare its dependencies on other packages via the depends clause of the package form. A dependency names the package depended upon and, optionally, constrains the version of that package. In the following example, ‘foo’ depends on ‘bar’ and ‘baz’; the dependency on ‘bar’ is unconstrained, allowing for any version of ‘bar’ to fulfill the dependency, while only a version of ‘baz’ higher than 1.2-3 will satisfy the second dependency.

(package (foo (1 1))
  (depends (bar) 
           (foo (>= (1 2) (3)))))

This is the BNF grammar for the package references used in the depends clause:

<pkg-reference> -> (<pkg-name>) | (<pkg-name> <version-constraint>)
<version-constraint> -> <version> | (<comparator> <version>)
   | (not <version-constraint>) 
   | (or <version-contraint>*)
   | (and <version-constraint>*)
<comparator> -> <= | >= | < | >
<version> -> <part>+
<part> -> (<integer>+)

4.2.4 Categories

A package’s files are grouped into categories to allow installation into appropriate places in the filesystem. Each category contains a (possibly empty) subset of the files contained in or below the directory the metadata file resides in.

A file can belong into at most one category. It can be mapped to any location (relative filename) inside that category, regardless of its physical location relative to the metadata file. To specify this mapping, a set of rules may be specified for each category known to dorodango, using the following grammar (see the IrRegular expression documentation for the SRE syntax supported by dorodango):

<file-rule> -> <source> | <source> -> <destination>
   | (exclude <source>*)
<source> -> <string> | <path-with-tail>
<path-with-tail> -> (<string>* <tail>) | <tail>
<tail> -> * | sls | (: <sre>*)

For instance, the following rules are used for the libraries category in the packaging of the SRFI collection:

(libraries ((: "%3a" (* any)) -> "srfi")
           ("private" -> ("srfi" "private")))

In plain English, this means “put any files and directories starting with “%3a” below the srfi directory, and put the file (or, in this case, directory) private in srfi/private.

4.2.5 Hooks

Hooks are a mechanism to perform actions during package installation. To that end, the package maintainer writes Scheme code resembling an R6RS program. The code must satisfy certain properties, namely that the last expression of the “program” must evaluate to a single-argument procedure that is invoked when the package is installed. The details of that procedure will be discussed below, but first the grammar for the hook options and body:

<hook-option> -> (needs-source? . <boolean>)
<hook-body> -> (import <library-reference>+) <definitions> <expressions>

Hooks are not evaluated and executed by dorodango itself, since dorodango may be installed in a different destination than that which the package in question should be installed into. Evaluating hooks in dorodango’s own context would hence pose the problem that the hook could rely neither on libraries provided by its package nor its dependencies. For this reason, dorodango spawns a small helper program using the r6rs-script of the destination it is installing to. With this way of proceeding, the following objectives are achieved:

However, due to the way the communication of dorodango with helper program running the hook is implemented currently, a hook must not use the standard output or input ports, as these are used for communication (the standard error port can be used, however). This restriction will be hopefully lifted in a later version of dorodango. Hook options

The only supported option supported currently is needs-source?, which specifies whether the hook requires the unpackaged source of the package for its operation. The needs-source? option defaults to #f. The hook agent

As mentioned before, the single-argument procedure that is the result of the last expression of the hook body is executed by the package manager. Its single argument is an “hook agent” procedure, which can be invoked to trigger actions of the package manager on behalf of the hook. The first argument to this procedure is the name of the desired action, further arguments depend on the action specified. Currently, the following actions are available:

Action: install-file category dest-filename src-filename

Install file src-filename, which is a string referring to an existing file.

Action: package-name

Returns the name of the package being installed.

Action: unpacked-source

Returns the path of the contents of the extracted package as a string, or #f, if the needs-source? option was not specified or #f.

Previous: , Up: Top   [Contents][Index]


Jump to:   B   C   D   F   I   P   R  
Index Entry  Section

bundles: Overview

category: Packages
configuration file, grammar: Configuration File
configuring destinations: Configuration File

destinations: Destinations
destinations, configuring: Configuration File

file, category: Packages

installation locations: Destinations

packages: Overview
packages, anatomy: Packages

repositories: Repositories

Jump to:   B   C   D   F   I   P   R