BOOKS-CERTIFICATION-CLASSIC.html -- ACL2 Version 6.3

## BOOKS-CERTIFICATION-CLASSIC

classic ACL2 `make'-based certification of books

    Major Section:  BOOKS

This documentation topic explains an approach to certifying directories of books, which we call ``classic ACL2 `make'-based certification''.

Warning: The capability described in this section might be replaced at any time by a capability based on corresponding support for community books (see books-certification). If you think that would be a hardship, please contact the ACL2 implementors.

This topic discusses a way to certify a directory of books other than the ACL2 community books. See books-certification for how to certify the set of ACL2 community books. There is also a section in that documentation topic, ``Restricting to Specific Directories and Books'', that provides an alternative to classic ACL2 `make'-based certification (as discussed in the present topic) for certifying specified sets of 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'. And finally, we assume, as is typically the case by following the standard installation instructions, that you install the ACL2 community books in the `books/` subdirectory of your ACL2 distribution. We will refer below to that directory as `BOOKS`.

In summary: to use `make' to certify books under a given directory, you may create a simple Makefile in that directory (as explained below) so that when you stand in that directory, you can submit the command, `make', to certify those books. If you have a multi-processor machine or the like, then you can use the ``-j` flag `make'-level parallelism by specifying the number of concurrent processes. For example:

    make -j 4

For each book `foo.lisp`, a file `foo.out` in the same directory as `foo.lisp` will contain the output from the corresponding certification attempt. If you have previously executed such a command, then you might first want to delete certificate files and other generated files by executing the following command.

    make clean

Note that when you run `make', then by default, the first error will cause the process to stop. You can use `make -i` to force `make' to ignore errors, thus continuing past them. Or, use `make -k` to keep going, but skipping certification for any book that includes another whose certification has failed.

By default, your acl2-customization file (see acl2-customization) is ignored by such `make' commands. However, you can specify the use of an acl2-customization file by setting the value of environment variable `ACL2_CUSTOMIZATION` to the empty string, indicating a default such file, or to the desired absolute pathname. For example:

    make ACL2_CUSTOMIZATION=''
    make ACL2_CUSTOMIZATION='~/acl2-customization.lisp'

We now discuss how to create makefiles to support `make' commands as discussed above.

First we give five steps for creating a `Makefile` to support certification of a directory of books, without subdirectories. For examples of such Makefiles you can look in community book directories (which, however, might disappear in future versions of ACL2).

> 1. Include the file `Makefile-generic` from the `books/` subdirectory of your ACL2 sources directory, but first perhaps define the variable ``ACL2`'. Consider the following example.

>     ACL2 ?= /Users/john_doe/acl2/acl2-sources/saved_acl2
>     include /Users/john_doe/acl2/acl2-sources/books/Makefile-generic

> In this example, you can omit the first line, because the default ACL2 executable is file `saved_acl2` in the directory immediately above the directory of the specified `Makefile-generic` file. Indeed, that is the common case. Note the use of `?=` instead of `=` or `:=`, so that `ACL2` can instead be defined by the environment or provided on the command line as part of the `make' command.

> 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 ``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. Normally, every file with extension `.lisp` will be a book that you want to certify, in which case 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 community books file `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 community books file `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.

> 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. Thus, 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 of adding the ``-include`' line above, 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.

This concludes the basic instructions for creating a `Makefile` in a directory including books. Here are some other capabilities offered by community books file `books/Makefile-subdirs`. Not included below is a discussion of how to increase parallelism by avoiding the need to certify included books before certifying a given book; see provisional-certification.

Subdirectory Support

There is support for using `make' to certify books in subdirectories. Consider the following example.

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

This indicates that we are to run `make' in subdirectories `pass1/`, `bind-free/`, and `floor-mod/` of the current directory.

You can combine this subdirectory support with the support already discussed for certifying books in the top-level directory. Here is an example, which as of this writing is in community books file `books/arithmetic-3/Makefile` contains the following lines.

    arith-top: top all
    all: top

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

    -include Makefile-deps

The ``top`' target is defined in `../Makefile-subdirs` to call `make' in each subdirectory specified 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 which, in turn, is the default target in any `Makefile-generic`, and is responsible for certifying books in the current directory as discussed in the five steps displayed above.

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 the `-j` option of `make' can allow subdirectories to be processed in parallel.

Cleaning Up

We note that there is a `clean` target. Thus,

    make clean

will remove generated files including `.cert`, `.out` files, and compiled files.

System Books

An environment variable `ACL2_SYSTEM_BOOKS` is generally set automatically, so you can probably skip reading the following paragraph unless your attempt to certify books fails to locate those books properly.

The environment variable `ACL2_SYSTEM_BOOKS` can be set to the top-level directory of the ACL2 community books. 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

The file `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 using GCL as the host Lisp, 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).

If you run into problems, you can get help by joining the `acl2-help` email list (follow the link from the ACL2 home page) and sending a message to that list. Also consider trying another version of GNU `make'; for example, we have found that versions 3.81 and 3.82 sometimes cause errors on Linux where version 3.80 does not.