Copyright (C) 2022-2025 Andrea Monaco

Copying and distribution of this file, with or without modification, are
permitted in any medium without royalty provided the copyright notice and this
notice are preserved.  This file is offered as-is, without any warranty.




al is a lisp implementation.  Right now it is just an interpreter, but I will
add some compilation later.  I aim for Common Lisp conformance, but I'm not
religious about it.

It's written in C89 and it also compiles with the -ansi option of gcc.

Currently it depends on GNU Readline (optionally) and on GNU Multiple Precision
Arithmetic Library.  It uses autotools for building.



__Building and installing__

If you have a cloned git repository and the latest commit is not a versioned
release, you can execute set-version-from-git.sh to set a meaningful alisp
version in the relevant line of configure.ac.

To build from a git snapshot, start with

  $ autoreconf -i

(which is not needed in released tarballs) and then run the usual

  $ ./configure

configure admits --with[out]-readline as an option, to build with line editing
or not; also note that the test suite will not work without readline, because
the script is written around readline's unusual echo behavior.

configure will also accept the option AL_MODULE_PATH containing a
slash-terminated path where al will look for cl.lisp and for modules like ASDF.

If you don't set AL_MODULE_PATH, you'll get a build that looks in the current
directory and so runs fine from the source tree; if you want a true installation
then set the variable, if your installation prefix is "/usr/local", I'd suggest
setting it to "/usr/local/lib/alisp/" like this

  $ ./configure AL_MODULE_PATH=/usr/local/lib/alisp/

(remember the trailing slash!) Then

  $ make

will build the program and

  $ make install

will install it if you have write permissions on the target directories.

A lisp file named cl.lisp contains many standard definitions.  By default, this
file gets loaded at startup, unless you pass -q or --dont-load-cl.  To load the
file manually, run

  [CL-USER]> (load "cl.lisp")

at the al prompt.


There's a test script too.  Run it with

  $ ./test.pl

if you have perl on your machine.  You should expect a 100% success rate, or
maybe some failures at floating-point operations if they yield slightly
different results on your system.

There's another test script called meta_test.pl that runs test.pl many times.  I
wrote that script because I found that some memory bugs manifest only a fraction
of the times.



__Debugging the C core__

The file al_gdb_debug.py defines a gdb command called al_print_object.  You may
load it with "source al_gdb_debug.py" in your gdb session.

Then the gdb command al_print_object takes a pointer to a struct object as
argument and displays the corresponding lisp object.  A string may be displayed
like this

  (gdb) al_print_object obj
  "abc"
   1(0)

below the string you see the strong refcount and (in parenthesis) the weak
refcount of the object.

A list will be printed like this

  (        A         B         C)
   1(0) 1(0) 1(0) 1(0) 1(0) 1(0)

For each cons cell, the command displays the refcounts of the cell and then
those of the car.

Currently the command doesn't descend into arrays nor hash tables.



__Readline history__

al saves immediately each line to the history file, instead of saving the whole
history at program termination.  That's a design choice, so that I have the last
lines available after crashes.

The history file al_history can get quite big; if you delete it, test.pl and
meta_test.pl will get much faster.




See the NOTES file for some notes on design choices, portability and ANSI
conformance.




You can reach me at andrea.monaco@autistici.org.  Send any suggestion and bug
report that you wish, but please note that I don't take patches.



If you like this project, you can make a donation at
https://liberapay.com/andreamonaco or at https://www.patreon.com/andreamonaco.
Thank you very much!
