CERTIFY-BOOK.html -- ACL2 Version 6.3

## CERTIFY-BOOK

how to produce a certificate for a book

    Major Section:  BOOKS

    Examples:
    (certify-book "my-arith")          ; certify in a world with 0 commands
    (certify-book "my-arith" 3)        ; ... in a world with 3 commands
    (certify-book "my-arith" ?)        ; ... in a world without checking the
                                         ;     number of commands
    (certify-book "my-arith" 0 nil)    ; ... without compilation
    (certify-book "my-arith" 0 t)      ; ... with compilation (default)
    (certify-book "my-arith" 0 t :ttags (foo))
                                         ; ... allowing trust tag (ttag) foo
    (certify-book "my-arith" 0 t :ttags :all)
                                         ; ... allowing all trust tags (ttags)
    (certify-book "my-arith" t)        ; ... from world of old certificate
    (certify-book "my-arith" 0 nil :acl2x t)
                                         ; ... writing or reading a .acl2x file

    General Form:
    (certify-book book-name
                  k                           ; [default 0]
                  compile-flg                 ; [default t]
                  :defaxioms-okp t/nil        ; [default nil]
                  :skip-proofs-okp t/nil      ; [default nil]
                  :ttags ttags                ; [default nil]
                  :acl2x t/nil                ; [default nil]
                  :ttagsx ttags               ; [default nil]
                  :write-port t/nil           ; [default t]
                  :pcert pcert                ; [default nil]
                  )

where `book-name` is a book name (see book-name), `k` is used to indicate your approval of the ``certification world,'' and `compile-flg` can control whether the book is to be compiled. The defaults for `compile-flg`, `skip-proofs-okp`, `acl2x`, `write-port`, and `pcert` can be affected by environment variables. All of these arguments are described in detail below, except for `:pcert`. (We assume below that the value of `:pcert` is `nil` (and environment variable `ACL2_PCERT_ARG` is unset or the empty string). For a discussion of this argument, see provisional-certification.)

Certification occurs in some logical world, called the ``certification world.'' That world must contain the `defpkg`s needed to read and execute the forms in the book. The commands necessary to recreate that world from the ACL2 initial world are called the ``portcullis commands,'' and will be copied into the certificate created for the book. Those commands will be re-executed whenever the book is included, to ensure that the appropriate packages (and all other names used in the certification world) are correctly defined. The certified book will be more often usable if the certification world is kept to a minimal extension of the ACL2 initial world (for example, to prevent name clashes with functions defined in other books). Thus, before you call `certify-book` for the first time on a book, you may wish to get into the initial ACL2 world (e.g., with `:ubt 1` or just starting a new version of ACL2), `defpkg` the desired packages, and then invoke `certify-book`.

The `k` argument to `certify-book` must be either a nonnegative integer or else one of the symbols `t` or `?` in any package. If `k` is an integer, then it must be the number of commands that have been executed after the initial ACL2 world to create the world in which `certify-book` was called. One way to obtain this number is by doing `:pbt :start` to see all the commands back to the first one.

If `k` is `t` (or any symbol whose `symbol-name` is `"T"`), it means that `certify-book` should use the same world used in the last certification of this book. `K` may have such a value only if you call `certify-book` in the initial ACL2 world and there is a certificate on file for the book being certified. (Of course, the certificate is probably invalid.) In this case, `certify-book` reads the old certificate to obtain the portcullis commands and executes them to recreate the certification world.

Finally, `k` may be `?` (or any symbol whose `symbol-name` is `"?"`), in which case there is no check made on the certification world. That is, if `k` is such a value then no action related to the preceding two paragraphs is performed, which can be a nice convenience but at the cost of eliminating a potentially valuable check that the certification world may be as expected.

We next describe the meaning of `compile-flg` and how it defaults. If explicit compilation has been suppressed by `(set-compiler-enabled nil state)`, then `compile-flg` is coerced to `nil`; see compilation. Otherwise `compile-flg` may be given the value of `t` (or `:all`, which is equivalent to `t` except during provisional certification; see provisional-certification), indicating that the book is to be compiled, or else `nil`. (Note that compilation initially creates a compiled file with a temporary file name, and then moves that temporary file to the final compiled file name obtained by adding a suitable extension to the book name. Thus, a compiled file will appear atomically in its intended location.) Finally, suppose that `compile-flg` is not supplied (or is `:default`). If environment variable `ACL2_COMPILE_FLG` is defined and not the empty string, then its value should be `T`, `NIL`, or `ALL` after converting to upper case, in which case `compile-flg` is considered to have value `t`, `nil`, or `:all` (respectively). Otherwise `compile-flg` defaults to `t`. Note that the value `:all` is equivalent to `t` except for during the Convert procedure of provisional certification; see provisional-certification.

Two keyword arguments, `:defaxioms-okp` and `:skip-proofs-okp`, determine how the system handles the inclusion of `defaxiom` events and `skip-proofs` events, respectively, in the book. The value `t` allows such events, but prints a warning message. The value `nil` causes an error if such an event is found. `Nil` is the default unless keyword argument `:acl2x t` is provided and state global `'write-acl2x` is a cons (see set-write-acl2x), in which case the default is `t`.

The keyword argument `:ttags` may normally be omitted. A few constructs, used for example if you are building your own system based on ACL2, may require it. See defttag for an explanation of this argument.

When book `B` is certified with value `t` (the default) for keyword argument `:write-port`, a file `B.port` is written by certification process. This file contains all of the portcullis commands for `B`, i.e., all user commands present in the ACL2 logical world at the time `certify-book` is called. if `B.lisp` later becomes uncertified, say because events from that file or an included book have been edited, then `(include-book "B")` will consult `B.port` to evaluate forms in that file before evaluating the events in `B.lisp`. On the other hand, `B.port` is ignored when including `B` if `B` is certified.

If you use guards, please note `certify-book` is executed as though `(set-guard-checking nil)` has been evaluated; see set-guard-checking. If you want guards checked, consider using `ld` instead, or in addition; see ld.

For a general discussion of books, see books. `Certify-book` is akin to what we have historically called a ``proveall'': all the forms in the book are ``proved'' to guarantee their admissibility. More precisely, `certify-book` (1) reads the forms in the book, confirming that the appropriate packages are defined in the certification world; (2) does the full admissibility checks on each form (proving termination of recursive functions, proving theorems, etc.), checking as it goes that each form is an embedded event form (see embedded-event-form); (3) rolls the world back to the initial certification world and does an `include-book` of the book to check for `local` incompatibilities (see local-incompatibility); (4) writes a certificate recording not only that the book was certified but also recording the commands necessary to recreate the certification world (so the appropriate packages can be defined when the book is included in other worlds) and the check sums of all the books involved (see certificate); (5) compiles the book if so directed (and then loads the object file in that case). The result of executing a `certify-book` command is the creation of a single new event, which is actually an `include-book` event. If you don't want its included events in your present world, simply execute `:``ubt` `:here` afterwards.

A utility is provided to assist in debugging failures of `certify-book`; see redo-flat.)

`Certify-book` requires that the default defun-mode (see default-defun-mode) be `:``logic` when certification is attempted. If the mode is not `:``logic`, an error is signalled.

An error will occur if `certify-book` has to deal with any uncertified book other than the one on which it was called. For example, if the book being certified includes another book, that subbook must already have been certified.

If you have a certified book that has remained unchanged for some time you might well not remember the appropriate `defpkg`s for it, though they are stored in the certificate file and (by default) also in the `.port` file. If you begin to change the book, don't throw away its certificate file just because it has become invalid! It is an important historical document until the book is re-certified. More important, don't throw away the `.port` file, as it will provide the portcullis commands when including the book as an uncertified book; see include-book.

When `certify-book` is directed to produce a compiled file, it calls the Common Lisp function `compile-file` on the original source file. This creates a compiled file with an extension known to ACL2, e.g., if the book is named `"my-book"` then the source file is `"my-book.lisp"` and the compiled file under GCL will be `"my-book.o"` while under SBCL it will be `"my-book.fasl"`. The compiled file is then loaded. When `include-book` is used later on `"my-book"` it will automatically load the compiled file, provided the compiled file has a later write date than the source file. The only effect of such compilation and loading is that the functions defined in the book execute faster. See guard for a discussion of the issues, and if you want more details about books and compilation, see book-compiled-file.

When `certify-book` is directed not to produce a compiled file, it will delete any existing compiled file for the book, so as not to mislead `include-book` into loading the now outdated compiled file. Otherwise, `certify-book` will create a temporary ``expansion file'' to compile, obtained by appending the string "@expansion.lsp" to the end of the book name. Remark: Users may ignore that file, which is automatically deleted unless state global variable `'save-expansion-file` has been set, presumably by a system developer, to a non-`nil` value; see book-compiled-file for more information about hit issue, including the role of environment variable `ACL2_SAVE_EXPANSION`.

After execution of a `certify-book` form, the value of `acl2-defaults-table` is restored to what it was immediately before that `certify-book` form was executed. See acl2-defaults-table.

Those who use the relatively advanced features of trust tags (see defttag) and `make-event` may wish to know how to create a certificate file that avoids dependence on trust tags that are used only during `make-event` expansion. For this, including documentation of the `:acl2x` and `:ttagsx` keyword arguments for `certify-book`, see set-write-acl2x.

This completes the tour through the documentation of books.