man clisp (1): m[blue]ANSIm[][38] m[blue]Common Lispm[][1] compiler, interpreter and debugger.

SYNOPSIS

clisp [[-h] | [--help]] [--version] [--license] [-help-image] [-B lisp-lib-dir] [-b] [-K linking-set] [-M mem-file] [-m memory-size] [-L language] [-N locale-dir] [-Edomain encoding] [[-q] | [--quiet] | [--silent] | [-v] | [--verbose]] [-on-error action] [-repl] [-w] [-I] [-disable-readline] [[-ansi] | [-traditional]] [-modern] [-p package] [-C] [-norc] [-lp directory...] [-i init-file...] [-c [-l] lisp-file [-o output-file]...] [-x expressions...] [lisp-file [argument...]]

DESCRIPTION

Invokes the m[blue]Common Lispm[][1] interpreter and compiler.

Interactive Mode

When called without arguments, executes the m[blue]read-eval-print loopm[][2], in which expressions are in turn

: • m[blue]READm[][3] from the standard input,

: • m[blue]EVALm[][4]uated by the lisp interpreter,

: • and their results are m[blue]PRINTm[][5]ed to the standard output.

Non-Interactive (Batch) Mode

Invoked with -c, compiles the specified lisp files to a platform-independent bytecode which can be executed more efficiently.

Invoked with -x, executes the specified lisp expressions.

Invoked with lisp-file, runs the specified lisp file.

OPTIONS

-h
--help

: Displays a help message on how to invoke m[blue]CLISPm[][6].

--version

: Displays the m[blue]CLISPm[][6] version number, as given by the function m[blue]LISP-IMPLEMENTATION-VERSIONm[][7], the value of the variable *FEATURES*, as well some other information.

--license

: Displays a summary of the licensing information, the m[blue]GNUm[][8] m[blue]GPLm[][9].

-help-image

: Displays information about the memory image being invoked: whether is it suitable for scripting as well as the :DOCUMENTATION supplied to EXT:SAVEINITMEM.

-B lisp-lib-dir

: Specifies the installation directory. This is the directory containing the linking sets and other data files. This option is normally not necessary, because the installation directory is already built-in into the clisp executable. Directory lisp-lib-dir can be changed dynamically using the m[blue]SYMBOL-MACROm[][10] CUSTOM:*LIB-DIRECTORY*.

-b

: Print the installation directory and exit immediately. The namestring of CUSTOM:*LIB-DIRECTORY* is printed without any quotes. This is mostly useful in module Makefiles, see, e.g., modules/syscalls/Makefile.in (file in the CLISP sources).

-K linking-set

Specifies the linking set to be run. This is a directory (relative to the lisp-lib-dir) containing at least a main executable (runtime) and an initial memory image. Possible values are

base

: the core m[blue]CLISPm[][6]

full

: core plus all the modules with which this installation was built, see Section 32.2, "External Modules".

The default is base.

-M mem-file

: Specifies the initial memory image. This must be a memory dump produced by the EXT:SAVEINITMEM function by this clisp runtime. It may have been compressed using m[blue]GNUm[][8] m[blue]gzipm[][11].

-m memory-size

Sets the amount of memory m[blue]CLISPm[][6] tries to grab on startup. The amount may be given as

n
nB

: measured in bytes

n
nW

: measured in machine words (4×n on 32-bit platforms, 8×n on 64-bit platforms)

nK
nKB

: measured in kilobytes

nKW

: measured in kilowords

nM
nMB

: measured in megabytes

nMW

: measured in megawords

The default is 3 megabytes. The argument is constrained above 100 KB.

This version of m[blue]CLISPm[][6] is not likely to actually use the entire memory-size since garbage-collection will periodically reduce the amount of used memory. It is therefore common to specify 10 MB even if only 2 MB are going to be used.

-L language

: Specifies the language m[blue]CLISPm[][6] uses to communicate with the user. This may be one of english, german, french, spanish, dutch, russian, danish. Other languages may be specified through the m[blue]environment variablem[][12] LANG, provided the corresponding message catalog is installed. The language may be changed dynamically using the m[blue]SYMBOL-MACROm[][10] CUSTOM:*CURRENT-LANGUAGE*.

-N locale-dir

: Specifies the base directory of locale files. m[blue]CLISPm[][6] will search its message catalogs in locale-dir/language/LC_MESSAGES/clisp.mo. This directory may be changed dynamically using the m[blue]SYMBOL-MACROm[][10] CUSTOM:*CURRENT-LANGUAGE*.

-Edomain encoding

Specifies the encoding used for the given domain, overriding the default which depends on the m[blue]environment variablem[][12]s LC_ALL, LC_CTYPE, LANG. domain can be

file

: affecting CUSTOM:*DEFAULT-FILE-ENCODING*

pathname

: affecting CUSTOM:*PATHNAME-ENCODING*

terminal

: affecting CUSTOM:*TERMINAL-ENCODING*

foreign

: affecting CUSTOM:*FOREIGN-ENCODING*

misc

: affecting CUSTOM:*MISC-ENCODING*

blank

: affecting all of the above.

: Warning
Note that the values of these m[blue]SYMBOL-MACROm[][10]s that have been saved in a memory image are ignored: these m[blue]SYMBOL-MACROm[][10]s are reset based on the OS environment after the memory image is loaded. You have to use the RC file, CUSTOM:*INIT-HOOKS* or init function to set them on startup, but it is best to set the aforementioned m[blue]environment variablem[][12]s appropriately for consistency with other programs. See Section 31.1, "Customizing CLISP Process Initialization and Termination".

-q
--quiet
--silent
-v
--verbose

: Change verbosity level: by default, m[blue]CLISPm[][6] displays a banner at startup and a good-bye message when quitting, and initializes m[blue]*LOAD-VERBOSE*m[][13] and m[blue]*COMPILE-VERBOSE*m[][14] to m[blue]Tm[][15], and m[blue]*LOAD-PRINT*m[][13] and m[blue]*COMPILE-PRINT*m[][14] to m[blue]NILm[][16], as per [ANSI CL standard]. The first -q removes the banner and the good-bye message, the second sets variables m[blue]*LOAD-VERBOSE*m[][13], m[blue]*COMPILE-VERBOSE*m[][14] and CUSTOM:*SAVEINITMEM-VERBOSE* to m[blue]NILm[][16]. The first -v sets variables CUSTOM:*REPORT-ERROR-PRINT-BACKTRACE*, m[blue]*LOAD-PRINT*m[][13] and m[blue]*COMPILE-PRINT*m[][14] to m[blue]Tm[][15], the second sets CUSTOM:*LOAD-ECHO* to m[blue]Tm[][15]. These settings affect the output produced by -i and -c options. Note that these settings persist into the m[blue]read-eval-print loopm[][2]. Repeated -q and -v cancel each other, e.g., -q -q -v -v -v is equivalent to -v.

-on-error action

Establish global error handlers, depending on action:.PP appease

: m[blue]continuablem[][17] m[blue]ERRORm[][18]s are turned into m[blue]WARNINGm[][19]s (with EXT:APPEASE-CERRORS) other m[blue]ERRORm[][18]s are handled in the default way

debug

: m[blue]ERRORm[][18]s m[blue]INVOKE-DEBUGGERm[][20] (the normal m[blue]read-eval-print loopm[][2] behavior), disables batch mode imposed by -c, -x, and lisp-file,

abort

: m[blue]continuablem[][17] m[blue]ERRORm[][18]s are appeased, other m[blue]ERRORm[][18]s are m[blue]ABORTm[][21]ed with EXT:ABORT-ON-ERROR

exit

: m[blue]continuablem[][17] m[blue]ERRORm[][18]s are appeased, other m[blue]ERRORm[][18]s terminate m[blue]CLISPm[][6] with EXT:EXIT-ON-ERROR (the normal batch mode behavior).

LANGUAGE REFERENCE

The language implemented is m[blue]ANSI[39]m[][38] m[blue]Common Lispm[][1]. The implementation mostly conforms to the ANSI Common Lisp standard, see Section 31.10, "Maximum ANSI CL compliance". [ANSI CL] ANSI CL standard1994. ANSI INCITS 226-1994 (R1999)
m[blue]Information Technology - Programming Language - Common Lispm[][40]
[formerly ANSI X3.226-1994 (R1999)].

COMMAND LINE USER ENVIRONMENT

help

: get context-sensitive on-line help, see Chapter 25, Environment.

(APROPOS name)

: list the m[blue]SYMBOLm[][41]s matching name.

(DESCRIBE symbol)

: describe the symbol.

(exit)
(quit)
(bye)

: quit m[blue]CLISPm[][6].

EOF (Control+D on m[blue]UNIXm[][42])

: leave the current level of the m[blue]read-eval-print loopm[][2] (see also Section 1.1, "Special Symbols ").

arrow keys

: for editing and viewing the input history, using the m[blue]GNUm[][8] m[blue]readlinem[][26] library.

TAB key

Context sensitive:

: • If you are in the "function position" (in the first symbol after an opening paren or in the first symbol after a m[blue]#'m[][44]), the completion is limited to the symbols that name functions.

: • If you are in the "filename position" (inside a string after m[blue]#Pm[][45]), the completion is done across file names, m[blue]GNUm[][8] m[blue]bashm[][46]-style.

: • If you have not typed anything yet, you will get a help message, as if by the help command.

: • If you have not started typing the next symbol (i.e., you are at a whitespace), the current function or macro is DESCRIBEd.

: • Otherwise, the symbol you are currently typing is completed.

USING AND EXTENDING CLISP

m[blue]Common Lispm[][1] is a programmable programming language. ---m[blue]John Foderarom[][47].PP When m[blue]CLISPm[][6] is invoked, the runtime loads the initial memory image and outputs the prompt; at which one can start typing m[blue]DEFVARm[][48]s, m[blue]DEFUNm[][49]s and m[blue]DEFMACROm[][50]s.

To avoid having to re-enter the same definitions by hand in every session, one can create a lisp file with all the variables, functions, macros, etc.; (optionally) compile it with m[blue]COMPILE-FILEm[][51]; and m[blue]LOADm[][31] it either by hand or from the RC file; or save a memory image to avoid the m[blue]LOADm[][31] overhead.

However, sometimes one needs to use some functionality implemented in another language, e.g., call a m[blue]Cm[][52] library function. For that one uses the Foreign Function Interface and/or the External Modules facility. Finally, the truly adventurous ones might delve into Extending the Core.

FILES

clisp
clisp.exe

: startup driver (an executable or, rarely, a shell script) which remembers the location of the runtime and starts it with the appropriate arguments

lisp.run
lisp.exe

: main executable (runtime) - the part of m[blue]CLISPm[][6] implemented in m[blue]Cm[][52].

lispinit.mem

: initial memory image (the part of m[blue]CLISPm[][6] implemented in lisp)

config.lisp

: site-dependent configuration (should have been customized before m[blue]CLISPm[][6] was built); see Section 31.12, "Customizing CLISP behavior"

*.lisp

: lisp source

*.fas

: lisp code, compiled by m[blue]CLISPm[][6]

*.lib

: lisp source library information, generated by COMPILE-FILE, see Section 24.3, "Function REQUIRE".

*.c

: C code, compiled from lisp source by m[blue]CLISPm[][6] (see Section 32.3, "The Foreign Function Call Facility")

For the m[blue]CLISPm[][6] source files, see Chapter 34, The source files of CLISP.

INPUT AND OUTUT

See Section 21.1.1, "Initialization of Standard Streams".

BUGS

When you encounter a bug in m[blue]CLISPm[][6] or in its documentation (this manual page or CLISP impnotes), please report it to the m[blue]CLISPm[][6] m[blue]SourceForge bug trackerm[][56].

Before submitting a bug report, please take the following basic steps to make the report more useful:

: 1. Please do a clean build (remove your build directory and build m[blue]CLISPm[][6] with ./configure --cbc build or at least do a make distclean before make).

: 2. If you are reporting a "hard crash" (segmentation fault, bus error, core dump etc), please do ./configure --with-debug --cbc build-g ; cd build-g; gdb lisp.run, then load the appropriate linking set by either base or full m[blue]gdbm[][57] command, and report the backtrace (see also Q: A.1.1.10).

: 3. If you are using pre-built binaries and experience a hard crash, the problem is likely to be in the incompatibilities between the platform on which the binary was built and yours; please try compiling the sources and report the problem if it persists.

When submitting a bug report, please specify the following information:

: 1. What is your platform (uname -a on a m[blue]UNIXm[][42] system)? Compiler version? m[blue]GNUm[][8] m[blue]libcm[][58] version (on m[blue]GNUm[][8]/m[blue]Linuxm[][59])?

: 2. Where did you get the sources or binaries? When? (Absolute dates, e.g., "2006-01-17", are preferred over the relative ones, e.g., "2 days ago").