## Preface

### About this book

This manual is part of the &ECL; software system. It documents deviations of &ECL; from various standards (&ANSI;, &AMOP;,...), 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 part.standards which 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.

part.extensions 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.

part.internals 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.

### What is &ECL;?

&CommonLisp; is a general purpose programming language. It lays its roots in the LISP programming language bib.LISP1.5 developed by John McCarthy in the 80s. &CommonLisp; as we know it &ANSI; is the result of an standarization process aimed at unifying the multiple lisp dialects that were born from that language.

&ECL; is an implementation of the Common-Lisp language. As such it derives from the implementation of the same name developed by Giuseppe Attardi, which itself was built using code from the Kyoto Common-Lisp bib.KCL. See preface.history for the history of the code you are about 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;. 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.

### History

#### ECL's family tree

The &ECL; project is an implementation of the Common-Lisp language inherits from many other previous projects, as shown in fig.family-tree. The oldest ancestor is the Kyoto Common Lisp, an implementation developed at the the Research Institute for Mathematical Sciences, Kyoto University bib.KCL. This implementation was developed partially in C and partially in Common Lisp itself and featured a lisp to C translator.

The KCL implementation remained a propietary project for some time. During this time, William F. Schelter improved KCL in several areas and developed Austin Kyoto Common-Lisp (AKCL). However, those changes had to be distributed as patches over the propietary KCL implementation and it was not until much later that both KCL and AKCL became freely available and gave rise to the GNU Common Lisp project, GCL.

Around the 90's, Giusseppe Attardi worked on the KCL and AKCL code basis to produce an implementation of &CommonLisp; that could be embedded in other C programs bib.ECL. The result was an implementation sometimes known as ECL and sometimes as ECoLisp, which achieved rather good compliance to the informal specification of the language in &Steele84;, and which run on a rather big number of platforms.

The &ECL; project stagnated a little bit in the coming years. In particular, certain dependencies such as object binary formats, word sizes and some C quirks made it difficult to port it to new platforms. Furthermore, &ECL; was not compliant with the ANSI specification, a goal that other Common Lisps were struggling to achieve.

This is where the ECLS or ECL-Spain project began. Juanjo García-Ripoll took the ECoLisp sources and worked on them, with some immediate goals in mind: increase portability, make the code 64-bit clean, make it able to build itself from scratch, without other implementation of &CommonLisp; and restore the ability to link &ECL; with other C programs.

Those goals were rather quickly achieved. &ECL; became ported to a number of platforms and with the years also compatibility with the ANSI specification became a more important goal. At some point the fork ECLS, with agreement of Prof. Attardi, took over the original ECL implementation and it became what it is nowadays, a community project.

In 2013 once again project got unmaintained. In 2015 Daniel Kochmański took position of maintainer with consent of Juanjo García-Ripoll.

The &ECL; project owes a lot to different people who have contributed in many different aspects, from pointing out bugs and incompatibilities of &ECL; with other programs and specifications, to actually solving these bugs and porting &ECL; to new platforms.

Current development of &ECL; is still driven by Daniel Kochmański with main focus on improving ANSI compliance and compapibility with &CommonLisp; libraries ecosystem, fixing bugs, improving speed and protability. The project homepage is located at https://common-lisp.net/project/ecl/, and there are pointers to all project resources like mailing list and main repository.

### Copyright of ECL

&ECL; is distributed under the GNU LGPL, which allows for commercial uses of the software. A more precise description is given in the Copyright notice which is shipped with &ECL;.

    ---- BEGINNING OF COPYRIGHT FOR THE ECL CORE ENVIRONMENT ------------

      Copyright (c) 2015, Daniel Kochmański
      Copyright (c) 2000, Juan Jose Garcia Ripoll
      Copyright (c) 1990, 1991, 1993 Giuseppe Attardi
      Copyright (c) 1984 Taiichi Yuasa and Masami Hagiya
    	      All Rights Reserved

      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.

      PLEASE NOTE THAT:

      This license covers all of the ECL program except for the files
    	src/lsp/loop.lsp	; Symbolic's LOOP macro
    	src/lsp/pprint.lsp	; CMUCL's pretty printer
    	src/lsp/format.lsp	; CMUCL's format
      and the directories
    	contrib/		; User contributed extensions
      Look the precise copyright of these extensions in the corresponding
      files.

      Report bugs, comments, suggestions to the ecl mailing list:
      ecls-list@lists.sourceforge.net.

    ---- END OF COPYRIGHT FOR THE ECL CORE ENVIRONMENT ------------------

### Copyright of this manual

Copyright: Daniel Kochmański, 2015.

Copyright: Juan José García-Ripoll, 2006.

Copyright: Kevin M. Rosenberg 2002-2003, (UFFI Reference)

- &ACL; is a registered trademark of Franz Inc.

- &LW; is a registered trademark of Xanalys Inc.

- Microsoft Windows is a registered trademark of Microsoft Inc.

- Other brand or product names are the registered trademarks or trademarks of their respective holders.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is shown below.

       &GFDL;

### Installation

The following sections describe which machines are supported by &ECL;, how to build and install it on them. You should read at least preface.platforms and in particular table.ports which details the other sections containing installation instructions for your platform.

#### Supported platforms

Architecture | Operating system | Toolchain | Tested YES means that a dedicated machine regularly builds and tests &ECL; on this platform.
x86 Intel 32 bit processors (Pentium, Pentium II, Pentium 3, Pentium 4) and AMD clones | Linux | Autoconf | YES
x86_64 AMD and Intel processors with 64 bit extensions. | Linux | Autoconf | YES
PPC | Linux | Autoconf | YES
Itanium | Linux | Autoconf | YES
x86 | FreeBSD | Autoconf | YES
x86 | OpenBSD | Autoconf | YES
x86 | NetBSD | Autoconf | YES
x86 | Windows XP, Vista, 7 | Microsoft compilers | YES
x86 | Windows XP, Vista, 7 | &cygwin; | YES
x86 | Windows XP, Vista, 7, 8 | &mingw; and Msys tools | YES
x86 | OS X Tiger | Autoconf | YES
x86_64 | OS X Tiger | Autoconf | YES
x86 | Solaris | Autoconf | YES
x86_64 | Solaris | Autoconf | YES
Sparc | Solaris | Autoconf | YES

In table.ports we show the operating systems in which ECL is known to run and where it is regularly tested. Note that ECL might successfully build on other platforms, and that porting is relatively easy. We regularly get reports on ECL being built on other platforms (ARM, Motorola 68x, Sparc, etc), so the best thing is to try yourself.

#### Autoconf based configuration

&ECL;, like many other free programs, can be built and installed a GNU tool called Autoconf. This is a set of automatically generated scripts that detect the features of your machine, such as the compiler type, existing libraries, desired installation path, and configures &ECL; accordingly. The following procedure describes how to build &ECL; using this procedure and it applies to all platforms except for the Windows ports.

1. Unpack the tar file

       $ gunzip -c ecl-16.0.0.tgz | tar xf -

2. Choose a directory in which you will install &ECL;. Following the Unix covention we will use `/usr/local`

3. Run the configuration file

       $ cd ecl-16.0.0
            $ ./configure --prefix=/usr/local

   If you are building under Solaris 9 you should replace the last line with

       $ ./configure --enable-slow-config --with-system-gmp=no \
            --prefix=/usr/local

   By now you should have a directory with the name `build` and a bunch of makefiles inside it.

4. Use GNU make to begin building ECL. Normally this amounts to invoking

       $ make

   from the command line.

5. Install the program using

       $ make install

6. Make sure the program is installed and ready to run

       $ /usr/local/bin/ecl
            ECL (Embeddable Common-Lisp) 16.0.0
            Copyright (C) 1984 Taiichi Yuasa and Masami Hagiya
            Copyright (C) 1993 Giuseppe Attardi
            Copyright (C) 2000 Juan J. Garcia-Ripoll
            Copyright (C) 2015 Daniel Kochmanski
            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 in: #<process TOP-LEVEL>.
            >

#### Platform specific instructions

##### Microsoft compilers

If you have a commercial version of Microsoft Visual Studio, the steps are simple:

1. Change to the `msvc` directory.

2. Run `nmake` to build ECL.

3. Run `nmake install prefix=d:\Software\ECL` where the `prefix` is the directory where you want to install ECL.

4. Optionally, if you want to build a self-installing executable, you can install NSIS and run `nmake windows-nsi`.

If you want to build ECL using the free Microsoft Visual Studio Express 2010 or better, you should follow these before building ECL as sketched before:

1. Download and install Microsoft Visual Studio C++ Compiler.

2. Download and install the Windows SDK

3. Open the Windows SDK terminal, which will set up the appropriate paths and environment variables.

##### OpenBSD and NetBSD

Before following the instructions in preface.autoconf you should install the following packages: boehm-gc and gmp-4.1 or better. Another component, libffi will be needed if you want to use the dynamic foreign interface.