Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo


[8612ce]: preface.xmlf Maximize Restore History

Download this file

preface.xmlf    497 lines (421 with data), 20.1 kB

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<book lang="en">
<preface id="preface">

 <section id="preface.words">
  <title>About this book</title>

  <para>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.</para>

  <para>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 <ulink url="http://www.lisp.org">Association of
  Lisp Users</ulink> contains a good list of links of such teaching and
  learning material.</para>

  <para>This book is structured into three parts. We begin with <xref
  linkend="part.standards"/> which documents all parts of the standard which
  are left as <emphasis>implementation specific</emphasis>. For instance,
  precision of floating point numbers, available character sets, actual
  input/output protocols, etc.</para>

  <para><xref linkend="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.</para>

  <para><xref linkend="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.</para>

 <section id="preface.what.is.ecl">
  <title>What is &ECL;?</title>

  <para>&CommonLisp; is a general purpose programming language. It lays its
  roots in the <acronym>LISP</acronym> programming language <xref
  linkend="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.</para>

  <para>&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 <xref
  linkend="bib.KCL"/>. See <xref linkend="preface.history"></xref> for the
  history of the code you are about to use.</para>

  <para>&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.</para>

  <para>&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.</para>

  <para>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.</para>


 <section id="preface.history">

  <para><figure float="1" id="fig.family-tree">
   <title>ECL's family tree</title>
     <imagedata align="center" fileref="figures/hierarchy.png"
		format="PNG" width="300px"/>

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

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

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

  <para>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 <acronym>ANSI</acronym> specification, a
  goal that other Common Lisps were struggling to achieve.</para>

  <para>This is where the <acronym>ECLS</acronym> or
  <acronym>ECL</acronym>-Spain project began. Juanjo Garc&iacute;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.</para>

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

  <para>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.</para>

  <para>Currently, development of &ECL; is still driven by Juanjo
  Garc&iacute;a-Ripoll with the help of Michael Goffioul in the Windows
  port. The project homepage is located at <ulink
  and there is a mailing list where questions, bug reports and other
  discussions may be carried out.</para>

 <section id="Copyright.ECL">
  <title>Copyright of ECL</title>

  <para>&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;.</para>


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


  This license covers all of the ECL program except for the files
	src/lsp/loop2.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
	src/clx/		; portable CLX library from Telent
  Look the precise copyright of these extensions in the corresponding

  Report bugs, comments, suggestions to the ecl mailing list:

---- END OF COPYRIGHT FOR THE ECL CORE ENVIRONMENT ------------------</programlisting>

 <section id="Copyright.Manual">
  <title>Copyright of this manual</title>

  <para>Copyright: Juan Jos&eacute; Garc&iacute;a-Ripoll, 2006.</para>

  <para>Copyright: Kevin M. Rosenberg 2002-2003, (UFFI Reference)</para>

   <listitem><para>&ACL; is a registered trademark of Franz Inc.</para></listitem>
   <listitem><para>&LW; is a registered trademark of Xanalys Inc.</para></listitem>
   <listitem><para><productname>Microsoft Windows</productname> is a registered
   trademark of Microsoft Inc.</para></listitem>
   <listitem><para>Other brand or product names are the registered trademarks
   or trademarks of their respective holders.</para></listitem>

  <para>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.</para>



 <section id="preface.installation">

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

  <section id="preface.platforms">
   <title>Supported platforms</title>

   <table id="table.ports">
    <title>Supported platforms</title>
    <tgroup cols="3">
       <entry>Operating system</entry>
       <entry>Tested<footnote><para>YES means that a dedicated machine regularly builds and tests &ECL; on this platform.</para></footnote></entry>
       <entry>ix86 <footnote id="note.x86"><para>Intel 32 bit processors
       (Pentium, Pentium II, Pentium 3, Pentium 4) and AMD
       <entry><xref linkend="preface.autoconf"/></entry>
       <entry>FreeBSD, OpenBSD</entry>
       <entry><xref linkend="preface.autoconf"/>,
       <xref linkend="preface.bsd"/></entry>
       <entry><xref linkend="preface.autoconf"/>,
       <xref linkend="preface.netbsd"/></entry>
       <entry>Windows 2000, XP</entry>
       <entry>Microsoft Visual C++ compiler</entry>
       <entry><xref linkend="preface.msvc"/></entry>
       <entry>Windows 2000, XP</entry>
       <entry>&cygwin; tools</entry>
       <entry><xref linkend="preface.autoconf"/></entry>
       <entry>Windows 2000, XP</entry>
       <entry>&mingw; and Msys tools</entry>
       <entry><xref linkend="preface.autoconf"/></entry>
       <entry>OS X Tiger</entry>
       <entry><xref linkend="preface.autoconf"/></entry>
       <entry>OS X Tiger</entry>
       <entry><xref linkend="preface.autoconf"/></entry>
       <footnote id="note.x86_64">
	<para>AMD 64 bits and Intel EM64 extensions.</para>
       <entry><xref linkend="preface.autoconf"/></entry>
       <entry><xref linkend="preface.autoconf"/></entry>
   <para>In <xref linkend="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.</para>


  <section id="preface.autoconf">
   <title>Autoconf based configuration</title>

   <para>&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.</para>

     <para>Unpack the tar file</para>
     <screen>$ gunzip -c ecl-0.9i.tgz | tar xf -</screen>
    <step><para>Choose a directory in which you will install &ECL;. Following
    the Unix covention we will use
     <para>Run the configuration file
     <screen>$ cd ecl-0.9i
     $ ./configure --prefix=/usr/local</screen>
     If you are building under Solaris 9 you should replace the last line with
     <screen>$ ./configure --enable-slow-config --with-system-gmp=no \
     By now you should have a directory with the name
     <filename>build</filename> and a bunch of makefiles inside it.</para>
     <para>Use GNU make to begin building ECL. Normally this amounts to
     <screen>$ make</screen>
     from the command line.</para>
     <para>Install the program using
     <screen>$ make install</screen>
     <para>Make sure the program is installed and ready to run
     <screen>$ /usr/local/ecl
     ECL (Embeddable Common-Lisp) 0.9i
     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.  Broken at EVAL.
     &gt; </screen>


  <section id="preface.osdep">
   <title>Platform specific instructions</title>

   <section id="preface.msvc">
    <title>Windows with Visual C++ compiler</title>

    <para>If you have a commercial version of Microsoft Visual Studio, the
    steps are simple:</para>
     <step><para>Change to the <code>msvc</code> directory.</para></step>

     <step><para>Run <code>nmake</code> to build ECL.</para></step>

     <step><para>Run <code>nmake install prefix=d:\Software\ECL</code>
     where the <code>prefix</code> is the directory where you want to install

     <step><para>Optionally, if you want to build a self-installing
     executable, you can install <ulink
     url="http://nsis.sourceforge.net">NSIS</ulink> and run <code>nmake

    <para>If you want to build ECL using the free Microsoft Visual C++ Toolkit
    2003, you should follow these before building ECL:</para>
     <step><para>Download and install <ulink
     url="http://msdn.microsoft.com/visualc/vctoolkit2003/">Microsoft Visual
     C++ Toolkit</ulink>.</para></step>

     <step><para>Download and install the <ulink
     Platform SDK</ulink></para></step>

     <step><para>Download NMAKE and install. There is an old version in
     <ulink url="http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe">
     Microsoft's download page</ulink>.</para></step>

     <step><para>Download and install the .NET Framework SDK. Copy the
     files msvcrt.lib an msvcrtd.lib from this toolkit to the directory where
     the Visual C++ Toolkit keeps it libraries. Afterwards you can uninstall
     the .NET SDK.</para></step>

     <step><para>Make sure that:</para>
      <step><para><code>%PATH%</code> includes the directories <code>bin</code> of
      both the C++ Toolkit, NMAKE and the SDK.</para></step>

      <step><para><code>%INCLUDE%</code> includes the directories
      <code>include</code> of both the C++ Toolkit and the SDK.</para></step>

      <step><para><code>%LIB%</code>includes the directories <code>lib</code> of
      both the C++ Toolkit and the SDK.</para></step>

   <section id="preface.mingw">
    <title>Windows with Mingw/Cygwin</title>


   <section id="preface.netbsd">

    <para>Before following the instructions in <xref
    linkend="preface.autoconf"/> you should install the following packages:
    <application>bash</application>, <application>boehm-gc</application> and
    <application>gmp-4.1</application> or better. Additionally when
    configuring, you should first export the environment variable
    <variable>CONFIG_SHELL</variable> using <code>setenv CONFIG_SHELL
    /usr/pkg/bin/bash</code> or <code>export


   <section id="preface.bsd">
    <title>OpenBSD and FreeBSD</title>

    <para>Before following the instructions in <xref
    linkend="preface.autoconf"/> you should install the following packages:
    <application>boehm-gc</application> and <application>gmp-4.1</application>
    or better.</para>

<!-- Keep this comment at the end of the file
      Local variables:
      mode: nxml
      sgml-parent-document: "ecl.xml"
      sgml-indent-step: 1
      nxml-child-indent: 1
      fill-column: 79