BOOK-MAKEFILES

makefile support provided with the ACL2 distribution 
Major Section:  BOOKS

This topic describes the ACL2 methodology for using makefiles to assist in the automation of the certification of collections of ACL2 books. We assume here a familiarity with Unix/Linux make. We also assume that you are using GNU make rather than some other flavor of make.

ACL2's regression suite is run using Makefiles that include books/Makefile-generic. You can look at existing Makefiles to understand how to create your own Makefiles. Here are the six steps to follow to create a Makefile for a directory that contains books to be certified, and certify them using that Makefile. Below these steps we conclude with discussion of other capabilties provided by books/Makefile-generic.

1. It is most common to use an ACL2 executable named saved_acl2 that resides in the parent directory of the distributed books/ directory. In this case, unless you are using a very old version of GNU make (version 3.80, at least, works fine), you should be able to skip the following sentence, because the ACL2 `make' variable will be set automatically. Otherwise, define the ACL2 variable using ?= to point to your ACL2 executable (though this may be omitted for directories directly under the distributed books directory), for example: 

ACL2 ?= ../../../saved_acl2
(For Makefile experts: we use ?= instead of = or := because of the protocol used by the ACL2 make system: command-line values are passed explicitly with recursive calls of make to override the Makefile values of ACL2, which in turn need to be able to override the environment value of ACL2 from books/Makefile-generic).

Also include the file Makefile-generic in the distributed books directory. For example, file books/arithmetic-3/pass1/Makefile starts as follows. 

include ../../Makefile-generic
If you also have a line defining ACL2 as explained above, put that line just above this include line.

2. (Optional; usually skipped.) Set the INHIBIT variable if you want to see more than the summary output. For example, if you want to see the same output as you would normally see at the terminal, put this line in your Makefile after the `ACL2 ?=' and ~c[include]' lines. 

INHIBIT = (assign inhibit-output-lst (list (quote proof-tree)))
For other values to use for INHIBIT, see set-inhibit-output-lst and see the original setting of INHIBIT in books/Makefile-generic.

3. Specify the books to be certified. If every file with extension .lisp is a book that you want to certify, you can skip this step. Otherwise, put a line in your Makefile after the ones above that specifies the books to be certified. The following example, from an old version of books/finite-set-theory/osets/Makefile, should make this clear. 

BOOKS = computed-hints fast instance map membership outer primitives \
        quantify set-order sets sort
But better yet, use the extension .lsp for any Lisp or ACL2 files that are not to be certified, so that the definition of BOOKS can be omitted.

4. Create .acl2 files for books that are to be certified in other than the initial ACL2 world (see portcullis). For example, if you look in books/arithmetic/equalities.acl2 you will see defpkg forms followed by a certify-book command, because it was determined that defpkg forms were necessary in the certification world in order to certify the equalities book. In general, for each <book-name>.lisp whose certification requires a non-initial certification world, you will need a corresponding <book-name>.acl2 file that ends with the appropriate certify-book command. Of course, you can also use .acl2 files with initial certification worlds, for example if you want to pass optional arguments to certify-book.

You also have the option of creating a file cert.acl2 that has a special role. When file <book-name>.lisp is certified, if there is no file <book-name>.acl2 but there is a file cert.acl2, then cert.acl2 will be used as <book-name>.acl2 would have been used, as described in the preceding paragraph, except that the appropriate certify-book command will be generated automatically -- no certify-book command should occur in cert.acl2.

It is actually allowed to put raw lisp forms in a .acl2 file (presumably preceded by :q or (value :q) and followed by (lp)). But this is not recommended; we make no guarantees about certification performed any time after raw Lisp has been entered in the ACL2 session.

5. Generally, the next step is to include the following line after the `include' of Makefile-generic (see the first step above). 

-include Makefile-deps
This will cause `make' to create and then include a file Makefile-deps that contains ``dependency'' lines needed by make. If those dependencies are somehow flawed, it may be because you have include-book forms that are not truly including books, for example in multi-line comments (#|..|#). These will be ignored if preceded by a semicolon (;), or if you add a line break after ``include-book.'' But instead, you can create dependency lines yourself by running the command 
make dependencies
and pasting the result into the end of your Makefile, and editing as you see fit.

6. Run make. This will generate a <book-name>.out file for each <book-name>.lisp file being certified, which is the result of redirecting ACL2's standard output. Note that make will stop at the first failure, but you can use make -i to force make to continue past failures. You can also use the -j option to speed things up if you have a multi-core machine, e.g., make -j 8 in a book directory or, if in the ACL2 sources directory, make -j 8 regression.

This concludes the basic instructions for creating a Makefile in a directory including books. Here are some other capabilities offered by books/Makefile-subdirs.

Subdirectory support. There is support for subdirectories. For example, file books/arithmetic-3/Makefile formerly had the following contents. 

DIRS = pass1 bind-free floor-mod
include ../Makefile-subdirs
This indicated that we are to run make in subdirectories pass1/, bind-free/, and floor-mod of the current directory (namely, books/arithmetic-3/).

However, there is also subdirectory support when the current directory has books as well. File books/arithmetic-3/Makefile contains the following lines (current in ACL2 Version_3.6). 

arith-top: top all
all: top


DIRS = pass1 bind-free floor-mod
include ../Makefile-subdirs
include ../Makefile-generic


-include Makefile-deps
The first line is optional because ../../saved_acl2 is the default and the directory is a sub-sub-directory of the distribution directory; but it is harmless to include this line. The other additional lines support certifying books in the subdirectories before certifying the books in the present directory, in the customary make style.

Specifically, the top target is defined in ../Makefile-subdirs to call make in each subdirectory in DIRS. We have set the default target in the example above to a new name, arith-top, that makes that top target before making the all target. The all target, in turn, is the top (default) target in ../Makefile-generic, and is responsible for certifying books in the current directory.

Use Makefile-psubdirs instead of Makefile-subdirs if certification of a book in a subdirectory never depends on certification of a book in a different subdirectory, because then make's -j option can allow subdirectories to be processed in parallel.

Cleaning up. We note that there is a clean target. Thus, 

make clean
will remove all .cert files, files resulting from compilation, and other ``junk''; see the full list under ``clean:'' in books/Makefile-generic.

System books. An environment variable ACL2_SYSTEM_BOOKS is generally set automatically (at least in GNU make versions 3.80 and 3.81), so you can probably skip reading the following paragraph unless your attempt to certify distributed books fails to locate those books properly.

The environment variable ACL2_SYSTEM_BOOKS can be set to the books/ directory under which the books reside that are distributed with ACL2. A Unix-style pathname, typically ending in books/ or books, is permissible. In most cases, your ACL2 executable is a small script in which you can set this environment variable just above the line on which the actual ACL2 image is invoked, for example: 

export ACL2_SYSTEM_BOOKS
ACL2_SYSTEM_BOOKS=/home/acl2/v3-2/acl2-sources/books
However, you can also set ACL2_SYSTEM_BOOKS as a make variable, by setting it in your Makefile before the first target definition, e.g.: 
ACL2_SYSTEM_BOOKS = /home/acl2/v3-2/acl2-sources/books

Compilation support. Finally, books/Makefile-generic provides support for compiling books that are already certified (but see compilation for an exception). For example, suppose that you have certified books in GCL, resulting in compiled files with the .o extension. Now suppose you would like to compile the books for Allegro Common Lisp, whose compiled files have the .fasl extension. The following command will work if you have included books/Makefile-generic in your Makefile. 

make fasl
In general, the compiled file extension for a Lisp supported by ACL2 will be a target name for building compiled files for all your books (after certifying the books, if not already up-to-date on certification).