The optional argument INFOLIST should be an association list that
maps symbols to values, this list will be stored as ID.setup-info at the same
location as the extension code. Currently the following properties are used:
syntax
[extension 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
[extension 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
[extension property] (version STRING)
Specifies version string.
static
[extension property] (static STRING)
If the extension also provides a static library, then STRING should
contain the name of that library. Used by csc when compiling with
the -static-extensions option.
static-options
[extension property] (static-options STRING)
Additional options that should be passed to the linker when linking
with the static version of an extension (see static above). Used
by csc when compiling with the -static-extensions option.
All other properties are currently ignored. The FILELIST argument may also be a single
string.
install-program
[procedure] (install-program ID FILELIST [INFOLIST])
Similar to install-extension, but installs an executable program in the
executable path (usually /usr/local/bin).
install-script
[procedure] (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-install) 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.
try-compile
[procedure] (try-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.
chicken-prefix
[parameter] chicken-prefix
The installation prefix specified when CHICKEN was built.
installation-prefix
[parameter] installation-prefix
An alternative installation prefix that will be prepended to extension
installation paths if specified. It is set by the -install-prefix
option or environment variable CHICKEN_INSTALL_PREFIX.
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 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-install was invoked.
setup-install-mode
[parameter] (setup-install-mode [BOOL])
Reflects the setting of the -no-install option, i.e. is #f, if -no-install was
given to chicken-install.
required-chicken-version
[procedure] (required-chicken-version VERSION)
Signals an error if the version of CHICKEN that this script runs under is lexicographically less than
VERSION (the argument will be converted to a string, first).
required-extension-version
[procedure] (required-extension-version EXTENSION1 VERSION1 ...)
Checks whether the extensions EXTENSION1 ... are installed and at least of version VERSION1 ....
The test is made by lexicographically comparing the string-representations of the given version with the version
of the installed extension. If one of the listed extensions is not installed, has no associated version information
or is of a version older than the one specified.
cross-chicken
[procedure] (cross-chicken)
Returns #t if this system is configured for cross-compilation or #f
otherwise.
host-extension
[parameter] host-extension
For a cross-compiling CHICKEN, when compiling an extension, then it
should be built for the host environment (as opposed to the target
environment). This parameter is controlled by the -host-extension command-line
option. A setup script should perform the proper steps of compiling any
code by passing -host when invoking csc or using the compile
macro.
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 " !") )
We need a .setup script to build and install our nifty extension:
;;;; hello.setup
;; compile the code into a dynamically loadable shared object
;; (will generate hello.so)
(compile -s hello.scm)
;; Install as extension library
(install-extension 'hello "hello.so")
Lastly, we need a file hello.meta defining a minimal set of properties:
;;;; hello.meta
((author "Me")
(synopsis "A cool hello-world library")
(license "GPLv3")
(files "hello.scm" "hello.setup"))
(for more information about available properties, see Metafile reference)
After entering
$ chicken-install
at the shell prompt (and in the same directory where the two files
exist), the file hello.scm will be compiled into a dynamically
loadable library. If the compilation succeeds, hello.so will
be stored in the repository, together with a file named
hello.setup-info containing an a-list with metadata (what
you stored above in hello.meta).
If no extension name is given to chicken-install, it will simply
execute the any files with the .setup extension it can find.
Use it like any other CHICKEN extension:
$ csi -q
#;1> (require-extension hello)
; loading /usr/local/lib/chicken/4/hello.so ...
#;2> (hello "me")
Hello, me!
#;3>
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
(compile hello2.scm) ; compile `hello2'
(install-program 'hello2 "hello2") ; name of the extension and files to be installed
;;;; hello2.meta
((author "Me")
(synopsis "A cool hello-world application")
(license "proprietary")
(files "hello.scm" "hello.setup"))
To use it, just run chicken-install in the same directory:
$ chicken-install
(Here we omit the extension name)
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 and may have to run chicken-install with
administrative rights or use the -sudo option.
De-installation is just as easy - use the chicken-uninstall
program to remove one or more extensions from the local repository:
$ chicken-uninstall hello2
When running chicken-install with an argument NAME, for which
no associated .setup file exists, then it will try to download the
extension via HTTP from the CHICKEN code repository at
http://chicken.wiki.br/svn/chicken-eggs/. Extensions that are
required to compile and/or use the requested extension are downloaded
and installed automatically.
To query the list of currently installed extensions, use
chicken-status. It can list what extensions are installed and
what files belong to a particular installed extension.
chicken-install reference
Available options:
- -h -help
- show this message and exit
- -v -version
- show version and exit
- -force
- don't ask, install even if versions don't match
- -k -keep
- keep temporary files
- -l -location LOCATION
- install from given location instead of default
- -t -transport TRANSPORT
- use given transport instead of default
- -s -sudo
- use sudo(1) for installing or removing files
- -r -retrieve
- only retrieve egg into current directory, don't install
- -n -no-install
- do not install, just build (implies -keep)
- -p -prefix PREFIX
- change installation prefix to PREFIX
- -host-extension
- when cross-compiling, compile extension for host
- -test
- run included test-cases, if available
- -username USER
- set username for transports that require this
- -password PASS
- set password for transports that require this
- -i -init DIRECTORY
- initialize empty alternative repository
- -u -update-db
- update export database
chicken-uninstall reference
- -h -help
- show usage information and exit
- -v -version
- show version and exit
- -force
- don't ask, delete whatever matches
- -s -sudo
- use sudo(1) for deleting files
chicken-status reference
- -h -help
- show usage information and exit
- -v -version
- show version and exit
- -f -files
- list installed files
Security
When extensions are downloaded and installed one is executing code
from potentially compromised systems. This applies also when
chicken-install executes system tests for required extensions. As
the code has been retrieved over the network effectively untrusted
code is going to be evaluated. When chicken-install is run as
root the whole system is at the mercy of the build instructions
(note that this is also the case every time you install software via
sudo make install, so this is not specific to the CHICKEN
extension mechanism).
Security-conscious users should never run chicken-install as root.
A simple remedy is to set the environment variable
CHICKEN_REPOSITORY, which will transparently place the repository
at an arbitrary user-selected location (don't forget to initialize it
first with chicken-install -init <directory>). Alternatively
obtain write/execute access to the default location of the repository
(usually /usr/local/lib/chicken) to avoid running as
root. chicken-install also provides a -sudo option to perform
the last installation steps as root user, but do building and other
.setup script processing as normal.
Other modes of installation
It is possible to install extensions directly from a
Subversion repository or from a local
checkout of the repository tree by using the -transport and
-location options when invoking chicken-install. Three possible
transport mechanisms are currently supported:
- http
- download extension sources via HTTP from a web-server (this is the default)
- svn
- perform an svn export from the central extension repository; this will require a svn(1) client to be installed on the machine
- local
- use sources from the local filesystem and build directly in the source directory
The -location option specifies where to look for the source
repository and names a web URL, a subversion repository URL or a
filesystem path, respectively. A list of locations to try when
retrieving extensions is stored in the file setup.defaults
(usually installed in /usr/local/share/chicken). For http
transports, chicken-install will detect networking timeouts and
try alternative locations, as listed in the file.
Dependency information, which is necessary to ensure required
extensions are also installed, is processed automatically.
Linking extensions statically
The compiler and chicken-install support statically linked
eggs. The general approach is to generate an object file or static
library (in addition to the usual
shared library) in your .setup script and install it along with the
dynamically loadable extension. The setup properties static
should contain the name of the object file (or static library) to be
linked, when csc gets passed the -static-extensions option:
(compile -s -O2 -d1 my-ext.scm) ; dynamically loadable "normal" version
(compile -c -O2 -d1 my-ext -unit my-ext) ; statically linkable version
(install-extension
'my-ext
'("my-ext.so" "my-ext.o")
'((static "my-ext.o")) )
Note the use of the -unit option in the second compilation step: static
linking must use static library units. chicken-install will perform
platform-dependent file-extension translation for the file list, but does currently
not do that for the static extension property.
To actually link with the static version of my-ext, do:
% csc -static-extensions my-program.scm -uses my-ext
The compiler will try to do the right thing, but can not handle all
extensions, since the ability to statically link eggs is relatively
new. Eggs that support static linking are designated as being able to
do so. If you require a statically linkable version of an egg that has
not been converted yet, contact the extension author or the CHICKEN
mailing list.
Previous: Interface to external functions and variables
Next: Data representation