Next: , Previous: , Up: Top   [Contents][Index]

1 User’s guide


Next: , Up: User's guide   [Contents][Index]

1.1 Building ECL

Due to its portable nature ECL works on every (at least) 32-bit architecture which provides a proper C99 compliant compiler.

Operating systems on which ECL is reported to work: Linux, Darwin (Mac OS X), Solaris, FreeBSD, NetBSD, OpenBSD, DragonFly BSD, Windows and Android. On each of them ECL supports native threads.

In the past Juanjo José García-Ripoll maintained test farm which performed ECL tests for each release on number of platforms and architectures. Due to lack of the resources we can’t afford such doing, however each release is tested by volunteers with an excellent package cl-test-grid created and maintained by Anton Vodonosov.

1.1.1 Autoconf based configuration

ECL, like many other FOSS programs, can be built and installed with 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 using Microsoft Visual Studio compilers (however you may build ECL with cygwin or mingw using the autoconf as described here).

To build Embeddable Common Lisp you need to

  1. Extract the source code and enter it’s directory
    $ tar -xf ecl-xx.x.x.tgz
    $ cd ecl-xx.x.x
    
  2. Run the configuration file, build the program and install it
    $ ./configure --prefix=/usr/local
    $ make                          # -jX if you have X cores
    $ make install
    
  3. 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>.
    > 
    

1.1.2 Platform specific instructions

1.1.2.1 MSVC based configuration

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

Next: , Previous: , Up: User's guide   [Contents][Index]

1.2 Entering and leaving Embeddable Common Lisp

Embeddable Common Lisp 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
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.
Top level in: #<process TOP-LEVEL>.
> 

When invoked, Embeddable Common Lisp will print the banner and initialize the system. The number in the Embeddable Common Lisp banner identifies the revision of Embeddable Common Lisp. 0.0e is the value of the function lisp-implementation-version.

Unless user specifies -norc flag when invoking the Embeddable Common Lisp, it will look for the initialization files ~/.ecl and ~/.eclrc. If he wants to load his own file from the current directory, then he should pass the file path to the -load parameter:

% ecl -norc -load init.lisp

After the initialization, Embeddable Common Lisp enters the top-level loop and prints the prompt ‘>’.

Type :h for Help.  Top level.
>

The prompt indicates that Embeddable Common Lisp 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 with the package name.

> (in-package "CL")
#<"COMMON-LISP" package>
COMMON-LISP> (in-package "SYSTEM")
#<"SI" package>
SI>

To exit from Embeddable Common Lisp, call the function quit.

> (quit)
%

Alternatively, you may type ^Dwhile pressing down the control key (Ctrl).

> ^D
%

The top-level loop of Embeddable Common Lisp is almost the same as that defined in Section 20.2 of [see 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)
Condition of type: UNDEFINED-FUNCTION
The function BAR is undefined.

Available restarts:

1. (RESTART-TOPLEVEL) Go back to Top-Level REPL.

Broken at FOO. In: #<process TOP-LEVEL>.
>>

>>’ 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 in: #<process TOP-LEVEL>.
>

If more restarts are present, user may invoke them with by typing :rN, where N is the restart number. For instance to pick the restart number two, type :r2.

See [The break loop] 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
Condition of type: INTERACTIVE-INTERRUPT
Console interrupt.

Available restarts:

1. (CONTINUE) CONTINUE
2. (RESTART-TOPLEVEL) Go back to Top-Level REPL.

Broken at FOO. In: #<process TOP-LEVEL>.
>>

Next: , Previous: , Up: User's guide   [Contents][Index]

1.3 The break loop


Previous: , Up: User's guide   [Contents][Index]

1.4 Embedding ECL


Up: Embedding ECL   [Contents][Index]

1.4.1 Embedding Reference

Macro: CL_CATCH_ALL

Create a protected region.

C Macro

  cl_env_ptr env = ecl_process_env();
  CL_CATCH_ALL_BEGIN(env) {
    /*
     * Code that is protected. Uncaught lisp conditions, THROW,
     * signals such as SIGSEGV and SIGBUS may cause jump to
     * this region.
     */
  } CL_CATCH_ALL_IF_CAUGHT {
    /*
     * If the exception, lisp condition or other control transfer
     * is caught, this code is executed.
     */
  } CL_CATCH_ALL_END
  /*
   * In all cases we exit here.
   */

Description

This is a set of three macros that create an UNWIND-PROTECT region that prevents any nonlocal transfer of control to outer loops. In the Lisp speak, the previous code is equivalent to

(block nil
  (unwind-protect
     (progn
        ;; Code that is protected
	)
    (return nil)))

As explained in CL_UNWIND_PROTECT,it is normally advisable to set up an unwind-protect frame to avoid the embedded lisp code to perform arbitary transfers of control.

See also

CL_UNWIND_PROTECT

Macro: CL_UNWIND_PROTECT

Create a protected region.

C Macro

  cl_env_ptr env = ecl_process_env();
  CL_UNWIND_PROTECT_BEGIN(env) {
    /*
     * Code that is protected. Uncaught lisp conditions, THROW,
     * signals such as SIGSEGV and SIGBUS may cause jump to
     * this region.
     */
  } CL_UNWIND_PROTECT_EXIT {
    /*
     * If the exception, lisp condition or other control transfer
     * is caught, this code is executed. After this code, the
     * process will jump to the original destination of the
     * THROW, GOTO or other control statement that was interrupted.
     */
  } CL_UNWIND_PROTECT_END
  /*
   * We only exit here if NO nonlocal jump was interrupted.
   */

Description

When embedding ECL it is normally advisable to set up an unwind-protect frame to avoid the embedded lisp code to perform arbitary transfers of control. Furthermore, the unwind protect form will be used in at least in the following ocasions:

Besides this, normal mechanisms for exit, such as ext:quit, and uncaught exceptions, such as serious signals (See Signals and Interrupts - Synchronous signals), are best handled using unwind-protect blocks.

See also

CL_CATCH_ALL

Function: int cl_boot (int argc, char **argv);

Setup the lisp environment.

argc,

An integer with the number of arguments to this program.

argv

A vector of strings with the arguments to this program.

Description

This function must be called before any other function from the ECL library, including the creation of any lisp object or evaluating any lisp code. The only exception are ecl_set_option and ecl_get_option.

Function: int cl_shutdown (void);

Close the lisp environment.

Description

This function must be called before exiting a program that uses the ECL environment. It performs some cleaning, including the execution of any finalizers, unloading shared libraries and deleting temporary files that were created by the compiler.

Function: void ecl_set_option (int option, cl_fixnum value);

Set a boot option.

option

An integer from Table 1.1.

value

A cl_index value for this option

Description

This functions sets the value of different options that have to be customized before ECL boots. The table of options and default values [Table 1.1] shows that some of them are boolean, and some of them are unsigned integers.

We distinguish three sets of values. The first set determines whether ECL handles certain exceptions, such as access to forbidden regions of memory, interrupts via , floating point exceptions, etc.

The second set is related to the sizes of different stacks. Currently ECL uses four stacks: a bind stack for keeping assignments to special variables; a frame stack for implementing blocks, tagbodys and catch points; an interpreter stack for evaluating bytecodes, and finally the machine or C stack, of the computer we run in. We can set the expected size of these stacks, together with the size of a safety area which, if penetrated, will lead to the generation of a correctable error.

Name (ECL_OPT_*)TypeDefaultDescription
INCREMENTAL_GCbooleanTRUEActivate generational garbage collector.
TRAP_SIGSEGVbooleanTRUECapture SIGSEGV signals.
TRAP_SIGFPEbooleanTRUECapture floating point exceptions.
TRAP_SIGINTbooleanTRUECapture user interrupts.
TRAP_SIGILLbooleanTRUECapture SIGILL exception.
TRAP_INTERRUPT_SIGNALbooleanTRUECapture the signal that implements mp:interrupt-process.
SIGNAL_HANDLING_THREADbooleanTRUECreate a signal to capture and process asynchronous threads (See Signals and Interrupts - Asynchronous signals).
BOOTEDbooleanTRUE/FALSEHas ECL booted (read only).
BIND_STACK_SIZEcl_index8192Size of stack for binding special variables.
BIND_STACK_SAFETY_AREAcl_index128
FRAME_STACK_SIZEcl_index2048Size of stack for nonlocal jumps.
FRAME_STACK_SAFETY_AREAcl_index128
LISP_STACK_SIZEcl_index32768Size of interpreter stack.
LISP_STACK_SAFETY_AREAcl_index128
C_STACK_SIZEcl_index131072Size of C stack (not exact).
C_STACK_SAFETY_AREAcl_index4192
SIGALTSTACK_SIZEcl_index1If nonzero, run C signal handler in an alternative signal. A small value is automatically incremented.
THREAD_INTERRUPT_SIGNALunsigned int0If nonzero, specify the unix signal which is used to communicate different Lisp threads.

Table 1.1: Boot options for embedded ECL

Function: cl_fixnum ecl_get_option (int option);

Read the value of a boot option.

option

An integer from Table 1.1.

Description

This functions reads the value of different options that have to be customized before ECL boots. The table of options and default values is Table 1.1.

Macro: ecl_clear_interrupts();

Clear all pending signals and exceptions.

Description

This macro clears all pending interrupts.

See also

ecl_disable_interrupts and ecl_enable_interrupts.

Macro: ecl_disable_interrupts();

Postpone handling of signals and exceptions.

Description

This macro sets a thread-local flag indicating that all received signals should be queued for later processing.

See also

ecl_enable_interrupts and ecl_clear_interrupts.

Macro: ecl_enable_interrupts();

Activate handling of signals and exceptions.

Description

This macro sets a thread-local flag indicating that all received signals can be handled. If there are any pending signals, they will be immediately processed.

See also

ecl_disable_interrupts and ecl_clear_interrupts.


Up: Embedding ECL   [Contents][Index]