Next: Getting Started [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.
| • Getting Started | Installation and a quick introduction | |
| • Overview | Dorodango summed up | |
| • Reference | The command-line interface | |
| • Packaging Guide | How to create packages | |
| • Index | Concept index |
| • Installation | Installing dorodango | |
| • Quickstart | A quick introduction |
Next: Quickstart, Up: Getting Started [Contents][Index]
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:
doro script to some directory in your
PATH.
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: Installation, Up: Getting Started [Contents][Index]
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 "http://rotty.yi.org/doro/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.
This is all configuration that is needed; if you now run doro
update, you should see something like the following:
Fetching http://rotty.yi.org/doro/experimental/available.scm 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.
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]
Fetching http://rotty.yi.org/doro/experimental/srfi_0-20091204.zip
Installing srfi (0-20091204) ...
Fetching http://rotty.yi.org/doro/experimental/spells_0-20091204.zip
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.
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 upgradeAttempts to upgrade each package to the newest available version.
doro removeAllows you to remove packages from your system.
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. Options: --no-depends ignore dependencies --help show this help and exit
Next: Reference, Previous: Getting Started, Up: Top [Contents][Index]
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.
| • Packages | Anatomy of a Package | |
| • Destinations | Where a the Files of a Package go | |
| • Repositories | Where packages come from |
Next: Destinations, Up: Overview [Contents][Index]
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: Repositories, Previous: Packages, Up: Overview [Contents][Index]
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: Destinations, Up: Overview [Contents][Index]
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: Packaging Guide, Previous: Overview, Up: Top [Contents][Index]
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.
| • Global Options | These must go directly after doro
| |
| • Command Reference | All of the commands | |
| • Configuration File | Configuration file syntax |
Next: Command Reference, Up: Reference [Contents][Index]
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: Configuration File, Previous: Global Options, Up: Reference [Contents][Index]
Note that all commands take a --help option showing brief usage information, although that option is not explicitly listed below.
The following commands gather information; either from the package database, uninstalled bundles, or about the configuration.
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.
Temporarily adds bundle’s contents to the package database.
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:
Temporarily adds bundle’s contents to the package database.
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.
Shows the current configuration in YAML-like style.
Download information about available packages from all repositories of the selected destination.
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’.
Temporarily adds bundle’s contents to the package database.
Disable dependency resolution. This option allows for installing packages with unresolved dependencies.
Remove the listed packages from the system.
Disable dependency resolution. This option allows for removing packages that still have others depending on them.
Upgrade all packages to the newest available version.
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).
Select the implementation to use for that destination.
The following commands are of use if you want to create your own packages and repositories.
Create a bundle from the directories given as arguments.
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.
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.
Search the directories passed as arguments for bundles and produce an “available file” containing information about found bundles on standard output.
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: Command Reference, Up: Reference [Contents][Index]
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 "http://rotty.yi.org/doro/experimental") (repository unstable "http://rotty.yi.org/doro/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)
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
"http://rotty.yi.org/doro/experimental", denoting an HTTP
repository at the apparent location.
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.
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.
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>
“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.
| • A simple Example | Packaging in a nutshell | |
| • The Metadata File | The gory details |
Next: The Metadata File, Up: Packaging Guide [Contents][Index]
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 README
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))
(libraries
(sls -> "example"))
(programs
(("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 example/foo.sls example/bar.sls Category: programs hello Category: documentation README
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 "http://www.example.org/hello-world")
(libraries
(sls -> "example"))
(programs
(("programs" "hello.sps") -> "hello")))
Previous: Simple Packaging Example, Up: Packaging Guide [Contents][Index]
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:
synopsisA short single line describing the package briefly.
descriptionA longer, possibly multi-line description of the package.
homepageThis should carry an URL on which information about the software contained in the package can be found.
dependsDeclares the package’s dependencies.
librariesprogramsdocumentationmanThese 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.
installation-hookA package may specify actions to be executed during installation using this property.
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.
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:
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>+)
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.
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:
import libraries that are part of the
package or its dependencies.
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.
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.
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:
Install file src-filename, which is a string referring to an existing file.
Returns the name of the package being installed.
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: Packaging Guide, Up: Top [Contents][Index]
| Jump to: | B C D F I P R |
|---|
| Jump to: | B C D F I P R |
|---|