ACL2 Version 2.5 Installation Guide

Table of Contents



REQUIREMENTS

ACL2 Version 2.5 Copyright (C) 2000 University of Texas at Austin. ACL2 is licensed under the terms of the GNU General Public License. See below for details.

ACL2 works on the Unix (and some variants, including Linux), Macintosh, and Windows 98 operating systems. It is built on top of any of the following Common Lisps: Allegro, GCL (Gnu Common Lisp) [or, AKCL], Lispworks, Lucid, and MCL (Macintosh Common Lisp). Support for Windows 98 is relatively new, and has undergone only minimal testing with Allegro Common Lisp. So, we would appreciate any feedback if there are problems. We expect that ACL2 may run on other Microsoft Windows operating systems using Common Lisp implementations other than Allegro, but we have not made such a try; please let us know if you try ACL2 on such platforms.

(Old remark, potentially obsolete for most users:) We have successfully run a small but nontrivial test suite on a Sparc 2 with 16 megabytes of main memory, but performance appears better with more memory. For more on this, see Problems.


OBTAINING AND INSTALLING ACL2

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.

Essential Steps



Short Cut: Solaris 7 Sparc running GNU Common Lisp

We assume you have set up dir and carried out the other essential steps.

Short Cut: Debian GNU/Linux running GNU Common Lisp

We assume you have set up dir and carried out the other essential steps.

Building an Executable Image on a Unix System

We assume you have set up dir and carried out the other essential steps. If you downloaded a Solaris 7 Sparc GCL image or Debian GNU/Linux GCL image, you may skip this section. Otherwise, connect to dir as above and execute

cd acl2-sources
make 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. You can fetch GCL without fee from ftp://prep.ai.mit.edu/pub/gnu/gcl/ or from mirror sites listed at http://www.gnu.org/order/ftp.html.
Linux notes. We have successfully built ACL2 under Debian Gnu Linux with GCL 2.3, and have been told by GCL author Bill Schelter that GCL 2.3.6 works with Redhat 6.1 and 6.2. One user has found GCL 2.3 (as opposed to 2.3.6) satisfactory with Redhat 6.1, while another experienced rare problems with Redhat 6.2 using GCL 2.3 that went away with GCL 2.3.6.

The time taken to carry out this process depends on the host processor but may be only several minutes for a fast processor (by June 2000 standards). 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. It may only work on Sun Sparcs and 486/66 PCs, for all we know about the portability of Unix Makefile code. See the file acl2-sources/Makefile for further details. If this make command does not work for you, please see the instructions for non-Unix systems below.

You can now skip to Using ACL2.



Building an Executable Image on a Non-Unix System

Create a subdirectory of dir named acl2-sources.

Open an ftp connection to ftp.cs.utexas.edu by anonymous login and ftp to the local acl2-sources subdirectory all of the files and directories in and below the ftp directory pub/moore/acl2/v2-5/acl2-sources. You may link to our ftp sources directory by clicking here.

You will find that pub/moore/acl2/v2-5/acl2-sources 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 this ftp operation is done, your local connected directory should have a subdirectory named acl2-sources and it should contain (at some level) everything obtained by the ftp. Your local acl2-sources subdirectory will now look exactly as though you had obtained our acl2.tar.gz and done the gunzip, tar and rm steps of the Unix instructions.

Next we describe how to create a suitable binary image containing ACL2. This takes some time and you are urged first to find out (perhaps from a local Common Lisp authority) how to save the resulting image so that it does not have to be constructed from scratch each time you wish to use ACL2. The time taken to carry out the initialization process depends on the host processor but may be an hour or two. The size of the resulting binary image is dependent on which Lisp was used, but it may be in the vicinity of 17 megabytes. See the file mcl-acl2-startup.lisp for Macintosh directions.

Invoke your local Common Lisp, which should be one of those listed in Requirements above. Filenames in this Lisp session 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/").

Now skip to "Building ACL2 under Windows 98" below for instructions for building ACL2 on Windows-based systems. Otherwise, read on.

Then type the following sequence of Lisp commands, 

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

The commands above will compile the ACL2 sources and create compiled object files on your acl2-sources subdirectory. 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: 

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

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! The message will say that it is impossible to finish because a certain file was compiled during the processing, thus dirtying the image yet again. 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: 

(load "acl2.lisp")   ; (load "acl2-init.lisp") ; if to use our save
(in-package "ACL2")
(quick-compile-acl2 t t)
(initialize-acl2)

This will load the new object files into the Lisp image, and bootstrap ACL2 by reading and processing the source files. This run will succeed and leave you at the top level of your Lisp.

If you were to invoke (LP) now, you will enter the ACL2 command loop as discussed in Invoking ACL2. However, we recommend that instead of doing this you save the current image to an executable file using whatever save mechanism exist in your Common Lisp. For consistency with these installation instructions, we suggest you save the binary image to the file named dir/acl2-sources/saved_acl2. The function save-acl2 in file acl2-init.lisp shows how we save an image in various Common Lisps.

You may now proceed to Using ACL2.


Building ACL2 under Windows 98

Here are detailed instructions for building an ACL2 image on a computer running the Microsoft Windows 98 operating system, using Allegro Common Lisp. These instructions might work for other Windows-based systems and other Common Lisps; if you experiment with any of these, please let us know how it goes.

  1. Remove file nsaved_acl2 if it exists.

  2. Start up Common Lisp in the acl2-sources directory and submit the following sequence of commands. 
      (load "acl2.lisp")
  (in-package "ACL2")
  (compile-acl2)
    The commands above will compile the ACL2 sources and create compiled object files on your acl2-sources subdirectory.

  3. 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: 
      (load "init.lsp")
  (in-package "ACL2")
  (load-acl2)
  (initialize-acl2 (quote include-book) *acl2-pass-2-files* t t)
    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! The message will say that it is impossible to finish because a certain file was compiled during the processing, thus dirtying the image yet again.

  4. 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: 
      (load "init.lsp")
  (in-package "ACL2")
  (save-acl2 (quote (initialize-acl2 (quote include-book) *acl2-pass-2-files* t))
             "saved_acl2")
    You have now saved an image. Exit Lisp now. Subsequent steps will put the image in the right place.

  5. Remove osaved_acl2 if it exists.

  6. IF saved_acl2 and saved_acl2.dxl both exist THEN: ELSE IF saved_acl2 exists THEN:

  7. Move nsaved_acl2 to saved_acl2.

  8. For Allegro 5.0 and later, nsaved_acl2.dxl should exist; move it to saved_acl2.dxl

  9. Make sure saved_acl2 is executable.


Summary of Distribution

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
  Makefile ; For Unix make.  See README.
  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, not well documented
  init.lsp ; 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)
acl2.tar.gz.SUM ; result of our running sum acl2.tar.gz
images/    ; Some gzip'd tar'd executables; see images/README.
split/     ; The result of splitting up acl2.tar.gz; see split/README

The entire acl2.tar.gz is roughly 6.5 megabytes, which expands out to roughly 22 megabytes. Additional space is required to build an image, perhaps 17 megabytes (though this depends on the Lisp), and to certify books.


Saving Space

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 files acl2-sources/Makefile and acl2-sources/init.lsp.

USING ACL2

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.

Invoking ACL2

At this point, dir has a subdirectory called acl2-sources. The sources and an executable image are located on that subdirectory. The executable image is called acl2-sources/saved_acl2. You can invoke ACL2 by running that image, e.g.,

mycomputer% dir/acl2-sources/saved_acl2

To make it easy to invoke ACL2 by typing a short command, e.g.,

mycomputer% acl2

you may want to install an executable file on your path, e.g., /usr/local/bin/acl2, containing the following two lines:

#!/bin/csh -f
dir/acl2-sources/saved_acl2


Note: A carriage return in the file after the last line above is important!

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.

Now you are ready to test your image.


Testing ACL2

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.


Certifying ACL2 Books

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. 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. To remove the files thus created, invoke: 
make clean-books

The command make certify-books has been constructed so that it will certify the books that you are most likely to want to use in your work (with the ACL2 form include-book). However, you can certify all the books, including books for the case studies described in the (hardbound) book Computer-Aided Reasoning: ACL2 Case Studies, using the command: 

make certify-books-all

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 path or an absolute file name, for example as follows. 

make certify-books ACL2=my-acl2

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

We apologize to non-Unix users: we do not provide non-Unix 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 Makefile 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.

Next proceed to the section on Documentation.


Documentation

ACL2's documentation is a hypertext document that, if printed in book form, is about 800 pages or about 1.5 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.

HTML

The ACL2 Home Page is

http://www.cs.utexas.edu/users/moore/acl2/index.html

The home page provides a selected bibliography, 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.

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:

* ACL2 i.j: (dir/acl2-sources/doc/EMACS/acl2-doc-emacs).
          Documentation for ACL2 version i.j.

If you are using Lucid Emacs instead of Gnu Emacs, you will find it more aesthetic to use

dir/acl2-sources/doc/LEMACS/acl2-doc-lemacs.info

instead of

dir/acl2-sources/doc/EMACS/acl2-doc-emacs.info.

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

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 (1MB) version is available. It prints as a book of almost 900 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. However this requires that the documentation be stored as strings in the Lisp image. To save space, the images mentioned so far in this document do not contain resident documentation strings. To build such an image on a Unix system, invoke

make large LISP=xxx

while connected to the acl2-sources directory. The xxx above should be replaced by the name of 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.) This will create dir/acl2-sources/saved_acl2 (note that this is the same name previously used for the image without documentation strings). The new image may be 30 megabytes in size and take several minutes to build on a fast (in June 2000) machine. For non-Unix systems, the ``large'' image can be built in your local Common Lisp by 

(load "acl2.lisp")
(in-package "ACL2")
(compile-acl2 nil)
(load-acl2 nil)
(initialize-acl2 'include-book *acl2-pass-2-files* nil)
Non-Unix users should then save the image to an executable binary file.

Once you have an image of ACL2 containing documentation strings, and 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.

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


MISCELLANEOUS INFORMATION

Please let us know if there is other information that you would find of use in this guide.

Problems

If you have difficulties with ftp time outs after establishing an ftp connection, please try logging in again using a dash (-) as the first character of your password -- this will turn off the continuation messages that may be confusing your ftp client. If that doesn't solve your problems, and you have encountered problems ftping the long file acl2.tar.gz because your get times out, an alternative is to get all of the many files in the directory split/, each of which matches the pattern split-acl2.tar.gz* (e.g., using an `mget' command). Once you have got all these files, concatenate them together in alphabetic order, e.g., with the command 
cat split-acl2.tar.gz* > acl2.tar.gz

If you are using Version 3.2.0 of Lispworks, there is probably a bug in the definition of logeqv. Harlequin has sent us a patch; if anyone asks us for it, we will ask Harlequin if we may forward their patch.

If you are running on GCL or AKCL on a machine with only 16 megabytes of RAM, it may be a good idea to have a file ~/acl2-init.lsp containing the following form, which will help to keep the ACL2 process small as you are running it: 

(setq acl2::*acl2-allocation-alist* nil).
In one test several years ago, we found the following times (minutes:seconds) using a Sparc 2. 
31:42   64 megabytes main memory
33:37   64 megabytes main memory, using the SETQ form above
63:52   16 megabytes main memory
43:09   16 megabytes main memory, using the SETQ form above

If you are running Linux Slackware v3.0:

Thanks to Vanderlei Moraes Rodrigues for the Slackware notes.


Reasoning about the Real Numbers

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.

Useful Addresses

To join the ACL2 mailing list, send a message to listproc@lists.cc.utexas.edu. The body of the message should contain the line:

subscribe acl2 name

where name is your name (not your email address). You should receive a confirmation of the request a short time later, along with instructions for using the mailing list (e.g., how to retrieve archive messages). If you need further assistance, please send a message to acl2-request@lists.cc.utexas.edu.

To send a message to all who receive ACL2 mail, send the message to acl2@lists.cc.utexas.edu. You can post messages to the ACL2 mailing list only if you are a member of the list.

Finally, please report bugs in ACL2 to acl2-bugs@lists.cc.utexas.edu.


Export/Re-Export Limitations

ACL2 may be exported to any countries except those subject to embargoes under various laws administered by the Office of Foreign Assets Control ("OFAC") of the U. S. Department of the Treasury.

License and Copyright

ACL2 Version 2.5 -- A Computational Logic for Applicative Common Lisp
Copyright (C) 2000 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.

Matt Kaufmann (Kaufmann@cs.utexas.edu)
J Strother Moore (Moore@cs.utexas.edu)

Department of Computer Sciences
University of Texas at Austin
Austin, TX 78712-1188 U.S.A.