You are looking at historical revision 1933 of this page. It may differ significantly from its current revision.

chicken-setup

Extension libraries

Extension libraries are extensions to the core functionality provided by the basic CHICKEN system, to be built and installed separately. The mechanism for loading compiled extensions is based on dynamically loadable code and as such is only available on systems on which loading compiled code at runtime is supported. Currently this are most UNIX-compatible platforms that provide the libdl functionality like Linux, Solaris, BSD, Mac OS X and Windows using Cygwin. Windows with the Microsoft tools is partially supported.

Note: Extension may also be normal applications or shell scripts.

Installing extensions

To install an extension library, run the chicken-setup program with the extension name as argument. If the extension consists of a single Scheme file, then it is compiled and installed in the extension repository. If it is an archive containing addition files, then the files are extracted and the contained setup script is executed. This setup script is a normal Scheme source file, which will be interpreted by chicken-setup. The complete language supported by csi is available, and the library units srfi-1 regex utils posix tcp are loaded. Additional libraries can of course be loaded at run-time.

The setup script should perform all necessary steps to build the new library (or application). After a successful build, the extension can be installed by invoking one of the procedures install-extension, install-program or install-script. These procedures will copy a number of given files into the extension repository or in the path where the CHICKEN executables are located (in the case of executable programs or scripts). Additionally the list of installed files, and user-defined metadata is stored in the repository.

If no extension name is given on the command-line, and if none of the options -list, -version, -repository (without argument), -program-path (without argument), -fetch or -docindex is given, then all .setup scripts in the current directory are processed.

Creating extensions

Extensions can be created by creating an (optionally gzipped) tar archive named EXTENSION.egg containing all needed files plus a .setup script in the root directory. After chicken-setup has extracted the files, the setup script will be invoked. There are no additional constraints on the structure of the archive, but the setup script has to be in the root path of the archive.

Procedures and macros available in setup scripts

install-extension

 
(install-extension ID FILELIST [INFOLIST])

Installs the extension library with the name ID. All files given in the list of strings FILELIST will be copied to the extension repository. It should be noted here that the extension id has to be identical to the name of the file implementing the extension. The extension may load or include other files, or may load other extensions at runtime specified by the require-at-runtime property.

FILELIST may be a filename, a list of filenames, or a list of pairs of the form (SOURCE DEST) (if you want to copy into a particular sub-directory - the destination directory will be created as needed). If DEST is a relative pathname, < it will be copied into the extension repository.

The optional argument INFOLIST should be an association list that maps symbols to values, this list will be stored as ID.setup at the same location as the extension code. Currently the following properties are used:

syntax
 
[property] (syntax)

Marks the extension as syntax-only. No code is compiled, the extension is intended as a file containing macros to be loaded at compile/macro-expansion time.

require-at-runtime
 
[property] (require-at-runtime ID ...)

Specifies extensions that should be loaded (via require) at runtime. This is mostly useful for syntax extensions that need additional support code at runtime.

version
 
[property] (version STRING)

Specifies version string.

documentation
 
[property] (documentation FILENAME)

The filename of a HTML document containing extension-specific documentation. This file should be given in the file-list passed to install-extension and a link to it will be automatically included in the index page (accessible via chicken-setup -docindex).

examples
 
[property] (examples FILENAME ...)

Copies the given files into the examples directory, which is usually $prefix/share/chicken/examples (equivalent to $CHICKEN_HOME/examples or (make-pathname (chicken-home) "examples")).

exports
 
[property] (exports EXPORT ...)

Add export-information to the generated extension-information. EXPORT may be a symbol naming an exported toplevel variable or a string designating a file with exported variables, as generated by the -emit-exports option or the emit-exports declaration specifier.

All other properties are currently ignored. The FILELIST argument may also be a single string.

install-program

 
(install-program ID FILELIST [INFOLIST])

Similar to install-extension, but installs an executable program in the executable path (usually /usr/local/bin).

install-script

 
(install-script ID FILELIST [INFOLIST])

Similar to install-program, but additionally changes the file permissions of all files in FILELIST to executable (for installing shell-scripts).

run

 
[syntax] (run FORM ...)

Runs the shell command FORM, which is wrapped in an implicit quasiquote. (run (csc ...)) is treated specially and passes -v (if -verbose has been given to chicken-setup) and -feature compiling-extension options to the compiler.

compile

 
[syntax] (compile FORM ...)

Equivalent to (run (csc FORM ...)).

make

 
[syntax] (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)

A make macro that executes the expressions COMMAND ..., when any of the dependents DEPENDENT ... have changed, to build TARGET. This is the same as the make extension, which is available separately. For more information, see make.

patch

 
[procedure] (patch WHICH REGEX SUBST)

Replaces all occurrences of the regular expression REGEX with the string SUBST, in the file given in WHICH. If WHICH is a string, the file will be patched and overwritten. If WHICH is a list of the form OLD NEW, then a different file named NEW will be generated.

copy-file

 
[procedure] (copy-file FROM TO)

Copies the file or directory (recursively) given in the string FROM to the destination file or directory TO.

move-file

 
[procedure] (move-file FROM TO)

Moves the file or directory (recursively) given in the string FROM to the destination file or directory TO.

remove-file*

 
[procedure] (remove-file* PATH)

Removes the file or directory given in the string PATH.

find-library

 
[procedure] (find-library NAME PROC)

Returns #t if the library named libNAME.[a|so] (unix) or NAME.lib (windows) could be found by compiling and linking a test program. PROC should be the name of a C function that must be provided by the library. If no such library was found or the function could not be resolved, #f is returned.

find-header

 
[procedure] (find-header NAME)

Returns #t if a C include-file with the given name is available, or #f otherwise.

test-compile

 
[procedure] (test-compile CODE #!key cc cflags ldflags compile-only c++)

Returns #t if the C code in CODE compiles and links successfully, or #f otherwise. The keyword parameters cc (compiler name, defaults to the C compiler used to build this system), cflags and ldflags accept additional compilation and linking options. If compile-only is true, then no linking step takes place. If the keyword argument c++ is given and true, then the code will be compiled in C++ mode.

create-directory

 
[procedure] (create-directory PATH)

Creates the directory given in the string PATH, with all parent directories as needed.

installation-prefix

 
[parameter] installation-prefix

Holds the prefix under which CHICKEN executables and libraries have been installed (either the value of the environment variable CHICKEN_PREFIX or whatever prefix was specified at the time the system was built.

program-path

 
[parameter] (program-path [PATH])

Holds the path where executables are installed and defaults to either $CHICKEN_PREFIX/bin, if the environment variable CHICKEN_PREFIX is set, $CHICKEN_HOME or the path where the CHICKEN binaries (chicken, csi, etc.) are installed.

setup-root-directory

 
[parameter] (setup-root-directory [PATH])

Contains the path of the directory where chicken-setup was invoked.

setup-build-directory

 
[parameter] (setup-build-directory [PATH])

Contains the path of the directory where the extension is built. This is not necessarily identical to setup-root-directory.

setup-verbose-flag

 
[parameter] (setup-verbose-flag [BOOL])

Reflects the setting of the -verbose option, i.e. is #t, if -verbose was given.

setup-install-flag

 
[parameter] (setup-install-flag [BOOL])

Reflects the setting of the --no-install option, i.e. is #f, if -no-install was given.

Examples for extensions

The simplest case is a single file that does not export any syntax. For example

;;;; hello.scm

(define (hello name)
  (print "Hello, " name " !") )

After entering

$ chicken-setup hello

at the shell prompt, the file hello.scm will be compiled into a dynamically loadable library, with the default compiler options -optimize-level 2 -no-trace -shared. If the compilation succeeds, hello.so will be stored in the repository, together with a file named hello.setup (not to be confused with a setup script - this .setup file just contains an a-list with metadata).

Use it like any other CHICKEN extension:

$ csi -q
#;1> (require-extension hello)
; loading /usr/local/lib/chicken/hello.so ...
#;2> (hello "me")
Hello, me!
#;3>

For more elaborate build operations, when installing applications or scripts, or when additional metadata should be stored for an extension, a setup script is required and the script and all additional files should be packaged in a gzipped tar archive.

Here we create a simple application:

;;;; hello2.scm

(print "Hello, ")
(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
(print "!")

We also need a setup script:

;;;; hello2.setup

(run (csc hello2.scm))  ; compile `hello2'
(install-program 'hello2 "hello2") ; name of the extension and files to be installed

To use it, just run chicken-setup in the same directory:

$ chicken-setup hello2

Now the program hello2 will be installed in the same location as the other CHICKEN tools (like chicken, csi, etc.), which will normally be /usr/local/bin. Note that you need write-permissions for those locations.

Uninstallation is just as easy:

$ chicken-setup -uninstall hello2

chicken-setup provides a make macro, so building operations can be of arbitrary complexity. When running chicken-setup with an argument NAME, for which no associated file NAME.setup, NAME.egg or NAME.scm exists will ask you to download the extension via HTTP from the default URL http://www.call-with-current-continuation.org/eggs. You can use the -host option to specify an alternative source location.

If the given extension name contains a path prefix and the -host option is given, then chicken-setup can also download and install eggs from an arbitrary HTTP server. Alternatively you can pass a full URL (including the http:// prefix. Note that no dependency checks are done when downloading eggs directly with the URL syntax.

Finally a somewhat more complex example: We want to package a syntax extension with additional support code that is to be loaded at run-time of any Scheme code that uses that extension. We create a glass lambda, a procedure with free variables that can be manipulated from outside:

;;;; glass.scm

(define-macro (glass-lambda llist vars . body)
  ;; Low-level macros are fun!
  (let ([lvar (gensym)]
	[svar (gensym)] 
	[x (gensym)]
	[y (gensym)] 
	[yn (gensym)] )
    `(let ,(map (lambda (v) (list v #f)) vars)
       (define (,svar ,x . ,y)
	 (let* ([,yn (pair? ,y)]
		[,y (and ,yn (car ,y))] )
	   (case ,x
	     ,@(map (lambda (v)
		      `([,v] (if ,yn 
				 (set! ,v ,y)
				 ,v) ) )
		    vars)
	     (else (error "variable not found" ,x)) ) ) )
       (define ,lvar (lambda ,llist ,@body))
       (extend-procedure ,lvar ,svar) ) ) )

Here some support code that needs to be loaded at runtime:

;;;; glass-support.scm

(require-extension lolevel)

(define glass-lambda-accessor procedure-data)
(define (glass-lambda-ref gl v) ((procedure-data gl) v))
(define (glass-lambda-set! gl v x) ((procedure-data gl) v x))

The setup script looks like this:

(run (csc -s -O2 -d0 glass-support.scm))

(install-extension
  'glass
  '("glass.scm" "glass-support.so")
  '((syntax) (require-at-runtime glass-support)) )

The invocation of install-extension provides the files that are to be copied into the extension repository, and a metadata list that specifies that the extension glass is a syntax extension and that, if it is declared to be used by other code (either with the require-extension or require-for-syntax form), then client code should perform an implicit (require 'glass-support) at startup.

This can be conveniently packaged as an egg:

$ tar cfz glass.egg glass.setup glass.scm glass-support.scm

And now we use it:

$ chicken-setup glass
$ csi -quiet
#;1> (require-extension glass)
; loading /usr/local/lib/chicken/glass.scm ...
; loading /usr/local/lib/chicken/glass-support.so ...
#;2> (define foo (glass-lambda (x) (y) (+ x y)))
#;3> (glass-lambda-set! foo 'y 99)
#;4> (foo 33)
132

chicken-setup reference

Available options:

-h -help
Show usage information and exit.
-V -version
Display version and exit.
-R -repository [PATHNAME]
When used without an argument, the path of the extension repository is displayed on standard output. When given an argument, the repository pathname (and the repository-path parameter) will be set to PATHNAME for all subsequent operations. The default repository path is the installation library directory (usually /usr/local/lib/chicken), or (if set) the directory given in the environment variable CHICKEN_REPOSITORY. PATHNAME should be an absolute pathname.
-P -program-path [PATHNAME]
When used without an argument, the path for executables is displayed on standard output. When given an argument, the program path for installing executables and scripts will be set to PATHNAME for all subsequent operations. PATHNAME should be an absolute pathname.
-h -host HOSTNAME[:PORT]
Specifies alternative host for downloading extensions, optionally with a TCP port number (which defaults to 80).
-u -uninstall EXTENSION
Removes all files that were installed for EXTENSION from the file-system, together with any metadata that has been stored.
-l -list [NAME ...]
List all installed extensions or show extension information.
-r -run FILENAME
Load and execute given file.
-s -script FILENAME
Executes the given Scheme source file with all remaining arguments and exit. The she-bang shell script header is recognized, so you can write Scheme scripts that use chicken-setup just as with csi.
-e -eval EXPRESSION
Evaluates the given expression(s).
-v -verbose
Display additional debug information.
-k -keep
Keep temporary files and directories.
-c -csc-option OPTION
Passes OPTION as an extra argument to invocations of the compiler-driver (csc). This works only if csc is invoked as (run (csc ...)).
-d -dont-ask
Do not ask the user before trying to download required extensions.
-n -no-install
Do not install generated binaries and/or support files. Any invocations of install-program, install-extension or install-script will be be no-ops.
-i -docindex
Displays the path to the index-page of any installed extension-documentation. If the index page does not exist, it is created.
-C -check
Downloads the repository-index and lists locally installed extensions for which a newer release is available for download.
-t -test EXTENSION ...
return success if all given extensions are installed
-ls EXTENSION
List installed files for extension
-fetch-tree
Downloads and prints the repository catalog
--
Ignore all following arguments.

Note that the options are processed exactly in the order in which they appear in the command-line.

Windows notes

chicken-setup works on Windows, when compiled with Visual C++, but depends on the tar and gunzip tools to extract the contents of an egg. The best way is to download an egg either manually (or with chicken-setup -fetch) and extract its contents with a separate program (like winzip). the CHICKEN_REPOSITORY environment variable has to be set (in addition to CHICKEN_HOME) to a directory where your compiled extensions should be located.

The .setup scripts will not always work under Windows, and the extensions may require libraries that are not provided for Windows or work differently. Under these circumstances it is recommended to perform the required steps to build an extension manually.

Previous: Interface to external functions and variables

Next: Data representation