Major Section: EVENTS
Examples: (include-book "my-arith") (include-book "/home/smith/my-arith") (include-book "/../../my-arith")General Form: (include-book file :load-compiled-file action ; [default :warn] :uncertified-okp t/nil ; [default t] :defaxioms-okp t/nil ; [default t] :skip-proofs-okp t/nil ; [default t] :dir directory :doc doc-string)
where file is a book name. See books for general information,
see book-name for information about book names, and see pathname for
information about file names. Action is one of t, nil, :warn
(the default), :try, or :comp; these values are explained below. The
first three -okp keyword arguments, which default to t, determine
whether errors or warnings are generated under certain conditions explained
below; when the argument is t, warnings are generated. The dir
argument, if supplied, is a keyword that represents an absolute pathname for
a directory (see pathname), to be used instead of the current book directory
(see cbd) for resolving the given file argument to an absolute pathname.
In particular, :dir :system resolves file using the distributed
books/ directory of your installation, unless your ACL2 executable was
built somewhere other than where it currently resides; please see the ``BOOKS
DIRECTORY, AND SOUNDNESS WARNING'' below. To define other keywords that can
be used for dir, see add-include-book-dir. Doc-string is an
optional documentation string; see doc-string. If the book has no
certificate, if its certificate is invalid or if the certificate
was produced by a different version of ACL2, a warning is printed and
the book is included anyway; see certificate. This can lead to serious
errors; see uncertified-books. If the portcullis of the certificate
(see portcullis) cannot be raised in the host logical world, an error
is caused and no change occurs to the logic. Otherwise, the non-local
events in file are assumed. Then the keep of the certificate
is checked to ensure that the correct files were read; see keep. A warning
is printed if uncertified books were included. Even if no warning is
printed, include-book places a burden on you; see certificate.
If there is a compiled file for the book that was created more
recently than the book itself and the value action of the
:load-compiled-file argument is not nil, or is omitted, then
the compiled file is automatically loaded; otherwise it is not
loaded. If action is t then the compiled file must be
loaded or an error will occur; if action is :warn (the
default) then a warning will be printed; if action is :try
then no warning will be printed; and if action is :comp then
the file will be immediately compiled (if the compiled file does not
already exist) and loaded. Certify-book can also be used to
compile a book. The effect of compilation is to speed up the
execution of the functions defined within the book when those
functions are applied to specific values. The presence of compiled
code for the functions in the book should not otherwise affect the
performance of ACL2. See guard for a discussion. NOTE: the
:load-compiled-file argument is not recursive; that is, calls of
include-book that are inside the book supplied to
include-book will use their own :load-compiled-file
arguments (default :warn), not the :load-compiled-file
argument for the enclosing book.
The three -okp arguments, :uncertified-okp, defaxioms-okp,
and skip-proofs-okp, determine the system's behavior when
the book or any subbook is found to be uncertified, when the book
or any subbook is found to contain defaxiom events, and when
the book or any subbook is found to contain skip-proofs events,
respectively. All three default to t, which means it is ``ok''
for the condition to arise. In this case, a warning is printed but
the processing to load the book is allowed to proceed. When one of
these arguments is nil and the corresponding condition arises,
an error is signaled and processing is aborted. Exception:
:uncertified-okp is ignored if the include-book is being
performed on behalf of a certify-book.
Include-book is similar in spirit to encapsulate in that it is
a single event that ``contains'' other events, in this case the
events listed in the file named. Include-book processes the
non-local event forms in the file, assuming that each is
admissible. Local events in the file are ignored. You may
use include-book to load multiple books, creating the logical
world that contains the definitions and theorems of all of
them.
If any non-local event of the book attempts to define a name
that has already been defined -- and the book's definition is not
syntactically identical to the existing definition -- the attempt to
include the book fails, an error message is printed, and no change
to the logical world occurs. See redundant-events for the
details.
When a book is included, the default defun-mode
(see default-defun-mode) for the first event is always
:logic. That is, the default defun-mode ``outside'' the book --
in the environment in which include-book was called -- is
irrelevant to the book. Events that change the defun-mode are
permitted within a book (provided they are not in local forms).
However, such changes within a book are not exported, i.e., at the
conclusion of an include-book, the ``outside'' default defun-mode
is always the same as it was before the include-book.
Unlike every other event in ACL2, include-book puts a burden on
you. Used improperly, include-book can be unsound in the sense
that it can create an inconsistent extension of a consistent logical
world. A certification mechanism is available to help you
carry this burden -- but it must be understood up front that even
certification is no guarantee against inconsistency here. The
fundamental problem is one of file system security.
See certificate for a discussion of the security issues.
After execution of an include-book form, the value of
acl2-defaults-table is restored to what it was immediately before
that include-book form was executed.
See acl2-defaults-table.
BOOKS DIRECTORY, AND SOUNDNESS WARNING.
We refer to the ``books directory'' of an executable image as the full
pathname string of the books directory associated with :dir :system for
that image. This is where the distributed books directory should reside. By
default, it is the books/ subdirectory of the directory where the sources
reside and the executable image is thus built. However, the Makefile
provided with ACL2 contains a variable ACL2_BOOKS_DIR that may be set to
the intended books directory. Advanced users who want to modify the books
directory without using the Makefile can look at the calls of
initialize-acl2 therein. For example, if the distributed books are to be
moved to /usr/local/lib/, a manual build on Windows without using the
Makefile might conclude as follows.
(save-acl2 (quote (initialize-acl2 (quote include-book)
*acl2-pass-2-files*
"/usr/local/lib/"))
"saved_acl2.bat")
The Soundness Warning is this: You must avoid using two executable images
with different books directories in the same project, if there are any
include-book forms with :dir :system in that collection of books.
Otherwise, unsoundness may occur. (We may enforce this restriction in later
versions of ACL2.) Here is an example.
Suppose we certify a bookbook1using an executable with books directorydir1, where this book contains the definition(defun foo () 1). Suppose that bookbook2contains these forms:; book2 (in-package "ACL2") (include-book "book1" :dir :system) (defthm thm1 (equal (foo) 1))Now let us certify thisbook1andbook2(see certify-book). But now suppose we have another executable image, this time with a different books directorydir2, wheredir2also contains a book namedbook1, but where this newbook1contains the definition(defun foo () 2). If we execute(include-book "book2" :dir :system)using the second executable, we will be including the latter definition offoofrom the latterbook1together with the above-displayed theoremthm1, and hence we can trivially provenil!
We conclude the Soundness Warning by noting that even if you use a single
executable image, :dir :system will not work for you if you move the
books from their original location, unless care was taken to specify the
final location when the image was built as indicated in the discussion of the
Makefile and initialize-acl2 above.
This concludes the guided tour through books.
See set-compile-fns for a subtle point about the interaction
between include-book and on-the-fly compilation.
See certify-book for a discussion of how to certify a book.