[Go to first, previous, next page;   contents]

6  The common-scheme Tool

The common-scheme tool is a convenience utility which handles the general areas of building and installing Common-Scheme software, including automatically fetching from peer-to-peer repositories and handling any dependencies.

The command syntax is

common-scheme <command> [options ...] [args ...]

The <command> chooses what action you want to and must always come first. The available commands are:

Each command is explained in detail below.

6.1  Options

The standard options are:

Options may be terminated with a double-dash ``-''. The options must always follow the command name, before any additional arguments passed to the command itself.

In addition you may specify an implementation to perform the action as, using the implementations name as an option. Currently, this includes:

The special option ``-all'' means to perform the action for all currently installed implementations, which is handy when installing software.

If no implementation is specified on the command-line or in the config files, then the implementation the common-scheme tool was compiled with will be used.

6.2  Module Name Dot Notation

Many of the commands refer to module names. To simplify use in command-line shells which would require quoting names with parenthesis and spaces, these commands use a dot notation formed by simply joining all the module name components with a dot. For example:

(com acme widget) => com.acme.widget

6.3  common-scheme Commands

6.3.1  script source [args ...]

Script runs source as a Scheme script, passing [args ...] to the script's entry-point procedure. source may be the local path to a source file, an HTTP URL to a remote source file, or a named module in dot notation registered in a known repository.

Examples:

6.3.2  build [source1 source2 ...]

This compiles the given source files in those implementations which have an external compiled form (currently Chicken, Gambit and SISC). The source locations may be a local file, remote URL or module name as in the script command. Sources which have an entry-point will be compiled as executables, otherwise they will be compiled as shared libraries.

If the recursive option is given, any dependant modules in the same relative path will also be built.

Any intermediate files (e.g. ``.c'' or ``.s'') files generated by the build will be removed afterwards, unless the keep-files option is specified.

6.3.3  install [source1 source2 ...]

This automatically installs all the listed sources which, you guessed it, may be local files, remote URLs or registered module names.

If the recursive option is specified, any module dependencies (either in the working directory or from remote modules) are installed as well.

6.3.4  update [repository ...]

With no arguments, this fetches and updates all currently know repositories. The first time run (or if you delete the cache file) this will fetch from the default list of know repositories which can be overridden with the repositories config option (see  6.4 below).

With one or more arguments, each is fetched as a URL and updated in the current repository list, registering it as a new repository if it hand't been fetched before. Thereafter any future updates will fetch and update the new repositories as well.

If the recursive option is specified, any peers of the updated modules will be fetched and added to the repository list as well.

6.3.5  upgrade [module ...]

Upgrades installed modules for which a new version is available. With no arguments checks all currently installed modules, otherwise checks only those modules on the command line.

Currently new versions are determined by comparing file modification times. In the future explicit versioning may be allowed, falling back on timestamps when no version information is available.

6.3.6  remove [module ...]

Removes the listed modules.

6.3.7  search [keyword ...]

Searches the names and descriptions of available modules for any of the keywords and prints a one-line summary of each match. If no keywords are specified, all available modules are displayed.

6.3.8  show [module ...]

Shows detailed information for the listed modules. With the verbose option set will show even more detailed information, such as the list of exported symbols.

6.3.9  list

Lists the names and one-line summaries of installed modules.

6.3.10  index [directory [file]]

Creates or updates a repository index for directory (default the current directory), writing it to file (default ``index.txt'' in the given directory).

This is how you manage your own repository that you want to share with others. All you have to do is make a directory of Scheme source available somewhere on the net and run this command on it. It will recursively search the directory for any Common-Scheme source, extract the relevant information and list it along with the file's modification time and path information in the index file. Basically it just does everything and you don't have to do anything to manage your repository except run this command when there's an update.

There are a few things you can do to make it easier for other user's to browse and use your software. By default there is no description of software, which makes the searching capabilities limited. But you can include a description clause in your module declaration and this will be included in the index file. For example:

(common-module (games board shogi)
  ((export play-shogi)
   (description
``A module for playing the game shogi.
The computer is very weak.
``))

...
)

You can also include a summary clause which will be used in one line summaries. If it is absent, the first line of the description will be used.

In general since any unknown module declarations are ignored by the Common-Scheme module system itself, you can put any information you want in the module fields and these will be displayed to users who run the show command. Suggested declarations are:

When the index file already exists, non-module declarations in the file are preserved. There are two non-module declarations of importance you may want to set.

The default-fields declaration specifies an alist of fields that are inherited by default for all modules in the index if not overridden. This is useful for specifying things common to all of your modules, such as the author and license.

The peers declaration simply contains a list of string URLs pointing to other repositories. This list is followed whenever a user updates your index with the recursive option set. When a new user creates their first repository, in addition to announcing it and sending the URL to their friends, if they know someone already in the network they can request to have their URL added to the friend's peers list. Then other users on the system will see the new modules seemlessly the next time they perform an update.

6.4  Config Files

In addition to command line options, you can specify default settings in config files. The system-wide config file is ``/etc/common-scheme/config'', and settings there can be overridden by the user's personal config file in `` /.common-scheme/config''.

Current settings include the following, the first seven of which can be set with command-line options:

In addition, you can specify any one of the command symbols followed by an alist, and those settings will take effect only when that particular command is run. This can be useful, for instance, to always enable recursive for specific commands, or to use a separate implementation for the script command.

[Go to first, previous, next page;   contents]