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 ...]
<command> chooses what action you want to and must always come
first. The available commands are:
script- run a file as a script
build- compile files
install- install files
update- retrieve new lists of modules
upgrade- upgrade some or all outdated modules
remove- remove installed modules
search- search for modules containing keywords
show- show detailed module information
list- list installed modules
index- create a repository index file
help- a brief usage message
Each command is explained in detail below.
The standard options are:
-v, -verbose - report extra information
-s, -silent - keep output to a minimum
-r, -recursive - recursively build/install dependent files
-n, -no-action - just print what actions would be performed
-k, -keep-files - don't clean up intermediate files
-f, -force-build - build even if the file is up-to-date
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.
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
source as a Scheme script, passing
[args ...] to
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.
common-scheme script dance.scm --with-cows tango.steps
This runs the script
dance.scmunder the user's default implementation, passing it the options
--with-cows tango.steps. In many cases the way to run this without the common-scheme tool is obvious - for instance to run it under Gauche one would just use:
gosh dance.scm --with-cows tango.steps
However it can be a handy convenience if you're trying a new implementation you don't usually use, and don't know that the Chicken version uses
csi -scriptor that the Guile version uses
guile -s, etc.
common-scheme script -gambit sing.scm --with-feeling
Again, this runs a local file as a script, this time overriding the default common-scheme implementation to Gambit.
common-scheme script http://www.acme.com/widget.scm
This runs a script from a remote URL by downloading it to a temporary file, providing a quick and easy way to try out someone's script without even using a webbrowser.
common-scheme script com.acme.widget
This will search your repository list for a module named
com acme widget, and if found lookup the path and run it as a remote URL.
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
script command. Sources which have an entry-point will be
compiled as executables, otherwise they will be compiled as shared
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
This automatically installs all the listed sources which, you guessed it, may be local files, remote URLs or registered module names.
recursive option is specified, any module dependencies
(either in the working directory or from remote modules) are installed
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
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.
recursive option is specified, any peers of the updated
modules will be fetched and added to the repository list as well.
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.
Removes the listed modules.
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.
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.
Lists the names and one-line summaries of installed modules.
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
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:
homepage- a string URL of the projects homepage
version- a string or symbol in version number format (2.1.3a)
license- a symbol naming the license such as
GPL, optionally followed by a string URL pointing to a more complete description
author- the author's name
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.
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.
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.
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:
verbose? - enable verbose output
silent? - reduce output
recursive? - act recursively where possible
force-build? - force builds even when files are up-to-date
no-action? - don't perform actions, just report what would be done
keep-intermediate-files? - don't delete intermediate build files
default-implementation - implementation to run as
repositories - a list of repositories to update the first time
hidden-fields - module fields not to display by default with show
c-compiler - path to the C compiler
chicken-compiler - path to the Chicken compiler
chicken-compiler-options - list of symbol or string options
chicken-interpreter - path to the Chicken interpreter
chicken-setup - path to the chicken-setup program
chicken-modules-dir - path to the chicken installed eggs directory
gambit-compiler - path to the Gambit compiler
gambit-compiler-options - list of symbol or string options
gambit-interpreter - path to the Gambit interpreter
gambit-modules-dir - path to the Gambit installed modules directory
gauche-interpreter - path to the Gauche interpreter (gosh)
gauche-config - path to the gauche-config program
gauche-modules-dir - path to the Gauche installed modules directory
guile-interpreter - path to the Guile interpreter
guile-config - path to the guile-config program
guile-modules-dir - path to the Guile installed modules directory
sisc - path to the SISC program
sisc-modules-dir - path to the SISC installed modules directory
bin-dir - path to install binaries (/usr/local/bin)
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