Commit 13cc9e0e authored by Daniel Kochmański's avatar Daniel Kochmański

new-doc: initial commit

parent bcc8b641
@node Environment implementation
@section Environment implementation
@cppindex cl_env_struct
@deftp {@cind} cl_env_struct
xxx
@end deftp
@node Developer's guide
@chapter Developer's guide
@menu
@c * Sources structure:: Overview of the source code structure
@c * Contributing:: Code, documentation and tests standards
@c * Modules hierarchy::
@c * Testing and benchmarking::
* Manipulating Lisp objects::
* Environment implementation::
@c * The interpreter::
@c * The compiler::
@c * Porting ECL::
@c * Experimental features::
@c * Current roadmap::
@end menu
@include developer-guide/objects.txi
@include developer-guide/environment.txi
@node Manipulating Lisp objects
@section Manipulating Lisp objects
@cppindex cl_lispunion
@deftp {C/C++ index} cl_lispunion cons big ratio SF DF longfloat complex symbol pack hash array vector base_string string stream random readtable pathname bytecodes bclosure cfun cfunfixed cclosure d instance process queue lock rwlock condition_variable semaphore barrier mailbox cblock foreign frame weak sse
Union containing all first-class ECL types.
@end deftp
@node Foreign Function Interface
@section Foreign Function Interface
@menu
* What is a FFI? :: FFI introduciton
@c * Three kinds of FFI :: ECL's FFI brief description
@c * Foreign objects
@c * Higher level interfaces :: Usage examples
@c * SFFI Reference :: Static FFI reference.
@c * DFFI Reference :: Dynamic FFI reference.
* UFFI Reference :: UFFI reference manual.
@end menu
@node What is FFI?
@subsection Three kinds of FFI
A Foreign Function Interface, or FFI for short, is a means for a programming language to
interface with libraries written in other programming languages, the foreign code. You will
see this concept most often being used in interpreted environments, such as Python, Ruby or
Lisp, where one wants to reuse the big number of libraries written in C and C++ for dealing
with graphical interfaces, networking, filesystems, etc.
A FFI is made of at least three components:
@c @table
@c @item Foreign objects management
@c This is the data that the foreign code will use. A FFI needs to provide
@c means to build and manipulate foreign data, with automatic conversions
@c to and from lisp data types whenever possible, and it also has to deal
@c with issues like garbage collection and finalization.
@c @item Foreign code loader
@c To actually use a foreign routine, the code must reside in memory. The
@c process of loading this code and finding out the addresses of the
@c routines we want to use is normally done by an independent component.
@c @item Foreign function invocation
@c This is the part of the FFI that deals with actually calling the foreign
@c routines we want to use. For that one typically has to tell the FFI what
@c are the arguments that these routines expect, what are the calling
@c conventions and where are these routines to be found.
@c @end table
On top of these components sits a higher level interface written entirely in lisp, with which
you will actually declare and use foreign variables, functions and libraries. In the following
sections we describe both the details of the low-level components (Section 3.2, Section 3.3),
and of the higher level interface (Section 3.4). It is highly recommended that you read all
sections.
@include extensions/ffi_uffi.txi
@node UFFI Reference
@subsection UFFI Reference
@menu
@c * Primitive Types
@c * Aggregate Types
@c * Objects
@c * Strings
@c * Functions and Libraries
@end menu
@node Gray streams
@section Gray streams
@defun{close} {@var{stream} @keys{} :abort}
If @var{stream} isn't a stream close will ``let to specialize
itself''. This decision ahs been taken mainly for the compatibility
reasons with some libraries.
@end defun
@node Extensions
@chapter Extensions
@menu
* System building::
* Operating System Interface::
* Foreign Function Interface::
* Multithreading::
* Signals and Interrupts::
@c Networking::
* Memory Management::
* Meta-Object Protocol (MOP)::
@c * Green Threads::
@c * Continuations::
@c * Extensible Sequences::
* Gray Streams::
@c * Series::
* Tree walker::
@c * Local package nicknames::
* CDR Extensions::
@end menu
@node System building
@section System building
@node Operating System Interface
@section Operating System Interface
@include extensions/ffi.txi
@node Multithreading
@section Multithreading
@node Signals and Interrupts
@section Signals and Interrupts
@node Memory Management
@section Memory Management
@node Meta-Object Protocol (MOP)
@section Meta-Object Protocol (MOP)
@c @node Green Threads
@c @section Green Threads
@c @node Continuations
@c @section Continuations
@c @node Extensible Sequences
@c @section Extensible Sequences
@node Gray Streams
@section Gray Streams
@c @node Series
@c @section Series
@node Tree walker
@section Tree walker
@c @node Local package nicknames
@c @section Local package nicknames
@node CDR Extensions
@section CDR Extensions
This source diff could not be displayed because it is too large. You can view the blob instead.
This diff is collapsed.
@node Indexes
@unnumbered Indexes
@menu
* Concept index::
* Function index::
* Variable index::
* Type index::
* Common Lisp symbols::
* C/C++ index::
@end menu
@node Concept index
@section Concept index
@printindex cp
@node Function index
@section Function index
@printindex fn
@node Variable index
@section Variable index
@printindex vr
@node Type index
@section Type index
@printindex tp
@node Common Lisp symbols
@section Common Lisp symbols
@printindex lsp
@node C/C++ index
@section C/C++ index
@printindex cpp
@node What is ECL
@section What is ECL
@clisp{} is a general purpose programming language. It lays its roots in
the @acronym{LISP} programming language @bibcite{LISP1.5} developed by
John McCarthy in the 80s. @clisp{} 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 @clisp{} 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
@bibcite{Yasa:85}. @ref{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 C
compiler to produce binaries. Additionally portable bytecode compiler is
provided for machines which doesn't have C compiler. While former
releases of ECL adhere to the the reference of the language given in
@cltl2{} @bibcite{Steele90}, the ECL is now compliant with X3J13 ANSI
Common Lisp @bibcite{ANSI}.
@node Copyrights
@section Copyrights
@subsection 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.
@verbatim
---- 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/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
examples/ ; Examples for the ECL usage
src/clx/ ; portable CLX library from Telent
Look the precise copyright of these extensions in the corresponding
files.
Examples are licensed under: (SPDX-License-Identifier) BSD-2-Clause
Report bugs, comments, suggestions to the ecl mailing list:
ecl-devel@common-lisp.net.
---- END OF COPYRIGHT FOR THE ECL CORE ENVIRONMENT ------------------
@end verbatim
@subsection Copyright of this manual
@itemize Copyright
@item
Daniel Kochmański, 2016
@item
Juan José García-Ripoll, 2006
@item
Kevin M. Rosenberg, 2002-2003 (UFFI Reference)
@end itemize
@itemize Trademark
@item
AllegroCL is a registered trademark of Franz Inc.
@item
Lispworks is a registered trademark of Xanalys Inc.
@item
Microsoft Windows is a registered trademark of Microsoft Inc.
@item
Other brand or product names are the registered trademarks or trademarks
of their respective holders.
@end itemize
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 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. Exact text of the license is available at
@uref{https://www.gnu.org/copyleft/fdl.html}.
@node Credits
@section Credits
The @ecl{} project is an implementation of the @clisp{} language that
aims to comply with the @ansi{} 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
@cite{Steele:84}. ECL derives itself mostly from Kyoto @clisp{}, 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 @clisp{} were Taiichi
Yuasa and Masami Hagiya, of the Research Institute for Mathematical
Sciences, at Kyoto University.
We must thank Giuseppe Attardi, Yuasa and Hagiya and Juan Jose Garcia
Ripoll 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 @bibcite{Yuasa:85}
The following people or organizations must be credited for support in
the development of Kyoto @clisp{}: 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 @clisp{} (AKCL). Many ideas and code from AKCL have been
incorporated in @ecl{}.
The following is the partial 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{}
@table @sc
@item Bruno Haible
For the Cltl2-compliance test
@item Peter Van Eynde
For the ANSI-compliance test
@item Symbolic's Inc.
For the ANSI-compliant LOOP macro.
@end table
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 we may
have omitted.
@node History
@section History
The ECL project is an implementation of the Common Lisp language
inherits from many other previous projects, as shown in
@ref{fig:hierarchy}. The oldest ancestor is the Kyoto Common Lisp, an
implementation developed at the the Research Institute for Mathematical
Sciences, Kyoto University @bibcite{Yasa:85}. This implementation was
developed partially in C and partially in Common Lisp itself and
featured a lisp to C translator.
@float Figure,fig:hierarchy
@caption{ECL's family tree}
@image{figures/kcl-hierarchy,,,png}
@end float
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 Common Lisp that could be embedded in
other C programs @bibcite{Attardi:95}. 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 CLTL2
@bibcite{Steele:90}, 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 Common
Lisp 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 compatibility with the
Common Lisp libraries ecosystem, fixing bugs, improving speed and the
portability. The project homepage is located at
@uref{https://common-lisp.net/project/ecl/}.
@node Introduction
@unnumbered Introduction
@menu
* What is ECL::
* History::
* Credits::
* Copyrights::
* Sandbox::
@end menu
@include introduction/about_ecl.txi
@include introduction/history.txi
@include introduction/credits.txi
@include introduction/copyrights.txi
@node Sandbox
@section Sandbox
@defun funkcja arg1 arg2 arg3
This is my defun
@end defun
@lspindex *ignore-eof-on-terminal-io*
@defvr {System} {*ignore-eof-on-terminal-io*}
This variable controls whether an end of file character (normally
@myctrl{D}) should terminate the session. The default value is @nil{}.
@end defvr
@macro myctrl {a}
^\a\@c
@end macro
@c @rmacro mopt {a}
@c [\a\]@c
@c @end rmacro
@macro mchoice {a}
<\a\>@c
@end macro
@c @rmacro mstar {a}
@c @{\a\@}*@c
@c @end rmacro
@c @rmacro mplus {a}
@c @{\a\@}+@c
@c @end rmacro
@c @rmacro mgroup {a}
@c @{\a\@},@c
@c @end rmacro
@macro kwd{a}
@var{:\a\}@c
@end macro
@macro pxlref{a}
\a\@c
@end macro
@macro defec{a}
@defun \a\
@end macro
@macro aux
&aux@c
@end macro
@macro keys
&key@c
@end macro
@macro rest
&rest@c
@end macro
@macro optional
&optional@c
@end macro
@macro allow
&allow-other-keys@c
@end macro
@macro macref{foo}
\foo\@c
@end macro
@macro tindexed{foo}
\foo\@c
@end macro
@macro cindexed{foo}
\foo\@c
@end macro
@macro vindexed{foo}
\foo\@c
@end macro
@ifhtml
@macro bibcite{foo}
[@pxref{Bibliography, \foo\}]
@end macro
@end ifhtml
@ifnothtml
@macro bibcite{foo}
[\foo\, @pxref{Bibliography}]
@end macro
@end ifnothtml
@macro back
\\
@end macro
@macro nil
()
@end macro
@macro true
@var{T}
@end macro
@macro ansi
@r{ANSI Common-Lisp}
@end macro
@macro ecl
@b{@r{Embeddable Common-Lisp}}
@end macro
@macro clisp
@r{Common-Lisp}
@end macro
@macro llisp
@b{@r{Lisp}}
@end macro
@macro cltl
@emph{@clisp{}: The Language}
@end macro
@macro cltl2
@emph{@clisp{}: The Language II}
@end macro
@c --- TAGS --- @
@macro cind
C/C++ identifier
@end macro
@macro lind
Common Lisp symbol
@end macro
@macro ocl
@emph{Only in Common Lisp}
@end macro
@c --- Helpers --- @
@macro clhs{end,name}
@url{http://www.lispworks.com/documentation/HyperSpec/Body/\end\,,\name\}
@end macro
@macro ansidict{left,right}
@item
\left\
@tab \right\
@end macro
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename ecldoc.info
@settitle ECL User's Guide
@setchapternewpage odd
@paragraphindent none
@defindex cpp
@defindex lsp
@c %**end of header
@c Entries for @command{install-info} to use
@dircategory Lisp Programming
@direntry
* ecl: (ecl). Embeddable Common Lisp (ECL) User's Manual
@end direntry
@include macros.txi
@ifinfo
@ecl{} is an implementation of @clisp{} designed for being
@emph{embeddable} into C based applications.
@noindent
Copyright @copyright{} 2015, Daniel Kochmański
@noindent
Copyright @copyright{} 2000, Juan Jose Garcia-Ripoll
@noindent
Copyright @copyright{} 1990, Giuseppe Attardi
@end ifinfo
@titlepage
@title ECL User's Guide
@author Giuseppe Attardi
@author Juan Jose Garcia Ripoll (revised version)
@author Daniel Kochmański (revised revised version)
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, Giuseppe Attardi
Copyright @copyright{} 2000, Juan Jose Garcia Ripoll
Copyright @copyright{} 2015, Daniel Kochmański
@end titlepage
@contents
@c ************************ TOP NODE **************************
@ifnottex
@node Top
@top Top
@end ifnottex
@iftex
@page
@titlefont{Preface}
@vskip 1cm
@end iftex
@ecl{} is an implementation of @clisp{} originally designed for being
@emph{embeddable} into C based applications. This document describes
the @ecl{} implementation and how it differs from @bibcite{ANSI} and
@bibcite{Steele:84}. @ref{Developer's guide} and @ref{User's guide} for
the details about the implementation and how to interface with other
languages.
@menu
* Introduction:: What @ecl{} is
* User's guide:: Guide for the programmers using ECL
* Developer's guide:: Guide for the ECL developers
* Standards:: Deviations and clarifications of the standard
* Extensions:: ECL-specific features and extensions
* Indexes:: Concepts, functions, variables, types and C/C++
* Bibliography:: Some interesting books.
@c * List of Figures::
@c * List of Tables::
@end menu
@include introduction/index.txi
@include user-guide/index.txi
@include developer-guide/index.txi
@include standards/index.txi
@include extensions/index.txi
@include indexes/index.txi
@node Bibliography
@unnumbered Bibliography
@table @b
@item ANSI
ANSI @clisp{} Specification, 1986.
@item AMOP
Gregor Kickzales et al. ``The Art of the Metaobject Protocol'' The
M.I.T. Press, Massachussets Institute of Technology, 1999
@item LISP1.5
John McCarthy et al. ``Lisp 1.5 Programmer's Manual 2nd ed'' The
M.I.T. Press, Massachussets Institute of Technology, 1985
@item Steele:84
Guy L. Steele Jr. et al. ``Common Lisp: the Language'',
Digital Press, 1984.
@item Steele:90
Guy L. Steele Jr. at al. ``Common Lisp: the Language II'', second edition,
Digital Press, 1990.
@item Yasa:85
Taiichi Yuasa and Masami Hagiya ``Kyoto @clisp{} Report'',
Research Institute for Mathematical Sciences, Kyoto University, 1988.
@item Attardi:95
Giusseppe Attardi ``Embeddable @clisp{}'', ACM Lisp Pointers, 8(1),
30-41, 1995
@item Smith:84
B.C. Smith and J. des Rivieres ``The Implementation of
Procedurally Reflective Languages'', @emph{Proc. of the 1984 ACM
Symposium on LISP and Functional Programming}, 1984.
@end table
@bye
@c * Input and output:: Accessing files with ECL.
@c * Memory management:: Bits and bytes of every object.
@c * Program development:: Tracing, steppping, error handling, etc.
@c * The interpreter:: The guts behind ECL.
@c * The compiler:: When you need speed@dots{}
@c * Declarations:: Helping the compiler
@c * OS interface:: Operating system interface.
@c * Macros:: Implementation dependent features of macros.
@c * CLOS:: Common-Lisp's Object System.
@c * Multithread:: Lisp lightweight processes or threads.
@c * Bibliography:: Some interesting books.
@node Evaluation and compilation
@section Evaluation and compilation
@menu
* Compiler declaration @code{OPTIMIZE}::
* C Reference (Evaluation and compilation)::
* ANSI Dictionary (Evaluation and compilation)::
@end menu
@node Compiler declaration @code{OPTIMIZE}