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
:uncertified-okp t/nil ; [default t]
:defaxioms-okp t/nil ; [default t]
:skip-proofs-okp t/nil ; [default t]
:ttags ttags ; [default nil]
: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,
:default, :warn, or :comp; these values are explained below, and
the default is :default. The 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, by default :dir :system
resolves file using the books/ directory of your ACL2 installation,
unless your ACL2 executable was built somewhere other than where it currently
resides; please see the ``Books Directory'' 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, perhaps mitigated by the presence of a .port file from an earlier
certification; 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 you use guards, please note include-book is executed as though
(set-guard-checking nil) has been evaluated; see set-guard-checking. If
you want guards checked, please see ld and/or see rebuild.
The value of :load-compiled-file controls whether a compiled file for the
given file is loaded by include-book. Note that this keyword applies
only to the given file, not to any included sub-books. In order to skip
loading all compiled files, for the given file as well as all included
sub-books -- for example, to avoid Lisp errors such as ``Wrong FASL
version'' -- use (set-compiler-enabled nil state); see compilation.
Otherwise, if keyword argument :load-compiled-file is missing or its
value is the keyword :default, then it is treated as :warn. If its
value is nil, no attempt is made to load the compiled file for the book
provided. In order to load the compiled file, it must be more recent than
the book's certificate (except in raw mode, where it must be more recent
than the book itself; see set-raw-mode). For non-nil values of
:load-compiled-file that do not result in a loaded compiled file, ACL2
proceeds as follows. Note that a load of a compiled file or expansion file
aborts partway through whenever an include-book form is encountered for
which no suitable compiled or expansion file can be loaded. For much more
detail, see book-compiled-file.
t: Cause an error if the compiled file is not loaded. This same requirement is imposed on everyinclude-bookform evaluated during the course of evaluation of the presentinclude-bookform, except that for those subsidiaryinclude-books that do not themselves specify:load-compiled-file t, it suffices to load the expansion file (see book-compiled-file).
:warn: An attempt is made to load the compiled file, and a warning is printed if that load fails to run to completion.
:comp: A compiled file is loaded as with valuet, except that if a suitable ``expansion file'' exists but the compiled file does not, then the compiled file is first created. See book-compiled-file.
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.
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.
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 several 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.
At the beginning of execution of an include-book form, even before
executing portcullis commands, the value of
acl2-defaults-table is restored to the value it had at startup. 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. We refer to the ``books directory'' of an executable
image as the full pathname string of the directory associated with
include-book keyword option :dir :system for that image. By default,
it is the books/ subdirectory of the directory where the sources reside
and the executable image is thus built (except for ACL2(r) -- see real
--, where it is books/nonstd/). If those books reside elsewhere, the
environment variable ACL2_SYSTEM_BOOKS can be set to the books/
directory under which they reside (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/4-0/acl2-sources/booksIf you follow suggestions in the installation instructions, these books will be the ACL2 community books; see community-books.
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.
:cited-by Programming