From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Andy Wingo Newsgroups: gmane.lisp.guile.devel Subject: guild hall update Date: Mon, 22 Aug 2011 18:00:52 +0200 Message-ID: <87wre5jv0r.fsf@pobox.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: dough.gmane.org 1314031901 9386 80.91.229.12 (22 Aug 2011 16:51:41 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 22 Aug 2011 16:51:41 +0000 (UTC) To: guile-devel Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Mon Aug 22 18:51:35 2011 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QvXin-0007VT-M0 for guile-devel@m.gmane.org; Mon, 22 Aug 2011 18:51:34 +0200 Original-Received: from localhost ([::1]:40873 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QvXim-0006LO-Lm for guile-devel@m.gmane.org; Mon, 22 Aug 2011 12:51:32 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:52831) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QvWw1-00058H-Cu for guile-devel@gnu.org; Mon, 22 Aug 2011 12:01:19 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QvWvs-0004X1-9X for guile-devel@gnu.org; Mon, 22 Aug 2011 12:01:09 -0400 Original-Received: from a-pb-sasl-sd.pobox.com ([74.115.168.62]:36120 helo=sasl.smtp.pobox.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QvWvr-0004Wq-NU for guile-devel@gnu.org; Mon, 22 Aug 2011 12:01:00 -0400 Original-Received: from sasl.smtp.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id E762E653D for ; Mon, 22 Aug 2011 12:00:58 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=pobox.com; h=from:to :subject:date:message-id:mime-version:content-type; s=sasl; bh=d diRBho8lsYuWlkuuZlf0TGkiBA=; b=LciTzBYvfkYluCA6p4Z+n05Pwm1Gmqd/e SmUq1W3yV8Vi9FNaKRYl/5R06dvjm130FqZTElaV+Fine1MtbTtfNO3slRHmhzNV njaDHfcCQOnFpt5ZxfQfT/2fIuYMDFvLH6hllhTFkItLCaPpdkBQqDi1Q/z73etR hthvyEJWys= DomainKey-Signature: a=rsa-sha1; c=nofws; d=pobox.com; h=from:to:subject :date:message-id:mime-version:content-type; q=dns; s=sasl; b=q69 BgudF3LEqSpwKjtSDKdzBNquYw76WEoxcW5YXXi7yT7sM8Ah1ibEynWV/t5x1XoE L28mKnlzREBX6e3x+FjynMgNX+QIjkHS2MkwNl7kh2rexcbtLH+tMR1Qeaqzri6z q1VDU5TqXExjJ86kdeqYadroECheZkHDkiUYnSxA= Original-Received: from a-pb-sasl-sd.pobox.com (unknown [127.0.0.1]) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTP id E12F3653C for ; Mon, 22 Aug 2011 12:00:58 -0400 (EDT) Original-Received: from badger (unknown [90.164.198.39]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by a-pb-sasl-sd.pobox.com (Postfix) with ESMTPSA id 95E826538 for ; Mon, 22 Aug 2011 12:00:57 -0400 (EDT) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.3 (gnu/linux) X-Pobox-Relay-ID: EC6CEADA-CCD7-11E0-B62C-B797DE995924-02397024!a-pb-sasl-sd.pobox.com X-detected-operating-system: by eggs.gnu.org: Solaris 10 (beta) X-Received-From: 74.115.168.62 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:12715 Archived-At: --=-=-= Hi all, Another status update on the construction of the guild hall. Since my last update, I moved all of the commands down from under the "guild hall" namespace, so that it's now "guild update", "guild install", etc. I also hacked a bit on the `guild' executable itself, allowing "guild help FOO" to work, and generally making `guild' more pleasant to use. Unlike dorodango, which has both global options and command-specific options (for example, "doro --global-foo command --command-bar"), the guild commands only take command-specific options. They also only take the set of options that they need. I have updated the manual with all of the details; a text copy is attached below. Another big change is that I renamed the package. The problem was that the package itself isn't really a "guild hall" -- it marks you as a member of the guild, giving you access to various guild halls on the net. After some hemming and hawwing I renamed it to "sigil" -- a graphic sign that marks you as a member of some group. It's your guild sigil? I think I got the meaning of this wrong though and we might need to change again. The image I have in my mind is of the sign hanging outside someone's shop. They still have those here in Barcelona, in some modern forms. Maybe the mental image of an old signet ring still works, though. Anyway the rename did clarify the documentation, by separating the name of the software package you install to enhance your `guild' command, from the name of the online archive. So those are the changes. Now, the problems. The biggest problem right now is that I don't know how it's supposed to work, by default. Should I be able to "guild install foo" and then run guile, and import the (foo) module directly? That's not how it currently works, because it installs to somewhere in ~/.local by default. Should I be able to install to the configured --prefix ? Should that be the default? If we install to the --prefix, is it in a guild hall path or is it in Guile's site dir? Should programs installed by the guild be in the default path? Also, many upstream dorodango R6RS packages still wouldn't work, because Guile doesn't do the .guile.sls / .sls thing by default. I think Guile needs an --r6rs option that enables that and other R6RS options. Sigil doesn't currently compile files that it installs. It probably should. It should probably recompile depending modules too, when updating a package. I feel like we should approach the problem from another direction for a little while: to think about what the user should type, and how that should enable the user to get their job done quickly and easily. I hope to pin down Ludovic and other interested parties this weekend at the GNU Hackers Meeting to see if we can make some progress here. Sigil itself is very close to being what we need, thanks mostly to Andreas' fantastic Dorodango. But we do need to continue thinking about our Guile users there. The code is here: https://gitorious.org/~wingo/dorodango/guildhall To check it out, you can: git clone git://gitorious.org/~wingo/dorodango/guildhall.git You'll need the latest Guile from the stable-2.0 branch. Just run autoreconf -vif && ./configure && make && sudo make install. You can make uninstall it later, that works fine. Cheers, Andy --=-=-= Content-Disposition: inline; filename=sigil.txt Sigil ***** This manual is for Sigil version 0.1.0. Sigil is a package manager written for Guile Scheme. A guild is an association of independent craftspeople. This sigil marks you as a member of the guild of Guile wizards and journeyfolk. On a practical level, Sigil lets you share Scheme modules and programs over the internet, and install code that has been shared by others. Sigil can handle dependencies, so when a program requires several libraries, and each of those has further dependencies, all of the prerequisites for the program can be installed in one go. Sigil is a port of Andreas Rottmann's Dorodango portable package manager for R6RS Scheme, adapted to better fit in with Guile Scheme environments. It is compatible with the R6RS Scheme package archives that Dorodango uses. 1 Getting Started ***************** 1.1 Installation ================ Sigil comes in a standard GNU tarball, and so the normal package installation techniques apply: tar -xjf sigil-0.1.0.tar.bz2 cd sigil-0.1.0/sigil ./configure make make check # become root make install Note that this assumes that you have installed Guile into the default prefix for `./configure', which is usually `/usr/local'. It is recommended to install sigil into the same prefix as your Guile installation, so if you installed Guile to `/usr', add `--prefix=/usr' after to your `./configure' invocation. After running installing Sigil, you should now be able to run `guild config --help', which displays a help message. 1.2 Quickstart ============== For the impatient, this section presents the minimum you need to know to install software using your new guild sigil. Configuration ------------- So, you've successfully installed Sigil, and were able to get the help message via `guild config --help'? Then it's time to tell Sigil where it can find software (*note Packages::) to install. Create the file `~/.config/sigil/config.scm' and add this line: (repository experimental "http://rotty.yi.org/doro/experimental") This tells the guild the location of the Andreas Rottmann's experimental repository, and gives it the name `experimental'. You could add further repositories with different names and locations, and Sigil will consider them all when installing packages. Updating the package database ----------------------------- This is all configuration that is needed; if you now run `guild update', you should see something like the following: $ guild update Fetching http://rotty.yi.org/doro/experimental/available.scm Loading available information for repository `experimental' Now you have obtained the information of available packages from the hall. You can verify that by running `guild list-packages --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 `guild install PACKAGE-NAME': % guild 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 listing, the guild 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 Sigil: installing software. There are a few other things you probably want to do at times: `guild upgrade' Attempts to upgrade each package to the newest available version. `guild remove' Allows you to remove packages from your system. Getting help ------------ For each command, you can invoke `guild help COMMAND', and it will show you what options and argument that command requires: % guild help remove Usage: guild remove PACKAGE... Remove installed packages. Options: --no-depends Ignore dependencies. -c, --config=FILE Use configuration file FILE, instead of the default. --no-config Do not read a configuration file. --help Print this help message. --version Print version information. 2 Overview ********** Sigil extends the `guild' program, provided by Guile, with a number of sub-comands that let you download, install, remove and upgrade Scheme modules and programs. The unit of installable software is the "package": a collection of modules, possibly including programs and documentation, together with some metadata. 2.1 Anatomy of a Package ======================== A package is the "unit of software" that Sigil 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 Sigil are: `libraries' R6RS libraries, and files required by them (either at runtime or at expand-time). `programs' R6RS programs. `documentation' README files, HTML documentation, etc. 2.2 Bundles =========== 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 packaging your or other people's software for the guild. 2.3 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_. For each destination, the guild 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 (http://www.pathname.com/fhs/) platforms: `libraries' Installed into `PREFIX/share/r6rs-libs'. `programs' 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 the guild initializes a destination. `documentation' Installed into PREFIX`/share/doc/libr6rs-PACKAGE-NAME'. For more on how to set the destination on the command line, *note Common Options::. 2.4 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. 3 Reference *********** Sigil doesn't actually install any programs. Instead, it extends the `guild' program that comes with Guile, adding new commands to it like `guild install', `guild upgrade', and the like. These sigil commands allow you, the guild member, to download, install and inspect packages containing Scheme code. The following subsections document the available commands, grouped by related tasks. 3.1 Common Options ================== Many commands take the same options, so we document them here in one section. In addition to the following, all commands take `--help' and `--version' options, although it's usually easier to type `guild help install' than `guild install --help'. 3.1.1 Config Options -------------------- Commands that need to access the sigil configuration file accept options to allow you choose a non-default file, or modify aspects of the configuration while the command is running. `--config=FILE' `-c' Use configuration file FILE, instead of the default one. *Note Configuration File::, for configuration file syntax. `--no-config' Do not read any configuration file. This option can be used to ensure that sigil commands will just use built-in defaults. `--prefix=PREFIX' 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 the sigil command. 3.1.2 Database Options ---------------------- Commands that query or modify the package database accept options to allow you to choose particular destinations or enable certain repositories. `--repo=URI' `-r URI' Add URI as an additional repository, during the extent of this command. `--dest=DEST-NAME' `-d DEST-NAME' Choose a specific destination, instead of the default one. A destination specifies where to install software. Destinations are associated with paths in the file system via entries in the configuration file. 3.1.3 UI Options ---------------- Some commands might need input from the user. These options allow a user to specifiy their choices in advance. `--non-interactive' `-n' 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. `--yes' `-y' Like `--non-interactive', but silently assume "yes" on all questions, even risky ones. 3.2 Command Reference ===================== 3.2.1 Querying -------------- The following commands gather information; either from the package database, uninstalled bundles, or about the configuration. -- Command: list-packages Produces a list of packages, along with their installation status and version on standard output. `--all' `-a' Show all packages, including uninstalled, but available ones. By default only installed packages are listed. `--bundle=BUNDLE' `-b BUNDLE' Temporarily adds BUNDLE's contents to the package database. This command also accepts config and database options, as listed in the previous section. -- 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: * A package name; in that case, all versions of PACKAGE are shown. It is not error when the package does not exist in the database or has no versions, but that package will be simply ignored. * A package name and version, separated by an equal sign, for example `foo=0.1.0'. Only the specified version will be shown in this case. It is not an error if the package or specified version cannot be found, but the package will simply be ignored. `--bundle=BUNDLE' `-b BUNDLE' Temporarily adds BUNDLE's contents to the package database. This command also accepts config and database options, as listed in the previous section. -- 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. *Note Packages::. -- Command: config Shows the current configuration in YAML-like style. This command takes config options. 3.2.2 Package managment ----------------------- In addition to the options listed below, all of these commands take config, database, and UI options. *Note Common Options::. -- 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'. `--bundle=BUNDLE' `-b BUNDLE' Temporarily adds BUNDLE's contents to the package database. `--no-depends' Disable dependency resolution. This option allows for installing packages with unresolved dependencies. -- Command: remove package ... Remove the listed PACKAGEs from the system. `--no-depends' 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. 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. `--output=FILENAME' `-o FILENAME' Output the bundle to FILENAME. When this option is not given, the guild will try to name the bundle based on the package contained in it. Should the bundle contain multiple packages, this option is mandatory. `--directory=DIRECTORY' `-d DIRECTORY' Output directory for the created bundle file. This option only has an effect when `--output' is _not_ provided. `--append-version=VERSION' 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. `--output=FILENAME' `-o FILENAME' -- Command: symlink-bundle bundle-directory target-directory Create a symbolic link tree in TARGET-DIRECTORY, using the bundle at BUNDLE-DIRECTORY. `--force' Allow the command to operate even when TARGET-DIRECTORY already exists. `--deep' Create a symbolic link for every file. Without this option, `guild hall' will create symbolic links to directories when this doesn't change the created symlink tree. `--include=PACKAGES' Create symbolic links just for the packages listed in the comma- or space-seperated list PACKAGES. `--exclude=PACKAGES' Create symbolic links for all _but_ the packages listed in the comma- or space-seperated list PACKAGES. 3.3 Configuration File ====================== The configuration file stores permanent settings for the guild, and can be selected with the `--config' option, *note Common Options::. Its 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 (*note 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) 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 ) In the running example, is `experimental', and is the string `"http://rotty.yi.org/doro/experimental"', 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 (http://www.pathname.com/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 the `--dest' option. *Note Common 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, the guild will use a default location, based on the destination's prefix. 3.3.3 Defaults -------------- Using the `default-destination' clause one can specify which configured destination will be used when none is explicitly specified via the `--dest' option. If there is no `default-destination' clause, the first destination specified is considered the default. 3.3.4 Formal Grammar -------------------- A complete BNF-style grammar for the configuration file: -> * -> | | -> (repository ) -> (destination