## Preface

### About this book

This manual is part of the &ECL; software system. It documents deviations of &ECL; from the &ANSI; standard, as well as extensions, daily working process (compiling files, loading sources, creating programs, etc) and the internals of this implementation.

This book is not intended as a source to learn &CommonLisp;. There are other tutorials and textbooks available in the Net which serve this purpose. The homepage of the Association of Lisp Users contains a good list of links of such teaching and learning material.

This book is structured into three parts. We begin with documents all parts of the standard which are left as implementation specific. For instance, precision of floating point numbers, available character sets, actual input/output protocols, etc.

introduces all features which are specific to &ECL; and which lay outside the standard. This includes configuring, building and installing &ECL; multiprocessing capabilities, graphics libraries, interfacing with the operating system, etc.

deals with the internals of the implementation. This part is only intended for experienced programmers that want to learn how &ECL; does its work and wish to extend it, customize it or port it to new architectures. This part of the documentation is the most fragile one and prone to change.

Missing highlights

### What is &ECL;?

&ECL; is an implementation of the Common-Lisp language that was developed by Giuseppe Attardi's up from the Kyoto Common-Lisp. See 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 &Steele84;, the aim of &ECL; is now to achieve maximum compliance with ANSI Common-Lisp, the most up to date standard for Common-Lisp.

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

### Credits

The &ECL; project is an implementation of the Common-Lisp language that aims to comply with the ANSI Common-Lisp standard. The first ECL implementations were developed 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, 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 were Taiichi Yuasa and Masami Hagiya, of the Research Institute for Mathematical Sciences, at Kyoto University.

We must thank Juan Jose Garcia Ripoll, 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 [Yuasa:85, see ]

The following people or organizations must be credited for support in the development of Kyoto Common-Lisp: 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 (AKCL). Many ideas and code from AKCL have been incorporated in &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.

### Copyright

Copyright © 2015 Daniel Kochmański

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:

### Building 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. 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: |
`$HOME/bin/ecl` | the &ECL; interpreter and compiler
Help documents: |
`$HOME/lib/ecl/help.doc` | data for the online help
`$HOME/man/man1/ecl.1` | manual page for &ECL;
`$HOME/info/ecl.info` | this manual you are reading
Library files and headers: |
`$HOME/lib/ecl/libecl.a` | the core library in C
`$HOME/lib/ecl/libgmp.a` | GNU library for bignums
`$HOME/lib/ecl/libgc.a` | Boehm-Weiser garbage collector
`$HOME/lib/ecl/*.a` | Other lisp compiled code
`$HOME/lib/ecl/ecl/` | Header files

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

### Entering and leaving &ECL;

&ECL; is invoked by the command `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 ().

The top-level loop of &ECL; is almost the same as that defined in Section 20.2 of &Steele84;. 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.
       >>