Dump of existing HTML tutorials into docuwiki format by the HTML::WikiConverter::DokuWiki Perl module. Useful for moving things from HTML tutes to the wiki at the SDF wiki. Convert script and source HTML also provided.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

160 lines
6.0 KiB

====== Using ECL (Embeddable Common-Lisp) on SDF ======
==== Contents: ====
* [[#what|What is ECL?]]
* [[#compare|ECL vs CLISP]]
* [[#basics|ECL Basics]]
* [[#oneliners|ECL one-liners]]
* [[#asdf|ASDF]]
* [[#customize|Customizations]]
* [[#refs|References]]
===== What is ECL? =====
ECL stands for //Embeddable Common-Lisp// and is a free open source ANSI Common-Lisp implementation. Its distinguishing attributes are maintaining a small-footprint, and being embeddable with existing C/C++ applications. ECL is LGPL licensed and hosted at [[http://ecls.sourceforge.net/|ecls.sourceforge.net]].
ECL-11.1.1 is currently available to MetaARPA members on most SDF hosts.
===== ECL vs CLISP =====
There are currently two Common-Lisp implementations available on SDF; ECL and CLISP. Both are largely compliant with the ANSI Common-Lisp standard. Each supports various object systems, debugging, bytecode compiling, unicode, sockets, streams, etc. CLISP comes with built-in readline support; ECL doesn't, though it can be added; see the [[#asdf|ASDF]] section. In addition to being smaller and faster than CLISP, ECL can be embedded in C/C++ programs, allow embedded C/C++ code in Lisp programs, and produce stand-alone ELF executables. ECL is also very well documented.
===== ECL Basics =====
By default ECL starts up in interactive mode. Log into SDF host //miku// and type "'ecl'"; you should see something like below:
ECL (Embeddable Common-Lisp) 11.1.1
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.
The default ECL prompt is ">". Enter Common-Lisp commands in the usual way:
> (+ 1 2 3)
> (* 4 5)
> (format t "hello SDF~&")
hello SDF
In-line help is available ; type :h for options. The debugger can be entered using "(break)" ; once entered typed :h to see options. To exit the ECL interactive session type ":exit" .
===== ECL one-liners =====
To use ECL as a script executor (ie. CGI) the //-shell// and/or //-eval// options can be used. The //-norc// is often a good addition so as to avoid unnecessary loading of modules, etc.
ex: hello.lsp
% echo '(format t "~&Hello SDF~&")' > hello.lsp
% ecl -norc -script hello.lsp
Hello SDF
It's also possible to use ECL to execute simple Common-Lisp one-liners at the command line (note that //princ// is needed for screen output):
% ecl -norc -shell /dev/null -eval "(princ (* 1 2 3))"
A nicer way to accomplish the same is to create a small shell script:
# lispit - executes a lisp expression and dumps it to stdout
if [ "$#" -eq 0 ]; then
echo "lispit - executes a lisp expression"
echo " usage: lispit '(lisp_expression)'"
echo ""
exit 1
ecl -norc -shell /dev/null -eval "(princ ${LSP_EXPR} )"
echo ""
exit 0
Example run:
% lispit '(mapcar (lambda (x) (expt x 2)) `(1 2 3 4 5))'
(1 4 9 16 25)
===== ASDF / enabling readline =====
ASDF (//Another System Definition Facility//) is an extensible build facility for Common-Lisp software. ECL comes with ASDF bundled in, however on SDF, users must setup their own ASDF repository under their $HOME directory.
The following outlines the process, using the //ecl-readline// module (adds GNU readline support to ECL) as example:
1) Create the user-level ASDF repository:
% mkdir -p $HOME/LISP/ASDF
2) Create the ASDF config directory and config file*:
% cd $HOME
% mkdir -p .config/common-lisp/source-registry.conf.d
% vi .config/common-lisp/source-registry.conf.d/asdf.conf
# ../asdf.conf
;;additional directory for ASDF to search (no recursion):
(:directory "/LISP/ASDF/")
*note: you can call the conf file anything you want.
3) Download ecl-readline module and copy select files to $HOME/LISP/ASDF:
% cd /tmp
% snarf http://www.common-lisp.net/project/ecl-readline/releases/ecl-readline-0.4.1.tar.gz
% tar xzf ecl-readline-0.4.1.tar.gz
% cd ecl-readline-0.4.1/
% cp ecl-*.* $HOME/LISP/ASDF/
4) Create the ECL startup file:
# $HOME/.eclrc
(require 'asdf)
(asdf:operate 'asdf:load-op 'ecl-readline)
The next time you startup ECL it will compile the ecl-readline module and launch an interactive session. With ecl-readline enabled the default ECL prompt is "//CL-USER[n]>//" and you should then be able to use Emacs-style command editing and history recall. If you don't like the provided prompt you can change it by editing the //ecl-readline.lisp// file.
===== Customizations =====
Additional modifications can be made to the ECL startup file, such as user-defined functions and tweaks to various modules. Below is a more nuanced example which reduces the verbosity at startup, modifies ecl-readline's history file location, and adds an external SHELL function similar to that found in CLISP:
# $HOME/.eclrc
(require 'asdf)
(setf ASDF:*ASDF-VERBOSE* nil) ; quiets ASDF output some
(setf *load-verbose* nil) ; quiets the LOAD process some
(asdf:operate 'asdf:load-op 'ecl-readline)
(ecl-readline::enable :history-file "/var/tmp/.ecl-history")
;; customizations
;; GNU clisp-like SHELL cmd
(defun shell (&optional (shell_cmd "$SHELL"))
"Args: (&optional shell_cmd)
SHELL calls the EXT:SYSTEM function. Executes SHELL_CMD if given, otherwise
User sub-shell is spawned. SHELL_CMD be string or symbol, 256 characters max."
(ext:system shell_cmd))
===== References: =====
* //ecl(1)// and //ecl-config(1)// manpages
* http://ecls.sourceforge.net/
* [[http://common-lisp.net/project/asdf/|http://common-lisp.net/project/asdf]]
* [[http://common-lisp.net/project/ecl-readline/|http://common-lisp.net/project/ecl-readline]]
* [[http://www.cliki.net/Getting%20Started|Getting Started with Common-Lisp]]
$Id: ecl_tutorial.html,v 1.4 2011/12/12 18:10:28 jgw Exp $