1. Introduction

ECL is an implementation of the Common-Lisp by Giuseppe Attardi's up from the Kyoto Common-Lisp. See 1.1 Credits for the history of the code you are up to use.

ECL (ECL for short) uses standard C calling conventions for Lisp compiled functions, which allows C programs to easily call Lisp functions and vice versa. No foreign function interface is required: data can be exchanged between C and Lisp with no need for conversion.

ECL is based on a Common Runtime Support (CRS) which provides basic facilities for memory management, dynamic loading and dumping of binary images, support for multiple threads of execution. The CRS is built into a library that can be linked with the code of the application. ECL is modular: main modules are the program development tools (top level, debugger, trace, stepper), the compiler, and CLOS. A native implementation of CLOS is available in ECL: one can configure ECL with or without CLOS. A runtime version of ECL can be built with just the modules which are required by the application.

The ECL compiler compiles from Lisp to C, and then invokes the GNU C compiler to produce binaries. While former releases of ECL adhere to the the reference of the language given in [see section Steele:84], the aim of ECL is now to achieve maximum compliance with ANSI Common-Lisp@c, the most up to date standard for Common-Lisp@c.

Throughout this manual we will describe the ECL implementation and how it differs from [see section ANSI] and [see section Steele:84]. In general, as work in ECL is completed section by section, we will drop compatibility with [see section Steele:84] and the corresponding chapter will be updated to document only the differences with [see section ANSI].

1.1 Credits
1.2 Copyright
1.3 Installation		Installing a binary distribution.
1.4 Rebuilding ECL		Building ECL from sources.
1.5 Entering and leaving ECL		Basic skills.

1.1 Credits

The ECL project is an implementation of the Common-Lisp comply with the ANSI Common-Lisp by Giuseppe Attardi's who produced an interpreter and compiler fully conformat with the Common-Lisp as reported in Steele:84. ECL derives itself mostly from Kyoto Common-Lisp@c, an implementation developed at the Research Institute for Mathematical Sciences (RIMS), Kyoto University, with the cooperation of Nippon Data General Corporation. The main developers of Kyoto Common-Lisp Yuasa and Masami Hagiya, of the Research Institute for Mathematical Sciences, at Kyoto University.

I must thank Giuseppe Attardi, Yuasa and Hagiya for their wonderful work with preceding implementations and for putting them in the Public Domain under the GNU General Public License as published by the Free Software Foundation. Without them this product would have never been possible.

This document is an update of the original ECL documentation, which was based in part on the material in [see section Yuasa:85]

The following people or organizations must be credited for support in the development of Kyoto Common-Lisp@c: Prof. Reiji Nakajima at RIMS, Kyoto University; Nippon Data General Corporation; Teruo Yabe; Toshiyasu Harada; Takashi Suzuki; Kibo Kurokawa; Data General Corporation; Richard Gabriel; Daniel Weinreb; Skef Wholey; Carl Hoffman; Naruhiko Kawamura; Takashi Sakuragawa; Akinori Yonezawa; Etsuya Shibayama; Hagiwara Laboratory; Shuji Doshita; Takashi Hattori.

William F. Schelter improved KCL in several areas and developed Austin Kyoto Common-Lisp ECL.

The following is the full list of contributors to ECL: Taiichi Yuasa and Masami Hagiya (KCL), William F. Schelter (Dynamic loader, conservative Gc), Giuseppe Attardi (Top-level, trace, stepper, compiler, CLOS, multithread), Marcus Daniels (Linux port) Cornelis van der Laan (FreeBSD port) David Rudloff (NeXT port) Dan Stanger, Don Cohen, and Brian Spilsbury.

We have to thank for the following pieces of software that have helped in the development of ECL

BRUNO HAIBLE

For the Cltl2-compliance test

PETER VAN EYNDE

For the ANSI-compliance test

SYMBOLIC'S INC.

For the ANSI-compliant LOOP macro.

The ECL project also owes a lot to the people who have tested this program and contributed with suggestions and error messages: Eric Marsden, Hannu Koivisto and Jeff Bowden, and others whose name I may have omitted.

1.2 Copyright

Copyright © 2000 Juan Jose Garcia Ripoll

Copyright © 1990, 1991, 1993 Giuseppe Attardi

Copyright © 1984 Taiichi Yuasa and Masami Hagiya

All Rights Reserved

Summary:

Permission is granted to use, copy, modify this program, EXCEPT that the copyright notice must be reproduced on copies, and credit should be given to the authors where it is due. WE MAKE NO WARRANTY AND ACCEPT NO LIABILITY FOR THIS PROGRAM.

In detail:

1. Permission to use, copy, modify this software and its documentation for any purpose is hereby granted without fee, provided that
   • the above copyright notice appears in all copies,
   • both that copyright notice and this permission notice appears in supporting documentation, and that
   • you cause modified files to carry prominent notices stating that you changed the files and the date of any change.

2. Please notify us if you are going to sell this software or its documentation for profit.

3. WE DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL WE BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Additionally:

ECL is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version; see file 'Copying'.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Address for reporting bugs, comments, suggestions:

worm@arrakis.es

1.3 Installation

*** *** Building of binary distributions has been discontinued. The *** following paragraphs do not apply ***

Usually I build current binaries for the platforms I have access to, and these are placed in

Linux

http://www.arrakis.es/~worm/ecl-linux.tgz

FreeBSD (>= 4.0)

http://www.arrakis.es/~worm/ecl-freebsd.tgz

To install them you need only unpack them on the root directory, and the program will install itself under

/usr/local/bin ecl program /usr/local/lib/ecl libraries and headers /usr/local/man/man1 ecl.1 manual page /usr/local/info ecl.info user guide

The flags which I used to build the program are summarized in `/usr/local/lib/ecl/BUILD-STAMP'. You should check that they correspond to your needs before using ECL --i.e., it could be a too old version, garbage collector might not be the right one or TCP/IP support could have been removed.

1.4 Rebuilding ECL

1. Obtain the distribution from http://ecls.sourceforge.net. The distribution is in a gzip-compressed tar file named like `ecl.tgz'

2. Prepare a directory (hereafter called ECL directory) for ECL. In the following examples, we suppose that the ECL directory is `/usr/local/ecl'.

3. Extract the content from the compressed tar file.

   zcat ecl.tgz | tar xf -

4. An auto configuration mechanism allows you to perform a standard installation with the following commands:

   ./configure

   This example will prepare to install executable files, manual pages and info files in standard directories like `/usr/local/bin', `/usr/local/man/man1', `/usr/local/info'.

5. If you don't have access rights to these directories, you should give to configure alternate places. Try ./configure -help for instructions on how to supply this information to configure, but a good starting point is

   ./configure --prefix=$HOME

6. Make sure everything went OK with the configuration. The configuration script figures out the machine where it is running and creates a directory machine where to perform the installation. If the program fails to recognize the machine, you will have to check whether it is one of the supported machines present in src/h/machine.h.

7. Next you must build the program and install it

   make make install

At the end of installation, the destination directories will contain several files. If you have not modified these directories when invoking `configure' the layout should be

Executable files: /usr/local/bin/ecl the ECL interpreter and compiler Help documents: /usr/local/lib/ecl/help.doc data for the online help /usr/local/man/man1/ecl.1 manual page for ECL /usr/local/info/ecl.info this manual you are reading Library files and headers: /usr/local/lib/ecl/libecl.a the core library in C /usr/local/lib/ecl/libgmp.a GNU library for bignums /usr/local/lib/ecl/libgc.a Boehm-Weiser garbage collector /usr/local/lib/ecl/*.a Other lisp compiled code /usr/local/lib/ecl/h/ Header files

You can remove all intermediate files produced during installation with the command make clean.

1.5 Entering and leaving ECL

% ecl ECL (Embeddable Common-Lisp) 0.0e Copyright (C) 1984 Taiichi Yuasa and Masami Hagiya Copyright (C) 1993 Giuseppe Attardi Copyright (C) 2000 Juan J. Garcia-Ripoll ECL is free software, and you are welcome to redistribute it under certain conditions; see file 'Copyright' for details. Type :h for Help. Top level. >

When invoked, ECL will print the banner and initialize the system. The date in the ECL banner identifies the revision of ECL. Version (0.8) 05/14/1993 is the value of the function lisp-implementation-version.

If there exists a file named `init.lsp' in the current working directory, ECL successively evaluates the forms in the file, immediately after the system initialization. The user may set up his or her own ECL environment (e.g., the memory configuration) with `init.lsp'.

After the initialization, ECL enters the top-level loop and prints the prompt `>'.

Type :h for Help. Top level. >

The prompt indicates that ECL is now ready to receive a form from the terminal and to evaluate it.

Usually, the current package (i.e., the value of *package*) is the user package, and the prompt appears as above. If, however, the current package is other than the user package, then the prompt will be prefixed by the package name.

> (in-package 'cl) #<"COMMON-LISP" package> COMMON-LISP> (in-package 'system) #<"SYSTEM" package> SYSTEM>

To exit from ECL, call the function quit.

>(quit) Bye. %

Alternatively, you may type ^D, i.e. press the key D while pressing down the control key (Ctrl).

>^DBye. %

You can disable ^D as the exit command by setting to T the following variable:

System: *ignore-eof-on-terminal-io*

This variable controls whether an end of file character (normally ^D) should terminate the session. The default value is ()@c.

The top-level loop of ECL is almost the same as that defined in Section 20.2 of [see section Steele:84]. Since the input from the terminal is in line mode, each top-level form should be followed by a newline. If more than one value is returned by the evaluation of the top-level form, the values will be printed successively. If no value is returned, then nothing will be printed.

>(values 1 2) 1 2 >(values) >

When an error is signalled, control will enter the break loop.

>(defun foo (x) (bar x)) foo >(defun bar (y) (bee y y)) bar >(foo 'lish) Error: The function BEE is undefined. Error signalled by BAR. Broken at BAR. >>

`>>' in the last line is the prompt of the break loop. Like in the top-level loop, the prompt will be prefixed by the current package name, if the current package is other than the user package.

To go back to the top-level loop, type :q

>>:q Top level. >

See Section 5.4 for the details of the break loop.

The terminal interrupt (usually caused by typing ^C (Control-C)) is a kind of error. It breaks the running program and calls the break level loop.

Example:

>(defun foo () (do () (nil))) foo >(foo) ^C Correctable error: Console interrupt. Signalled by DO. Broken at FOO. >>