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 Makefile
s that include
books/Makefile-generic
. You can look at existing Makefile
s to
understand how to create your own Makefile
s. Here are the seven 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. Include the file books/Makefile-generic
. For example, if you look at
books/misc/Makefile
then you'll see that it starts with this line:
include ../Makefile-genericNote that
../
should be replaced by the appropriate path to
books/Makefile-generic
. AND PLEASE NOTE: This include
line should
precede the lines mentioned below.
2. Define the ACL2
variable. For example, file
books/arithmetic-3/pass1/Makefile
starts as follows.
include ../../Makefile-generic ACL2 = ../../../saved_acl2Note that you will need to provide the appropriate path to your ACL2 executable.
3. (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 include
and ACL2
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
.
4. 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
books/finite-set-theory/osets/Makefile
, should make this clear.
BOOKS = computed-hints fast instance map membership outer primitives \ quantify set-order sets sort
5. 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.
6. Run the following command:
make dependenciesThis will generate dependency information. If you try it in
books/misc/
,
the result should agree with what you find in books/misc/Makefile
. If
you run this in the directory you are developing, you will want to insert the
output at the end of your Makefile
.
7. 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.
That 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-subdirsThis 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. Here is the current version (as of ACL2 Version_3.2) of
books/arithmetic-3/Makefile
.
ACL2 = ../../saved_acl2The first line is optional becausearith-top: top all all: top
DIRS = pass1 bind-free floor-mod include ../Makefile-subdirs include ../Makefile-generic
top.cert: top.lisp top.cert: bind-free/top.cert top.cert: floor-mod/floor-mod.cert top.cert: floor-mod/mod-expt-fast.cert
../../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 cleanwill remove all
.cert
files, files resulting from compilation, and other
``junk''; see the full list under ``clean:
'' in
books/Makefile-generic
.
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 faslIn 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).