ACL2 Version 6.3 Installation Guide: Obtaining and Installing ACL2

# Obtaining and Installing ACL2

[Back to main page of Installation Guide.]

Table of Contents

- Pre-built Binary Distributions
  - Linux/Mac/Windows Binaries in ACL2s
  - Windows
  - MacPorts for Mac OS X
  - Debian GNU Linux
- Obtaining the Sources and Community Books
- Creating or Obtaining an Executable Image
  - Pre-Built Images
  - Building an Executable image on a Unix-like System
  - Building an Executable image on Other than a Unix-like Systems
  - Building an Executable Image on Some Particular Systems
    - Special Case: Building an Executable Image on a Windows System using GCL
    - Older instructions from Jared Davis for building ACL2 on Windows using mingw
- Running Without Building an Executable Image
- Summary of Distribution
- Saving Space

ACL2 is more than just the executable image. You should typically obtain the distributed 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 6.3. We will call this directory dir. For example, dir might be `/home/jones/acl2/v6-3`.

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

A collection of books (ACL2 input files typically including definitions and theorems) has been developed over the years for use with ACL2, called the "community books". It is very useful to obtain these books, which are distributed from the Google Code acl2-books project website; directions are included below.

## Pre-built Binary Distributions

Visit the "Recent changes to this page" link on the ACL2 home page to see if there are other shortcuts available.

WARNING: Some of these packages might be for old version of ACL2. We recommend that you use the latest version of ACL2 (Version 6.3).

- Linux/Mac/Windows Binaries in ACL2s

  The ACL2 Sedan (ACL2s) is an Eclipse-based IDE for ACL2 that is distributed with pre-certified books and pre-built binaries. If you use an alternative development environment (such as Emacs), you can still fetch a tarball for your x86-based Linux/Mac/Windows system that contains a pre-built binary of (pure) ACL2, using the following instructions based on information kindly provided by Harsh Raju Chamarthi. Just extract the appropriate tarball (using `tar xfz` on Linux or Mac and `unzip` on Windows) under a path with no spaces. Then run the script you will find, `run_acl2` on Linux or Mac and `run_acl2.exe` on Windows, to start an ACL2 session. (Note that The first time you execute that command, the certificate (`.cert`) files are automatically fixed, according to the full pathname of your `books/` directory.) Also see the ACL2 documentation topic on the ACL2 Sedan.

- Windows

  In the past, a Windows Installer for ACL2 has included a Unix environment, pre-certified standard and workshop books, and a copy of Gnu Emacs. This capability has largely been superseded by the section on Building an Executable Image on Some Particular Systems and the Shortcut using the ACL2 Sedan, above. See also information about ACL2 on Windows.

- MacPorts for Mac OS X

  ACL2 versions have sometimes been made available under MacPorts. If we learn that an up-to-date version is available, we will add instructions here.

- Debian GNU Linux

  A Debian Gnu Linux package is available, which is likely to work on other Linux systems as well. 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 has said: "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." Alternatively, Debian GNU Linux users may wish to download the Debian package for Linux. Or, see following annotated log, provided by Camm Maguire, to see another way to proceed.

           camm@localhost:~$ cd /tmp
           camm@localhost:/tmp$ mkdir a
           camm@localhost:/tmp$ cd a
           camm@localhost:/tmp/a$ wget ftp://ftp.debian.org/debian/pool/main/a/acl2/acl2*5.0*_{i386,all}*b

           ;;; or ftp, use browser, etc.  I.e. download the .deb files.  Replace
           ;;; i386 above with amd64 if the target is a 64bit Ubuntu machine.
           ;;; Other target names should be self explanatory.  The 'all'
           ;;; designation refers to binary independent data.

           camm@localhost:/tmp/a$ ls
           acl2_5.0-1_i386.deb	   acl2-books-certs_5.0-1_all.deb   acl2-doc_5.0-1_all.deb    acl2-infix_5.0-1_i386.deb        acl2-source_5.0-1_all.deb
           acl2-books_5.0-1_i386.deb  acl2-books-source_5.0-1_all.deb  acl2-emacs_5.0-1_all.deb  acl2-infix-source_5.0-1_all.deb
           camm@localhost:/tmp/a$ for i in *b; do ar x $i; tar zxf data.tar.gz; done

           ;;; unpack files in current directory

           camm@localhost:/tmp/a$ sed -e 's,usr,tmp/a/usr,g' usr/bin/acl2 >tmp && chmod 755 tmp && mv tmp usr/bin/acl2

           ;;; Edit shell script wrapper to refer to the local path

           camm@localhost:/tmp/a$ usr/bin/acl2
           GCL (GNU Common Lisp)  2.6.7 CLtL1    Aug 22 2012 15:25:31
           Source License: LGPL(gcl,gmp), GPL(unexec,bfd,xgcl)
           Binary License:  GPL due to GPL'ed components: (XGCL READLINE UNEXEC)
           Modifications of this banner must retain notice of a compatible license
           Dedicated to the memory of W. Schelter

           Use (help) to get some basic information on how to use GCL.
           Temporary directory for compiler files set to /tmp/

            ACL2 Version 5.0 built August 25, 2012  11:53:08.
            Copyright (C) 2012  University of Texas at Austin
            ACL2 comes with ABSOLUTELY NO WARRANTY.  This is free software and you
            are welcome to redistribute it under certain conditions.  For details,
            see the GNU General Public License.

            Initialized with (INITIALIZE-ACL2 'INCLUDE-BOOK *ACL2-PASS-2-FILES*).
            See the documentation topic note-5-0 for recent changes.
            Note: We have modified the prompt in some underlying Lisps to further
            distinguish it from the ACL2 prompt.

           ACL2 Version 5.0.  Level 1.  Cbd "/tmp/a/".
           System books directory "/tmp/a/usr/share/acl2-5.0/books/".
           Type :help for help.
           Type (good-bye) to quit completely out of ACL2.

           ACL2 !>

## Obtaining the Sources and Community Books

Obtain the sources and place them in directory dir as follows.

(First, a note for Windows users only: we suggest that you obtain a Unix-like environment or, at least, download a utility such as `djtarnt.exe` to use with the `-x` option on gzipped tarfiles. 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.)

- Save acl2.tar.gz on directory dir. (You can run `md5sum` and compare with acl2-tar-gz-md5sum if you wish to verify the transmission.)
- 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`".)
  `cd dir`
  `tar xfz acl2.tar.gz`
  `rm acl2.tar.gz`
  `cd acl2-sources`
- We strongly suggest that you now install the community books, using one of the following methods, while still connected to the new directory.
  - Easy download. Fetch `a gzipped tarfile` of the community books from the Google Code website, and then extract as follows to create a `books/` subdirectory:
    `tar xfz books-6.3.tar.gz`
  - OR, obtain a read-only copy using svn as a new subdirectory, `books/`:
    `svn checkout http://acl2-books.googlecode.com/svn/branches/6.3 books`
  - OR, for read-write access, become a member of the acl2-books project by contacting one of the project administrators (see the acl2-books project page). Then:
    `svn checkout https://acl2-books.googlecode.com/svn/branches/6.3 books --username <name>`
  NOTE: The second and third methods provide all of the community books, but the first omits the `workshops/` and `nonstd/` subdirectories of these `books/`, which (respectively) are books contributed in support of papers presented at ACL2 workshops, and books for use with ACL2(r). You can fetch these easily as gzipped tarfiles, as follows, using the following links to the Google Code website.
  - ACL2 Workshops books
  - ACL2(r) books
  Then put the gzipped tarfile(s) in the `acl2-sources/books/` directory, connect to that directory, and extract to create `workshops/` and `nonstd/` subdirectories, respectively:
  `tar xfz workshops-6.3.tar.gz`
  `tar xfz nonstd-6.3.tar.gz`

## Creating or Obtaining an Executable Image

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.

- Building an Executable Image on a Unix-like System
- Building an Executable Image on Other than a Unix-like System
- Running Without Building an Executable Image

### Short Cut: Pre-Built ACL2 Images

The site http://www.cs.utexas.edu/users/moore/acl2/v6-3/distrib/images/Readme.html contains links to ACL2 executables and packages. Each `-md5sum` file was created using `md5sum`. We may add additional links from time to time.

Now proceed to Using ACL2.

### Building an Executable Image on a Unix-like System

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-sources`
`make LISP=`xxx
where xxx is the command to run your local Common Lisp.

By default, if no `LISP=`xxx is specified, `LISP=ccl` is used. On our hosts, `ccl` is the name of Clozure Common Lisp (CCL), which can be obtained as explained in the Requirements document.

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 up to a couple hundred megabytes or so.

This `make` works for the Common Lisps listed in Requirements document on 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 below for other than Unix-like systems.

You can now skip to Using ACL2.

### Building an Executable Image on Other than a Unix-like System

Next we describe how to create a binary image containing ACL2 without using the ``make`' utility. 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.

See also Building an Executable Image on Some Particular Systems, in case you want to skip directly to the instructions in one of its subtopics.

Otherwise, proceed as follows.

Your Common Lisp should be one of those listed in Requirements document. Filenames below should default to the dir`/acl2-sources` directory; please connect to that directory before continuing.

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.

         ; Compile
         (load "init.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:

         ; Initialization, first pass
         (load "init.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 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.)

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:

         ; Initialization, second pass
         (load "init.lisp")
         (in-package "ACL2")
         (save-acl2 (quote (initialize-acl2))
                    "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:
   - move `saved_acl2.dxl` to `osaved_acl2.dxl`
   - move `saved_acl2` to `osaved_acl2` and edit `osaved_acl2`, changing `saved_acl2.dxl` (at end of line) to `osaved_acl2.dxl`
   ELSE IF `saved_acl2` exists THEN:
   - move `saved_acl2` to `osaved_acl2`

7. Move `nsaved_acl2` to `saved_acl2`.

8. For some Common Lisps, a file `nsaved_acl2.`suffix is created for some suffix. Move it to: `saved_acl2.`suffix

9. Make sure `saved_acl2` is executable. For Windows this involves two mini-steps:

   > (a) Remove the `"$*"` from the `saved_acl2` script (because Windows does not understand `$*`). Consequently, any arguments you pass to ACL2 via the command line will be ignored.

   > (b) Rename `saved_acl2` to `saved_acl2.bat`, for example by executing the following command.
   > `rename saved_acl2 saved_acl2.bat`

### Building an Executable Image on Some Particular Systems

Subtopics of this section are as follows.

- Special Case: Building an Executable Image on a Windows System using GCL
- Instructions from David Rager for building ACL2 on Windows
- Older instructions from Jared Davis for building ACL2 on Windows using mingw

### Special Case: Building an Executable Image on a Windows System using GCL

You may want to skip this section and instead read Instructions from David Rager for building ACL2 on Windows. Or, you may be able to download a pre-built ACL2 image for Windows instead of reading this section.

Otherwise here are steps to follow.

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

       @
       % do not delete this line %
       @ECHO off
       set cwd=%cd%
       path C:\gcl\gclm\mingw\bin;%PATH%
       C:\gcl\gclm\lib\gcl-2.6.2\unixport\saved_gcl.exe -dir C:/gcl/gclm/lib/gcl-2.6.2/unixport/ -libdir  C:/gcl/gclm/lib/gcl-2.6.2/ -eval "(setq si::*allow-gzipped-file* t)" %1 %2 %3 %4 %5 %6 %7 %8 %9

3. THIRD, follow the instructions for other than Unix-like systems above, though the resulting file may be called `saved_acl2.exe` rather than `saved_acl2`.
4. FINALLY, create a file `acl2.bat` as explained in `http://www.cs.utexas.edu/users/moore/acl2/v6-3/distrib/images/Readme.html`.

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

## Running Without Building an Executable Image

The most convenient way to use ACL2 is first to install an executable image as described above for Unix-like systems 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-like systems 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.

Now proceed to read more about Using ACL2.

## Summary of Distribution

The ACL2 distribution, `acl2.tar.gz`, includes the ACL2 source files as well as the following files and directories (and a few others not mentioned here). Note that a `books/` directory is not included; see instructions above to fetch the community books.

      LICENSE       ; ACL2 license file
      GNUmakefile   ; For GNU make
      TAGS          ; Handy for looking at source files with emacs
      doc/          ; ACL2 documentation in various formats
      emacs/        ; Some helpful emacs utilities
      installation/ ; Installation instructions (start with installation.html)
      saved/        ; Empty directory for backing up copies during make

Also available are the following.

- `images/`: Some gzip'd tar'd executables; see `images/Readme.html`
- `split/`: The result of splitting up `acl2.tar.gz`

Based on the preceding ACL2 release, we estimate that the entire `acl2.tar.gz` is about 7MB, which extracts to about 30MB, and the gzipped tarfile `books-6.3.tar.gz` (obtained as described above) is about 12MB, which extracts to about 70MB. Additional space is required to build an image, perhaps 50 to 300 megabytes depending on the platform (including the host Lisp); and more will be required to certify books.

[Back to Installation Guide.]