Gnu Common Lisp (GCL) has probably been the most commonly-used platform for
ACL2, certainly among non-commercial Lisps. IMPORTANT: Here we are referring
to the non-ANSI version (sometimes called the "CLtL1 version") of GCL. It
is probably impossible to build ACL2 with ANSI GCL as of December 2005, but
recent GCL advances suggest that this may be possible soon.

Macintosh. Robert Krug has provided instructions
for building GCL on Mac OS X, which we include here (very slightly modified, in
part with help from Camm Maguire) in case others find them helpful.

The normal build process for GCL on Mac OS X assumes that
you have installed fink on your Mac. (If you do not know
what this is, don't worry; you probably don't have it or
want it.) Here we give instructions that have worked for
building GCL on OS X without fink.
A. Obtain recent sources (there is a problem, e.g., with
gcl-2.6.7). For example, you can do the following:
export CVSROOT=:pserver:anonymous@cvs.sv.gnu.org:/sources/gcl
cvs -z9 -q co -d gcl-2.6.8pre -r Version_2_6_8pre gcl
At some point you may be able to obtain GCL from
ftp://ftp.gnu/org/, cd gnu, cd gcl, get
gcl-2.6.8.tar.gz, tar xfz gcl-2.6.8.tar.gz)
B. Make sure that /usr/local/bin is in your PATH; if not, run:
PATH="$PATH:/usr/local/bin"
C. cd <gcl directory>
D. You now need to patch file h/powerpc-macosx.defs (this might not be
necessary starting with GCL 2.6.8):
Replace the line:
LIBS := `echo $(LIBS) | sed -e 's/-lncurses/ /'` /sw/lib/libintl.dylib
With:
LIBS := `echo $(LIBS) | sed -e 's/-lncurses/ /'` /usr/local/lib/libintl.dylib
E. Configure and start to build gcl:
./configure
make
F. Install gcl:
sudo make install

Lispworks note. We initially encountered a problem in getting ACL2 to run
under LIspworks 4.2.0. The Lispworks folks provided a patch and suggested that
we make the following announcement.

Users with LispWorks4.2.7 should ask us at lisp-support@xanalys.com
for the transform-if-node patch. It will be helpful if they quote
(Lisp Support Call #11372) when doing so. Also, they must send a bug
form generated from their LispWorks image: instructions at
http://www.lispworks.com/support/bug-report.html.

ACL2 is more than just the executable image. You should obtain the standard
books and a local copy of the documentation. Start here and we will take
you through the whole process of obtaining and installing ACL2.
First, create a directory in which to store ACL2 Version 3.1. We will
call this directory dir. For example, dir might be
/home/jones/acl2/v3-1.

NOTE: If you intend to obtain an incremental release (e.g. 2.9.4 as opposed
to 2.9), please see the ACL2 News for instructions.
Otherwise, continue reading here.

The sources come with a books subdirectory (here
for the latest non-incremental release)
that you may find helpful in your proof development and programming with ACL2.
The following two collections of books are not included with the sources. You
can extract them in the books/ subdirectory of your ACL2
distribution; see the discussion below on certifying
books for information on using them.

For Linux (especially Debian GNU Linux), you can download the Debian package
for Linux. Thanks to Camm Maguire for maintaining this package, and for
pointing out that as Debian packages are simply ar and tar archives, they can
be unpacked on any linux system, and who says: If someone is running Debian,
all they want to do is 'apt-get install acl2', doing likewise for any optional
add-on package they wish as well, e.g. emacs, infix, etc.

You can fetch the above package for a linux
system other than Debian and unpack it as follows. First, connect to the
directory under which you install ACL2 versions and download the
.deb file there. Then submit these commands (changing
"2.9-7" and "i386" as appropriate).

Jared Davis has kindly been providing, typically soon after an ACL2 release, a
Windows installer for ACL2.
The download includes a Unix environment, pre-certified standard and workshop
books, and a copy of Gnu Emacs.

Execute the following four Unix commands. (Note: Gnu tar is
preferred, as there have been some problems with long file names when using tar
provided by SunOS. You may want to use the -i option, "tar xpvfi
acl2.tar", if you have problems with other than Gnu tar. You can see if
you have Gnu tar by running "tar -v".)

For a non-Unix (and non-Linux) system, obtain the sources and place them in
directory dir. The easiest way to do this is to fetch
file http://www.cs.utexas.edu/users/moore/acl2/v3-1/distrib/acl2.tar.gz,
and then extract using an appropriate tar utility. For example,
for Windows systems you may be able to download a utility such as
djtarnt.exe to be used as follows:

djtarnt.exe -x acl2.tar.gz

WARNING: At least one user experienced CR/LF issues when using WinZIP, but we
have received the suggestion that people untarring with that utility should probably
turn off smart cr/lf conversion.

You will find that the ACL2 distribution
contains many files, subdirectories, sub-subdirectories, etc. We mean
for you to copy over to your local connected directory the entire
structure of files and subdirectories. Thus, when you have completed
extracting from acl2.tar.gz, or fetching all files directly
is done, your local connected directory should have a subdirectory
named acl2-sources under which everything resides.

The next step is to create an executable image. The common approach is to
build that image from the sources you have already obtained.
However, you may
be able to take a short cut by downloading an
ACL2 image, in which case you can skip ahead to Summary of
Distribution. Otherwise you should click on one of the links just below.
Choose the last option if you are using a Common Lisp on which you cannot save
an image (e.g., a trial version of Allegro Common Lisp).

PLEASE NOTE: The available memory for ACL2 is determined by the underlying
Common Lisp executable. If you need more memory, refer to your Common Lisp's
instructions for building an executable.

We assume you have obtained ACL2 and placed it in directory dir, as
described above.
If you downloaded a pre-built ACL2 image, you may skip this section.
Connect to dir as above and execute

cd
acl2-sourcesmake LISP=xxx

where xxx is the command to run your local Common Lisp.

By default, if no LISP=xxx is specified,
LISP=gcl is used. On our hosts, gcl is the name of
GNU Common Lisp, which can be obtained as explained above.

This will create executable saved_acl2 in the
acl2-sources directory.

The time taken to carry out this process depends on the host processor but may
be only a few minutes for a fast processor. The size of the resulting binary
image is dependent on which Lisp was used, but it may be in the vicinity of 17
megabytes.

This make works for the Common Lisps listed in Requirements above on Unix and Linux systems we have
tested. See the file acl2-sources/GNUmakefile for further details.
If this make command does not work for you, please see the
instructions for non-Unix/Linux systems below.

Next we describe how to create a suitable binary image containing ACL2. If you
are using a trial version of Allegro Common Lisp, then you may not be
able to save an image. In that case, skip to Running
Without Building an Executable Image.

Your Common Lisp should be one of those listed in
Requirements above. Filenames
below should default to the dir/acl2-sources
directory, e.g., for GCL, connect to
dir/acl2-sources before invoking GCL or, after
entering GCL, do (si::chdir
"dir/acl2-sources/").

Remove file nsaved_acl2 if it exists.

Start up Common Lisp in the acl2-sources directory
and submit the following sequence of commands.

Now exit your Common Lisp and invoke a fresh copy of it (mainly to avoid
saving an image with the garbage created by the compilation process). Again
arrange to connect to the acl2-sources subdirectory. In the
fresh Lisp type:

This will load the new object files in the Lisp image and bootstrap ACL2 by
reading and processing the source files. But the attempt at initialization
will end in an error saying that it is impossible to finish because a certain
file was compiled during the processing, thus dirtying the image yet again.
(If however the attempt ends with an error during compilation of file
TMP1.lisp, see the first troubleshooting tip below.)

So now exit your Common Lisp and invoke a fresh copy of it (again arranging
to connect to your acl2-sources subdirectory). Then, in the
fresh Lisp type:

FIRST get GCL running on your Windows system using ONE of the
following two options. Note that GCL can be unhappy with spaces in filenames,
so you should probably save the GCL distribution to a directory whose path is
free of spaces.

OR, obtain GCL for Windows systems from ftp://ftp.gnu.org/gnu/gcl/
or as explained above. You
may wish to pick a .zip file from the cvs/
subdirectory (containing pre-releases) that has "mingw32" in the
name.

OR ELSE, perhaps you can build GCL on your Windows system from the
sources. The mingw tools and the cygnus bash shell have been used to build
distributed GCL executables.

SECOND, create an appropriate GCL batch file. When we tried running
the script gclm/bin/gclm.bat that came with
gcl-cvs-20021014-mingw32 from the above ftp site, a separate
window popped up, and with an error. Many ACL2 users prefer running in an
emacs shell buffer. (We obtained emacs for Windows from ftp://ftp.gnu.org/gnu/windows/emacs/21.2/emacs-21.2-fullbin-i386.tar.gz.)
The following modification of gclm.bat seemed to solve the problem
(your pathnames may vary).

We hope that the above simply works. If you experience
problems, the following hints may help.

TROUBLESHOOTING:

We tried building ACL2 on Windows XP on
top of GCL, our attempt broke at the end of the "Initialization, first pass" step, while
compiling TMP1.lisp. That was easily remedied by starting up a
fresh GCL session and invoking (compile-file "TMP1.lisp") before
proceeding to the next step.

Yishai Feldman has provided some nice instructions at http://www.faculty.idc.ac.il/yishai/reasoning/win-install.htm,
some of which we have tried to incorporate here. A useful point made there is
that when you want to quit ACL2, use :good-bye (or
(good-bye) which works even in raw Lisp). Or you can use
(user::bye) in raw Lisp. The point is: Avoid control-c
control-d, even thought that often works fine in emacs under
Unix/Linux.

If the above batch file does not work for some reason, an alternate
approach may be to set environment variables. You may be able to add to the
PATH variable gcl-dir\gcc\bin, where
gcl-dir is the directory where GCL is installed. To get to the place to
set environment variables, you might be able to go to the control panel, under
system, under advanced. Alternately, you might be able to get there by opening
My Computer and right-clicking to get to Properties,
then selecting the Advanced tab. At one time, when GCL/Windows
was release as Maxima, Pete Manolios suggested adding the system variable
LD_LIBRARY_PATH with the value "maxima-dir\gcc\i386-mingw32msvc\include"; this
may or may not be necessary for your GCL installation (and the path would of
course likely be different).

We thank Jared Davis for providing the following instructions for Version_2.8,
which we include verbatim and expect apply to future versions.

Building ACL2 on Windows from Scratch
_____________________________________________________________
Note: The disk space requirements are large. Not including
emacs, I had about 275 MB taken up by msys/mingw32/gcl/acl2
during the build process. You can probably use much less
space by removing files after you use them, but I didn't
bother to do that.
Here are the steps I took:
Downloaded emacs 21.3 full distribution and installed
Downloaded msys 1.10.10, installed to c:\acl2
Downloaded mingw 3.1.0-1, installed to c:\acl2\mingw
Downloaded gcl 2.5.3, extracted to c:\acl2\mingw
Downloaded acl2 2.8, extracted to c:\acl2\sources
Compiling gcl:
in msys:
cd /acl2/ming2/gcl-2.5.3
./configure
make
make install
Compiling acl2:
copy "etags.exe" to /mingw/bin. you can find this program
in your emacs folder, under "bin".
in msys:
cd /sources
make
Certifying ACL2 books:
This took 111 minutes on my Athlon 2500+
in msys:
cd /sources
mv nsaved_acl2.gcl.exe saved_acl2.exe
vim books/Makefile-generic, remove "nice" from this line:
ACL2=time nice ../../saved_acl2
make certify-books ACL2=/sources/saved_acl2.exe

The most convenient way to use ACL2 is first to install an executable image as
described above for Unix/Linux and other platforms. However, in some cases this is not
possible, for example if you are using a trial version of Allegro Common Lisp.
In that case you should follow the steps below each time you want to start up
ACL2.

We assume you have obtained ACL2 and placed it in directory dir, as
described above for Unix/Linux or other platforms.
(If you downloaded a pre-built ACL2 image, then you may skip this section.)
Connect to subdirectory acl2-sources of dir,
start up your Common Lisp, and compile by executing the following forms.
This sequence of steps need only be performed once.

(load "init.lisp")
(in-package "ACL2")
(compile-acl2)

Now each time you want to use ACL2, you need only execute the following forms
after starting up Common Lisp in subdirectory acl2-sources of
dir.

(load "init.lisp")
(in-package "ACL2")
(load-acl2)
(initialize-acl2)

Note. The resulting process includes the ACL2 documentation, and hence
will probably be considerably larger (perhaps twice the size) than the result
of running an executable image created as described above.

The distribution includes the following. A list of all files in
acl2-sources may be found in the file all-files.txt
in that directory.

Readme.html; This file
acl2-sources/
LICENSE ; GNU General Public License
GNUmakefile ; For Unix/Linux make.
TAGS ; Handy for looking at source files with emacs
*.lisp ; ACL2 source files
all-files.txt ; List of all files in this directory and subdirectories
books/ ; Examples, potentially useful in others' proofs. See books/Readme.html.
doc/ ; ACL2 documentation in various formats
emacs/ ; Miscellaneous emacs and file utilities, especially emacs-acl2.el
init.lisp; Useful for building the system
interface/
emacs/ ; Support for ACL2 "proof trees". See interface/emacs/README.doc.
infix/ ; ACL2 infix printer by Mike Smith. See interface/infix/README.
saved/ ; Empty directory for backing up copies during make; not important
acl2.tar.gz; gzip'd tar file containing all of acl2-sources/ (see below)
images/ ; Some gzip'd tar'd executables; see images/Readme.html
split/ ; The result of splitting up acl2.tar.gz; see split/Readme.html

The entire acl2.tar.gz is a little more than 6 megabytes, which expands out to nearly
30 megabytes. Additional space is required to build an image, perhaps 30 to 120
megabytes depending on the Lisp, and to certify books.

For those really pressed for space, we note that it is not necessary
to fetch the whole acl2.tar.gz file in order to build
acl2. That file includes more than just the ACL2 sources proper. It
suffices, for building ACL2, via the instructions above, to fetch only
the acl2-sources/*.lisp files, which take up `only' about
5 megabytes, together with the file
acl2-sources/GNUmakefile.

Here we begin with a discussion of how to invoke ACL2
interactively. We then discuss testing as well as the
certification of ACL2 books that come with
the distribution. We conclude with a discussion of the documentation.

When you invoke ACL2, you should see the host Common Lisp
print a header concerning the ACL2 version, license and copyright.

Some hosts then automatically enter the ACL2 ``command loop,'' an ACL2
read-eval-print loop with the prompt:

ACL2 !>

Other hosts will leave you in Common Lisp's read-eval-print loop.
If yours is one of the latter, evaluate the Common Lisp expression
(ACL2::LP) or simply (LP) if the current
package is "ACL2".

Once in the ACL2 command loop, you can type an ACL2 term, typically
followed by ``return'' or ``enter,'' and ACL2 will evaluate the term,
print its value, and prompt you for another one. Below are three
simple interactions:

ACL2 !>t
T
ACL2 !>'abc
ABC
ACL2 !>(+ 2 2)
4

To get out of the ACL2 command loop, type the :q command.
This returns you to the host Common Lisp. We sometimes call this
``raw Lisp.'' You may re-enter the command loop with
(LP) as above.

Note that when you are in raw Lisp you can overwrite or destroy ACL2
by executing inappropriate Common Lisp expressions. All bets are
off once you've exited our loop. That said, many users do it.
For example, you might exit our loop, activate some debugging or trace
features in raw Lisp, and then reenter our loop. While developing
proofs or tracking down problems, this is reasonable behavior.

An easy way to test the theorem prover is to
type the following term to the ACL2 command loop:

:mini-proveall

This will cause a moderately long sequence of commands to be processed, each of
which is first printed out as though you had typed it. Each will print some
text, generally a proof of some conjecture. None should fail.

A more elaborate test is to certify the ``books''
that come with the distribution, which is a good idea anyhow; this is our next
topic. On a Unix/Linux system, you can also certify just a small but useful
subset of the books in a few minutes by executing, in directory
dir/acl2-sources:

The ``books'' that come with the distribution have been contributed mainly by
users and are on the subdirectory acl2-sources/books. See acl2-sources/books/Readme.html
for information. The general topic of books is discussed thoroughly in the
ACL2 documentation; see the BOOKS node in the documentation tree.

Books should be ``certified'' before they are used. We do not distribute
certificates with our books, mainly because certification produces compiled
code specific to the host. You should certify the books locally as a test of
your ACL2 image.

It is easy to re-certify all the distributed books in Unix/Linux. We recommend you
do this. If you have entered ACL2, exit to the operating system, e.g., by
control-d in many systems.

While connected to dir/acl2-sources, execute

make certify-books

This will generate minimal output to the screen and will probably take an hour
or two. Failure is indicated by the presence of **CERTIFICATION FAILED** in the log.

To remove the files thus created, invoke:

make clean-books

The certify-books target does not cause workshop books to be
certified. If you want to certify those books as well, you will first need to
download
the gzipped tar file to the books/ directory, and then gunzip
and extract it. You can certify all the books, including books for the
workshops (including those from the 1999 workshop as described in the
(hardbound) book Computer-Aided
Reasoning: ACL2 Case Studies), using the command:

make regression

By default, certification uses the image
dir/acl2-sources/saved_acl2. You may specify any ACL2
image, as long as it is either a command on your Unix/Linux path or an absolute file
name, for example as follows.

make certify-books ACL2=my-acl2
make regression ACL2=/u/smith/projects/acl2/saved_acl2

We apologize to non-Unix/Linux users: we do not provide non-Unix/Linux
instructions for recertifying the distributed books. The
certification methods provided by the authors of the books vary
greatly and we codified them in the Unix/Linux makefile (GNUmakefile) used above. Most
subdirectories of acl2-sources/books contain either a
README file or a certify.lsp file. Users
who wish to certify one of these books and who cannot figure out (from
these scant clues) what to type to ACL2 should not hesitate to contact
the authors.

ACL2's documentation is a hypertext document that, if printed in book
form, is about 1100 pages or more than 2 megabytes of text. Its
hypertext character makes it far more pleasing to read with an
interactive browser. The documentation is available in four formats:
HTML, Texinfo, Postscript and ACL2 documentation strings. All of this
material is copyrighted by the University of Texas at Austin and is
derived under the GNU General Public License from material copyrighted
by Computational Logic, Inc.

Two Web-based guided tours of ACL2 are available from the home page
noted below. If you are already familiar with Nqthm, you might find
it useful to look at the documentation node
NQTHM-TO-ACL2. Another useful documentation topic for
beginning ACL2 users is the node TUTORIAL.

The home page provides a selected bibliography, a search button (near the top
of the page), guided tours of the system, and the complete hypertext
documentation tree.

Once you have installed ACL2, the HTML form of the documentation is
available locally as
dir/acl2-sources/doc/HTML/acl2-doc.html.

We urge you to browse your local copy of the documentation rather than
our Web copy, simply to reduce Web traffic and the demand on our
server. (Macintosh users using MacOS 9 and earlier may, however, find
filenames being truncated and hence will want to avoid the local
documentation.)

Emacs Info

This is a very convenient format for accessing the ACL2 documentation from
within Emacs. In Emacs, invoke

meta-x info

and then, if you are unfamiliar with Info, type

control-h m

to see a list of commands available. In particular, type

g (dir/acl2-sources/doc/EMACS/acl2-doc-emacs.info)TOP

to enter the ACL2 documentation. Alternatively, your system administrator can
add an ACL2 node to the top-level Info menu. The appropriate entry might read:

Note: The Emacs Info and Postscript versions of our documentation were
created using the file acl2-sources/doc/texinfo.tex which
is copyrighted by the Free Software Foundation, Inc. (See that file
for copyright and license information.)

Users new to emacs may find it helpful to load into emacs the file
dir/acl2-sources/emacs/emacs-acl2.el. Utilities
offered by this file are documented near the top of the file.

Postscript

The Postscript version of the documentation is not included in our normal
distribution because it is so much less useful than the hyper-text versions.
But a gzipped
Postscript (1.2 MB) version is available. It prints as a book of about 1000
pages and contains a Table of Contents and an index to all documented topics.

ACL2 Documentation Strings

The ACL2 system has facilities for browsing the documentation. When you are in
the ACL2 command loop, you may query the documentation on a given topic by
typing the command

:doc topic

where topic is the Lisp symbol naming the topic you want to
learn about. To learn more about the on-line documentation, type
:help and then return.

Note, however, that you may find it more convenient to view the documentation
in a web browser (starting at doc/HTML/acl2-doc.html) or in Emacs
info (starting at doc/EMACS/acl2-doc-emacs.info).

This completes the installation of ACL2 Version 3.1. You may wish to
return to the Table of Contents.

ACL2 supports rational numbers but not real numbers. However, starting
with Version 2.5, a variant of ACL2 called "ACL2(r)" supports the real
numbers by way of non-standard analysis. ACL2(r) was conceived and
first implemented by Ruben Gamboa in his Ph.D. dissertation work,
supervised by Bob Boyer with active participation by Matt Kaufmann.
See the documentation topic REAL for information about this
extension and how to build it, and a warning about its experimental nature.

ACL2 Version 3.1 -- A Computational Logic for Applicative Common Lisp
Copyright (C) 2006 University of Texas at Austin

This version of ACL2 is a descendent of ACL2 Version 1.9, Copyright
(C) 1997 Computational Logic, Inc.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

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 General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.