INCLUDE-BOOK

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)

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, action, of :load-compiled-file controls whether a compiled file is loaded by include-book. If action is missing or its value is the keyword :default, then it is treated as :warn unless explicit compilation is suppressed (see compilation), in which case it is treated as nil. If action is nil or :comp!, no attempt is made to load the compiled file for the book provided; otherwise, such an attempt is made but the compiled file must exist and be more recent than the book itself. For non-nil values of action that do not result in a loaded compiled file, ACL2 proceeds as follows.

:warn: a warning is printed

:try: no warning is printed

:comp, :comp!: a compiled file is created and loaded, where in the case of :comp! any preexisting compiled file is first deleted. Note that the compiled file includes executable counterparts, as for compiled files typically by created certify-book.

An effect of compilation is to speed up the execution of the functions defined within the book. Compilation can also remove tail recursion, thus avoiding stack overflows. The presence of compiled code for the functions in the book should not otherwise affect the performance of ACL2. See guard for a discussion. NOTES: (1) 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, not the :load-compiled-file argument for the enclosing book. (2) Only functions defined in the book (executable counterparts as discussed above) are compiled, not functions defined in sub-books or in the certification world (see portcullis).

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.

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.

Distributed Books Directory. 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 (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/v3-2/acl2-sources/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