SET-RAW-MODE

Major Section:  SWITCHES-PARAMETERS-AND-MODES

Below we discuss raw-mode. In brief: The simplest way to turn raw-mode on is :SET-RAW-MODE-ON!, and to turn it off, :SET-RAW-MODE NIL. Also see set-raw-mode-on!.

Some Related Topics

• ADD-RAW-ARITY -- add arity information for raw mode

• REMOVE-RAW-ARITY -- remove arity information for raw mode

ACL2 users often find its careful syntax checking to be helpful during code development. Sometimes it is even useful to do code development in :logic mode, where ACL2 can be used to check termination of (mutually) recursive functions, verify guards, or even prove properties of the functions.

However, loading code using include-book is much slower than using Common Lisp load in raw Lisp, and in this sense ACL2 can get in the way of efficient execution. Unfortunately, it is error-prone to use ACL2 sources (or their compilations) in raw Lisp, primarily because a number of ACL2 primitives will not let you do so. Perhaps you have seen this error message when trying to do so:

HARD ACL2 ERROR in ACL2-UNWIND-PROTECT:  Apparently you have tried
to execute a form in raw Lisp that is only intended to be executed
inside the ACL2 loop.

ACL2 provides a ``raw mode'' for execution of raw Lisp forms. In this mode, include-book reduces essentially to a Common Lisp load. More generally, the ACL2 logical world is not routinely extended in raw mode (some sneaky tricks are probably required to make that happen). To turn raw mode off or on:

:set-raw-mode t   ; turn raw mode on
:set-raw-mode nil ; turn raw mode off

The way you can tell that you are in raw mode is by looking at the prompt (see default-print-prompt), which uses a capital ``P'' (suggesting something like program mode, but more so).

ACL2 P>

Typical benefits of raw mode are fast loading of source and compiled files and the capability to hack arbitrary Common Lisp code in an environment with the ACL2 sources loaded (and hence with ACL2 primitives available). In addition, ACL2 hard errors will put you into the Lisp debugger, rather than returning you to the ACL2 loop, and this may be helpful for debugging; see hard-error and see illegal, but also see break-on-error. However, it probably is generally best to avoid raw mode unless these advantages seem important. We expect the main benefit of raw mode to be in deployment of applications, where load time is much faster than the time required for a full-blown include-book, although in certain cases the fast loading of books and treatment of hard errors discussed above may be useful during development.

Raw mode is also useful for those who want to build extensions of ACL2. For example, the following form can be put into a certifiable book to load an arbitrary Common Lisp source or compiled file.

(progn (defttag my-application)
       (progn! (set-raw-mode t)
               (load "some-file")))

Below are several disadvantages to raw mode. These should discourage users from using it for general code development, as :program mode is generally preferable.

-- Forms are in essence executed in raw Lisp.  Hence:
   -- Syntax checking is turned off; and
   -- Guard checking is completely disabled.
-- Table events, including logic, are ignored, as are many
   other events, including defthm and comp.
-- Soundness claims are weakened for any ACL2 session in which raw
   mode was ever entered; see defttag.
-- The normal undoing mechanism (see ubt) is not supported.
-- Unexpected behavior may occur when you return from raw-mode.
   For example, if you redefine a :logic mode function whose guards
   have not been verified, you will not see the change inside the
   ACL2 loop because there, the raw Common Lisp definition is only
   executed after guards have been verified; see guards-and-evaluation
   and see guard-evaluation-table.

We conclude with some details.

Printing results. The rules for printing results are unchanged for raw mode, with one exception. If the value to be printed would contain any Lisp object that is not a legal ACL2 object, then the print routine is used from the host Lisp, rather than the usual ACL2 printing routine. The following example illustrates the printing used when an illegal ACL2 object needs to be printed. Notice how that ``command conventions'' are observed (see ld-post-eval-print); the ``[Note'' occurs one space over in the second example, and no result is printed in the third example.

ACL2 P>(find-package "ACL2")
[Note:  Printing non-ACL2 result.]
#<The ACL2 package>
ACL2 P>(mv nil (find-package "ACL2") state)
 [Note:  Printing non-ACL2 result.]
#<The ACL2 package>
ACL2 P>(mv t (find-package "ACL2") state)
ACL2 P>(mv 3 (find-package "ACL2"))
[Note:  Printing non-ACL2 result.]
(3 #<The ACL2 package>)
ACL2 P>

Include-book. The events add-include-book-dir and delete-include-book-dir have been designed to work with raw mode. However, if you enter raw mode and then evaluate such forms, then the effects of these forms will disappear when you exit raw mode, in which case you can expect to see a suitable warning. Regarding include-book itself: it should work in raw mode as you might expect, at least if a compiled file or expansion file was created when the book was certified; see certify-book.

Packages. Raw mode disallows the use of defpkg. If you want to create a new package, first exit raw mode with :set-raw-mode nil; you can subsequently re-enter raw mode with :set-raw-mode t if you wish.