use.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd"><!-- DO NOT EDIT THIS FILE-->
<!-- Edit the .tex version instead-->

<html>
<head>
<title>使用Chez Scheme</title>
<link href="csug.css" rel="stylesheet" type="text/css">
</head>
<body>
<a name="g5"></a>
<a name="./use:h0"></a>

<h1>Chapter 2. 使用Chez Scheme<a name="CHPTUSE"></a></h1>


<p>
<i>Chez&nbsp;Scheme</i>常使用交互界面来支持程序开发和调试，然而它也能用于创建没有交互元素的独立应用。
本章描述了<i>Chez&nbsp;Scheme</i>的各种典型用法，或者说更普遍地，如何充分利用该系统。
Sections&nbsp;<a href="./use.html#g6">2.1</a>, <a href="./use.html#g7">2.2</a>,
和&nbsp;<a href="./use.html#g8">2.3</a>描述了如何以交互式的方式使用<i>Chez&nbsp;Scheme</i>。
Section&nbsp;<a href="./use.html#g9">2.4</a>讨论了如何在<i>Chez&nbsp;Scheme</i>中使用库和RNRS顶级程序。
Section&nbsp;<a href="./use.html#g10">2.5</a>涵盖了书写与运行Scheme脚本，包括编译脚本、编译RNRS顶级程序。
Section&nbsp;<a href="./use.html#g11">2.6</a>描述了如何构造和编译一个程序以求编译出最高效的代码。
Section&nbsp;<a href="./use.html#g12">2.7</a>描述了如何自定义启动过程，例如，改变或消除命令行选项、预加载Scheme或其他语言代码、或以其他程序子程序的方式运行<i>Chez&nbsp;Scheme</i>。
Section&nbsp;<a href="./use.html#g13">2.8</a>描述了如何使用<i>Petite&nbsp;Chez&nbsp;Scheme</i>建造<i>Chez&nbsp;Scheme</i>应用程序以获得运行时支持。
最后，Section&nbsp;<a href="./use.html#g14">2.9</a>涵盖了调用<i>Chez&nbsp;Scheme</i>时所能使用的命令行选项。

<p>

<h3><a name="g6"></a><a name="./use:h1"></a>Section 2.1. 与Chez Scheme交互<a name="SECTUSEINTERACTION"></a></h3>


<p>
最简单最高效的编写测试Scheme程序的方式之一是使用<tt>vi</tt>或<tt>emacs</tt>之类的文本编辑器来编写，然后在shell窗口中运行的<i>Chez&nbsp;Scheme</i>中交互式地测试它们。
当<i>Chez&nbsp;Scheme</i>以默认选项被安装好后，在shell的提示符后输入命令<tt>scheme</tt>以启动一个交互式Scheme会话。类似的，命令<tt>petite</tt>则是用于启动<i>Petite&nbsp;Chez&nbsp;Scheme</i>的交互式会话。
在输入这条命令后，你可以看到一段简短的后跟一个行首带着尖括号的新行的问候，就像这样：

<p>

<p><tt>Chez&nbsp;Scheme&nbsp;Version&nbsp;9.4<br>

Copyright&nbsp;1984-2016&nbsp;Cisco&nbsp;Systems,&nbsp;Inc.&nbsp;
<br>
<br>
&gt;&nbsp;</tt>
<p>你应该能看到，光标位于尖括号偏右一个空格的位置。
尖括号是系统的"REPL"的提示符，"REPL"是"Read Eval Print Loop"的缩写，意味读、求值、打印一个表达式，然后从头开始继续读、求值、打印的过程，就这么不断重复。

(在<i>Chez&nbsp;Scheme</i>中，REPL也叫做waiter。)

<p>
你可以输入一些Scheme表达式以回应提示符。
如果表达式正确，那么REPL会运行表达式，然后打印它的值。
以下是一些例子：

<p>

<p><tt>&gt;&nbsp;3<br>

3<br>

&gt;&nbsp;(+&nbsp;3&nbsp;4)<br>

7<br>

&gt;&nbsp;(cons&nbsp;'a&nbsp;'(b&nbsp;c&nbsp;d))<br>

(a&nbsp;b&nbsp;c&nbsp;d)</tt>
<p>The reader used by the REPL is more sophisticated than an ordinary
reader.
In fact, it's a full-blown "expression editor" ("expeditor" for short)
like a regular text editor but for just one expression at a time.
One thing you might soon notice is that the system automatically indents
the second and subsequent lines of an expression.
For example, let's say we want to define <tt>fact</tt>, a procedure that
implements the factorial function.
If we type <tt>(define&nbsp;fact</tt> followed by the enter key, the cursor
should be sitting under the first <tt>e</tt> in <tt>define</tt>, so that
if we then type <tt>(lambda&nbsp;(x)</tt>, we should see:

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(x)</tt>
<p>The expeditor also allows us to move around within the expression
(even across lines) and edit the expression to correct mistakes.
After typing:

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(x)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(=&nbsp;n&nbsp;0)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(*&nbsp;n&nbsp;(fact&nbsp;</tt>
<p>we might notice that the procedure's argument is named <tt>x</tt>
but we have been referencing it as <tt>n</tt>.
We can move back to the second line using the arrow keys,
remove the offending <tt>x</tt> with the backspace key, and
replace it with <tt>n</tt>.

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(n)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(=&nbsp;n&nbsp;0)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(*&nbsp;n&nbsp;(fact&nbsp;</tt>
<p>We can then return to the end of the expression with the arrow
keys and complete the definition.

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(n)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(=&nbsp;n&nbsp;0)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(*&nbsp;n&nbsp;(fact&nbsp;(-&nbsp;n&nbsp;1))))))</tt>
<p>Now that we have a complete form with balanced parentheses,
if we hit enter with the cursor just after the final parenthesis,
the expeditor will send it on to the evaluator.
We'll know that it has accepted the definition when we get another
right-angle prompt.

<p>
Now we can test our definition by entering, say, <tt>(fact&nbsp;6)</tt>
in response to the prompt:

<p>

<p><tt>&gt;&nbsp;(fact&nbsp;6)<br>

0</tt>
<p>The printed value isn't what we'd hoped for, since 6! is actually 720.
The problem, of course, is that the base-case return-value <tt>0</tt>
should have been <tt>1</tt>.
Fortunately, we don't have to retype the definition to correct the
mistake.
Instead, we can use the expeditor's history mechanism to retrieve the
earlier definition.
The up-arrow key moves backward through the history.
In this case, the first up-arrow retrieves <tt>(fact&nbsp;6)</tt>, and
the second retrieves the <tt>fact</tt> definition.

<p>
As we move back through the history, the expression editor shows us
only the first line, so after two up arrows, this is all we see of
the definition:

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact</tt>
<p>We can force the expeditor to show the entire expression by typing
<tt>^L</tt> (control <tt>L</tt>, i.e., the control and <tt>L</tt> keys
pressed together):

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(n)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(=&nbsp;n&nbsp;0)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(*&nbsp;n&nbsp;(fact&nbsp;(-&nbsp;n&nbsp;1))))))</tt>
<p>Now we can move to the fourth line and change the <tt>0</tt> to a
<tt>1</tt>.

<p>

<p><tt>&gt;&nbsp;(define&nbsp;fact<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(n)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(=&nbsp;n&nbsp;0)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(*&nbsp;n&nbsp;(fact&nbsp;(-&nbsp;n&nbsp;1))))))</tt>
<p>We're now ready to enter the corrected definition.
If the cursor is on the fourth line and we hit enter, however, it will
just open up a new line between the old fourth and fifth lines.
This is useful in other circumstances, but not now.
Of course, we can work around this by using the arrow keys to move
to the end of the expression, but an easier way is to type
<tt>^J</tt>, which forces the expression to be entered immediately
no matter where the cursor is.

<p>
Finally, we can bring back <tt>(fact&nbsp;6)</tt> with another two
hits of the up-arrow key and try it again:

<p>

<p><tt>&gt;&nbsp;(fact&nbsp;6)<br>

720</tt>
<p>To exit from the REPL and return back to the shell, we can type
<tt>^D</tt> or call the <tt>exit</tt> procedure.

<p>
The interaction described above uses just a few of the expeditor's
features.
The expeditor's remaining features are described in the following
section.

<p>
Running programs may be interrupted by typing the interrupt
character (typically <tt>^C</tt>).
In response, the
system enters a debug handler, which prompts for input with a
<tt>break&gt;</tt> prompt.
One of several commands may be issued to the break handler (followed by a
newline), including
<dl compact>
<dt>"e"<dd> or end-of-file to exit from the handler and continue,
<dt>"r"<dd> to stop execution and reset to the current caf&eacute;,
<dt>"a"<dd> to abort <i>Chez&nbsp;Scheme</i>,
<dt>"n"<dd> to enter a new caf&eacute; (see below),
<dt>"i"<dd> to inspect the current continuation,
<dt>"s"<dd> to display statistics about the interrupted program, and
<dt>"?"<dd> to display a list of these options.
</dl>

<p>
When an exception other than a warning occurs, the default exception
handler prints a message that describes the exception to the console
error port.
If a REPL is running, the exception handler then returns to the REPL,
where the programmer can call the <tt>debug</tt> procedure to start up the
debug handler, if desired.
The debug handler is similar to the break handler and allows the
programmer to inspect the continuation (control
stack) of the exception to help determine the cause of the problem.
If no REPL is running, as is the case for a script or top-level program
run via the <a name="./use:s0"></a><tt>--script</tt>
or <a name="./use:s1"></a><tt>--program</tt>
command-line options, the default exception handler exits from the script
or program after printing the message.
To allow scripts and top-level programs to be debugged,
the default exception handler can be forced via the
<a name="./use:s2"></a><tt>debug-on-exception</tt>
parameter or the
<a name="./use:s3"></a><tt>--debug-on-exception</tt> command-line option
to invoke <tt>debug</tt> directly.

<p>
Developing a large program entirely in the REPL is unmanageable, and we
usually even want to store smaller programs in a file for future use.
(The expeditor's history is saved across Scheme sessions, but there is a
limit on the number of items, so it is not a good idea to count on a
program remaining in the history indefinitely.)
Thus, a Scheme programmer typically creates a file containing Scheme
source code using a text editor, such as <tt>vi</tt>, and loads the file
into <i>Chez&nbsp;Scheme</i> to test them.
The conventional filename extension for <i>Chez&nbsp;Scheme</i> source files is
"<tt>.ss</tt>," but the file can have any extension or even no extension
at all.
A source file can be loaded during an interactive session by typing
<a name="./use:s4"></a><tt>(load&nbsp;"<i>path</i>")</tt>.
Files to be loaded can also be named on the command line when the
system is started.
Any form that can be typed interactively can be placed in a file to be loaded.

<p>
<i>Chez&nbsp;Scheme</i> compiles source forms as it sees them to machine
code before evaluating them, i.e., "just in time."
In order to speed loading of a large file or group of files, each file
can be compiled ahead of time via
<a name="./use:s5"></a><tt>compile-file</tt>, which puts the
compiled code into a separate object file.
For example, <tt>(compile-file&nbsp;"<i>path</i>")</tt> compiles
the forms in the file <tt><i>path</i></tt>.ss and places the
resulting object code in the file <tt><i>path</i></tt>.so.
Loading a pre-compiled file is essentially no different from
loading the source file, except that loading is faster since
compilation has already been done.

<p>
<a name="./use:s6"></a>When compiling a file or set of files, it is often more convenient to
use a shell command than to enter <i>Chez&nbsp;Scheme</i> interactively to perform
the compilation.
This is easily accomplished by "piping" in the command to compile
the file as shown below.

<p>

<p><tt>echo&nbsp;'(compile-file&nbsp;"<i>filename</i>")'&nbsp;|&nbsp;scheme&nbsp;-q</tt>
<p>The <tt>-q</tt> option suppresses the system's greeting messages for more
compact output, which is especially useful when compiling numerous
files.
The single-quote marks surrounding the <tt>compile-file</tt> call
should be left off for Windows shells.

<p>
When running in this "batch" mode, especially from within "make"
files, it is often desirable to force the default exception handler to exit
immediately to the shell with a nonzero exit status.
This may be accomplished by setting the
<a name="./use:s7"></a><tt>reset-handler</tt> to
<tt>abort</tt>.

<p>

<p><tt>echo&nbsp;'(reset-handler&nbsp;abort)&nbsp;(compile-file&nbsp;"<i>filename</i>")'&nbsp;|&nbsp;scheme&nbsp;-q</tt>
<p>One can also redefine the
<a name="./use:s8"></a><tt>base-exception-handler</tt>
(Section&nbsp;<a href="./system.html#g108">12.1</a>) to achieve a similar effect
while exercising more control over the format of the messages that
are produced.


<p>

<h3><a name="g7"></a><a name="./use:h2"></a>Section 2.2. Expression Editor<a name="SECTUSEEXPEDITOR"></a></h3>


<p>
When Chez Scheme is used interactively in a shell window, as described
above, or when <tt>new-cafe</tt> is invoked explicitly from a top-level
program or script run via <tt>--program</tt> or <tt>--script</tt>, the
waiter's "prompt and read" procedure employs an expression editor that
permits entry and editing of single- and multiple-line expressions,
automatically indents expressions as they are entered, supports
identifier completion outside string constants based on the identifiers defined
in the interactive environment, and supports filename completion within
string constants.
The expression editor also maintains a history of expressions typed during
and across sessions and supports tcsh-like history movement and search
commands.
Other editing commands include simple cursor movement via
arrow keys, deletion of characters via backspace and delete, and
movement, deletion, and other commands using mostly
emacs key bindings.

<p>
The expression editor does not run if the TERM environment variable is not
set (on Unix-based systems), if the standard input or output files have
been redirected, or if the <tt>--eedisable</tt> command-line option
(Section&nbsp;<a href="./use.html#g14">2.9</a>) has been used.
The history is saved across sessions, by default, in the file
".chezscheme_history" in the user's home directory.
The <tt>--eehistory</tt> command-line option
(Section&nbsp;<a href="./use.html#g14">2.9</a>) can be used to specify a different
location for the history file or to disable the saving and restoring of
the history file.

<p>
Keys for nearly all printing characters (letters, digits, and special
characters) are "self inserting" by default.
The open parenthesis, close parenthesis, open bracket, and close bracket
keys are self inserting as well, but also cause the editor to "flash"
to the matching delimiter, if any.
Furthermore, when a close parenthesis or close bracket is typed, it is
automatically corrected to match the corresponding open delimiter, if any.

<p>
Key bindings for other keys and key sequences initially recognized by
the expression editor are given below, organized into groups by function.
Some keys or key sequences serve more than one purpose depending upon
context.
For example, tab is used for identifier completion, filename completion,
and indentation.
Such bindings are shown in each applicable functional group.

<p>
Multiple-key sequences are displayed with hyphens between the keys of
the sequences, but these hyphens should not be entered.
When two or more key sequences perform the same operation, the sequences
are shown separated by commas.

<p>
Detailed descriptions of the editing commands are given in
Chapter&nbsp;<a href="./expeditor.html#g128">14</a>, which also describes parameters that allow
control over the expression editor, mechanisms for adding or changing key
bindings, and mechanisms for creating new commands.


<p>


<p>
<p> Newlines, acceptance, exiting, and redisplay:
<p><TABLE><TR><TD nowrap align="left">
enter, <tt>^M</tt>        </TD><TD nowrap align="left"> accept balanced entry if used at end of entry;</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> else add a newline before the cursor and indent</TD></TR><TR><TD nowrap align="left">
<tt>^J</tt>               </TD><TD nowrap align="left"> accept entry unconditionally</TD></TR><TR><TD nowrap align="left">
<tt>^O</tt>               </TD><TD nowrap align="left"> insert newline after the cursor and indent</TD></TR><TR><TD nowrap align="left">
<tt>^D</tt>               </TD><TD nowrap align="left"> exit from the waiter if entry is empty;</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> else delete character under cursor</TD></TR><TR><TD nowrap align="left">
<tt>^Z</tt>               </TD><TD nowrap align="left"> suspend to shell if shell supports job control</TD></TR><TR><TD nowrap align="left">
<tt>^L</tt>               </TD><TD nowrap align="left"> redisplay entry</TD></TR><TR><TD nowrap align="left">
<tt>^L</tt>-<tt>^L</tt>      </TD><TD nowrap align="left"> clear screen and redisplay entry
</TD></TR></TABLE>
<p>

<p>
 Basic movement and deletion:
<p><TABLE><TR><TD nowrap align="left">
leftarrow, <tt>^B</tt>    </TD><TD nowrap align="left"> move cursor left</TD></TR><TR><TD nowrap align="left">
rightarrow, <tt>^F</tt>   </TD><TD nowrap align="left"> move cursor right</TD></TR><TR><TD nowrap align="left">
uparrow, <tt>^P</tt>      </TD><TD nowrap align="left"> move cursor up; from top of unmodified entry,</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> move to preceding history entry.</TD></TR><TR><TD nowrap align="left">
downarrow, <tt>^N</tt>    </TD><TD nowrap align="left"> move cursor down; from bottom of unmodified entry,</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> move to next history entry</TD></TR><TR><TD nowrap align="left">
<tt>^D</tt>               </TD><TD nowrap align="left"> delete character under cursor if entry not empty,</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> else exit from the waiter</TD></TR><TR><TD nowrap align="left">
backspace, <tt>^H</tt>    </TD><TD nowrap align="left"> delete character before cursor</TD></TR><TR><TD nowrap align="left">
delete                 </TD><TD nowrap align="left"> delete character under cursor
</TD></TR></TABLE>
<p>

<p>
 Line movement and deletion:
<p><TABLE><TR><TD nowrap align="left">
home, <tt>^A</tt>         </TD><TD nowrap align="left"> move cursor to beginning of line</TD></TR><TR><TD nowrap align="left">
end, <tt>^E</tt>          </TD><TD nowrap align="left"> move cursor to end of line</TD></TR><TR><TD nowrap align="left">
<tt>^K</tt>,
esc-k                  </TD><TD nowrap align="left"> delete to end of line or, if cursor is at the end</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> of a line, join with next line</TD></TR><TR><TD nowrap align="left">
<tt>^U</tt>               </TD><TD nowrap align="left"> delete contents of current line
</TD></TR></TABLE>
<p>

<p>
When used on the first line of a multiline entry of which only the first line
is displayed, i.e., immediately after history movement, <tt>^U</tt> deletes the
contents of the entire entry, like <tt>^G</tt> (described below).

<p>
 Expression movement and deletion:
<p><TABLE><TR><TD nowrap align="left">
esc-<tt>^F</tt>           </TD><TD nowrap align="left"> move cursor to next expression</TD></TR><TR><TD nowrap align="left">
esc-<tt>^B</tt>           </TD><TD nowrap align="left"> move cursor to preceding expression</TD></TR><TR><TD nowrap align="left">
esc-<tt>]</tt>         </TD><TD nowrap align="left"> move cursor to matching delimiter</TD></TR><TR><TD nowrap align="left">
<tt>^]</tt>               </TD><TD nowrap align="left"> flash cursor to matching delimiter</TD></TR><TR><TD nowrap align="left">
esc-<tt>^K</tt>,
esc-delete             </TD><TD nowrap align="left"> delete next expression</TD></TR><TR><TD nowrap align="left">
esc-backspace,
esc-<tt>^H</tt>           </TD><TD nowrap align="left"> delete preceding expression
</TD></TR></TABLE>
<p>

<p>
 Entry movement and deletion:
<p><TABLE><TR><TD nowrap align="left">
esc-<tt>&lt;</tt>         </TD><TD nowrap align="left"> move cursor to beginning of entry</TD></TR><TR><TD nowrap align="left">
esc-<tt>&gt;</tt>         </TD><TD nowrap align="left"> move cursor to end of entry</TD></TR><TR><TD nowrap align="left">
<tt>^G</tt>               </TD><TD nowrap align="left"> delete current entry contents</TD></TR><TR><TD nowrap align="left">
<tt>^C</tt>               </TD><TD nowrap align="left"> delete current entry contents; reset to end of history
</TD></TR></TABLE>
<p>

<p>
 Indentation:
<p><TABLE><TR><TD nowrap align="left">
tab                    </TD><TD nowrap align="left"> re-indent current line if identifier/filename prefix</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> not just entered; else insert completion</TD></TR><TR><TD nowrap align="left">
esc-tab                </TD><TD nowrap align="left"> re-indent current line unconditionally</TD></TR><TR><TD nowrap align="left">
esc-<tt>q</tt>,
 esc-<tt>Q</tt>,
 esc-<tt>^Q</tt>          </TD><TD nowrap align="left"> re-indent each line of entry
</TD></TR></TABLE>
<p>

<p>
 Identifier/filename completion:
<p><TABLE><TR><TD nowrap align="left">
tab                    </TD><TD nowrap align="left"> insert completion if identifier/filename prefix just</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> entered; else re-indent current line</TD></TR><TR><TD nowrap align="left">
tab-tab                </TD><TD nowrap align="left"> show possible identifier/filename completions at end</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> of identifier/filename just typed, else re-indent</TD></TR><TR><TD nowrap align="left">
<tt>^R</tt>               </TD><TD nowrap align="left"> insert next identifier/filename completion
</TD></TR></TABLE>
<p>

<p>
Identifier completion is performed outside of a string constant, and filename
completion is performed within a string constant.
(In determining whether the cursor is within a string constant, the
expression editor looks only at the current line and so can be fooled
by string constants that span multiple lines.)
If at end of existing identifier or filename, i.e., not one just typed, the first tab
re-indents, the second tab inserts identifier completion, and the third
shows possible completions.

<p>
 History movement:
<p><TABLE><TR><TD nowrap align="left">
uparrow, <tt>^P</tt>      </TD><TD nowrap align="left"> move to preceding entry if at top of unmodified</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> entry; else move up within entry</TD></TR><TR><TD nowrap align="left">
downarrow, <tt>^N</tt>    </TD><TD nowrap align="left"> move to next entry if at bottom of unmodified</TD></TR><TR><TD nowrap align="left">
                       </TD><TD nowrap align="left"> entry; else move down within entry</TD></TR><TR><TD nowrap align="left">
esc-uparrow,
 esc-<tt>^P</tt>          </TD><TD nowrap align="left"> move to preceding entry from unmodified entry</TD></TR><TR><TD nowrap align="left">
esc-downarrow,
 esc-<tt>^N</tt>          </TD><TD nowrap align="left"> move to next entry from unmodified entry</TD></TR><TR><TD nowrap align="left">
esc-p                  </TD><TD nowrap align="left"> search backward through history for given prefix</TD></TR><TR><TD nowrap align="left">
esc-n                  </TD><TD nowrap align="left"> search forward through history for given prefix</TD></TR><TR><TD nowrap align="left">
esc-P                  </TD><TD nowrap align="left"> search backward through history for given string</TD></TR><TR><TD nowrap align="left">
esc-N                  </TD><TD nowrap align="left"> search forward through history for given string
</TD></TR></TABLE>
<p>

<p>
To search, enter a prefix or string followed by one of the search key
sequences.
Follow with additional search key sequences to search further backward or
forward in the history.
For example, enter "(define" followed by one or more esc-p key sequences
to search backward for entries that are definitions, or "(define"
followed by one or more esc-P key sequences for entries that contain
definitions.

<p>
 Word and page movement:
<p><TABLE><TR><TD nowrap align="left">
esc-<tt>f</tt>,
  esc-<tt>F</tt>       </TD><TD nowrap align="left"> move cursor to end of next word</TD></TR><TR><TD nowrap align="left">
esc-<tt>b</tt>,
  esc-<tt>B</tt>       </TD><TD nowrap align="left"> move cursor to start of preceding word</TD></TR><TR><TD nowrap align="left">
<tt>^X</tt>-<tt>[</tt>    </TD><TD nowrap align="left"> move cursor up one screen page</TD></TR><TR><TD nowrap align="left">
<tt>^X</tt>-<tt>]</tt>    </TD><TD nowrap align="left"> move cursor down one screen page
</TD></TR></TABLE>
<p>

<p>
 Inserting saved text:
<p><TABLE><TR><TD nowrap align="left">
<tt>^Y</tt>               </TD><TD nowrap align="left"> insert most recently deleted text</TD></TR><TR><TD nowrap align="left">
<tt>^V</tt>               </TD><TD nowrap align="left"> insert contents of window selection/paste buffer
</TD></TR></TABLE>
<p>

<p>
 Mark operations:
<p><TABLE><TR><TD nowrap align="left">
<tt>^@</tt>,
  <tt>^</tt>space,
  <tt>^^</tt>             </TD><TD nowrap align="left"> set mark to current cursor position</TD></TR><TR><TD nowrap align="left">
<tt>^X</tt>-<tt>^X</tt>      </TD><TD nowrap align="left"> move cursor to mark, leave mark at old cursor position</TD></TR><TR><TD nowrap align="left">
<tt>^W</tt>               </TD><TD nowrap align="left"> delete between current cursor position and mark
</TD></TR></TABLE>
<p>

<p>
 Command repetition:
<p><TABLE><TR><TD nowrap align="left">
esc-<tt>^U</tt>           </TD><TD nowrap align="left"> repeat next command four times</TD></TR><TR><TD nowrap align="left">
esc-<tt>^U</tt>-<i>n</i>       </TD><TD nowrap align="left"> repeat next command <i>n</i> times
</TD></TR></TABLE>
<p>


<p>

<h3><a name="g8"></a><a name="./use:h3"></a>Section 2.3. The Interaction Environment<a name="SECTUSEINTERACTIONENVIRONMENT"></a></h3>


<p>
<a name="./use:s9"></a><a name="./use:s10"></a><a name="./use:s11"></a>In the language of the Revised<sup>6</sup> Report, code is structured into
libraries and "top-level programs."
The Revised<sup>6</sup> Report does not require an implementation to support
interactive use, and it does not specify how an interactive top level
should operate, leaving such details up to the implementation.

<p>
In <i>Chez&nbsp;Scheme</i>, when one enters definitions or expressions at the
prompt or loads them from a file, they operate on an
interaction environment, which is a mutable environment that initially
holds bindings only for built-in keywords and primitives.
It may be augmented by user-defined identifier bindings via top-level
definitions.
The interaction environment is also referred to as the top-level
environment, because it is at the top level for purposes of scoping.
Programs entered at the prompt or loaded from a file via <tt>load</tt>
should not be confused with RNRS top-level programs, which are
actually more similar to libraries in their behavior.
In particular, while the same identifier can be defined multiple times
in the interaction environment, to support incremental program
development, an identifier can be defined at most once in an RNRS
top-level program.

<p>
The default interaction environment used for any code that occurs outside
of an RNRS top-level program or library (including such code typed at
a prompt or loaded from a file) contains all of the bindings of the
<tt>(chezscheme)</tt> library (or <tt>scheme</tt> module, which exports the
same set of bindings).
This set contains a number of bindings that are not in the RNRS libraries.
It also contains a number of bindings that extend the RNRS counterparts in
some way and are thus not strictly compatible with the RNRS bindings for
the same identifiers.
To replace these with bindings strictly compatible with RNRS, simply
import the <tt>rnrs</tt> libraries into the interaction environment by
typing the following into the REPL or loading it from a file:

<p>

<p><tt>(import<br>

&nbsp;&nbsp;(rnrs)<br>

&nbsp;&nbsp;(rnrs&nbsp;eval)<br>

&nbsp;&nbsp;(rnrs&nbsp;mutable-pairs)<br>

&nbsp;&nbsp;(rnrs&nbsp;mutable-strings)<br>

&nbsp;&nbsp;(rnrs&nbsp;r5rs))</tt>
<p><a name="./use:s12"></a>To obtain an interaction environment that contains all <i>and only</i>
RNRS bindings, use the following.

<p>

<p><tt>(interaction-environment<br>

&nbsp;&nbsp;(copy-environment<br>

&nbsp;&nbsp;&nbsp;&nbsp;(environment<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;eval)&nbsp;<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;mutable-pairs)&nbsp;<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;mutable-strings)&nbsp;<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;r5rs))<br>

&nbsp;&nbsp;&nbsp;&nbsp;#t))</tt>
<p>To be useful for most purposes, <tt>library</tt> and <tt>import</tt>
should probably also be included, from the <tt>(chezscheme)</tt> library.

<p>

<p><tt>(interaction-environment<br>

&nbsp;&nbsp;(copy-environment<br>

&nbsp;&nbsp;&nbsp;&nbsp;(environment<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;eval)&nbsp;<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;mutable-pairs)&nbsp;<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;mutable-strings)&nbsp;<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(rnrs&nbsp;r5rs)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'(only&nbsp;(chezscheme)&nbsp;library&nbsp;import))<br>

&nbsp;&nbsp;&nbsp;&nbsp;#t))</tt>
<p>It might also be useful to include <tt>debug</tt> in the set of
identifiers imported from <tt>(chezscheme)</tt> to allow the debugger to be
entered after an exception is raised.

<p>
Most of the identifiers bound in the default interaction environment that
are not strictly compatible with the Revised<sup>6</sup> Report are variables bound to
procedures with extended interfaces, i.e., optional arguments or extended
argument domains.
The others are keywords bound to transformers that extend the Revised<sup>6</sup>
Report syntax in some way.
This should not be a problem except for programs that count on
exceptions being raised in cases that coincide with the extensions.
For example, if a program passes the <tt>=</tt> procedure a single numeric
argument and expects an exception to be raised, it will fail in the
initial interaction environment because <tt>=</tt> returns <tt>#t</tt>
when passed a single numeric argument.

<p>
Within the default interaction environment and those created as described
above, variables that name built-in procedures are read-only, i.e.,
cannot be assigned, since they resolve to the read-only bindings exported
from the <tt>(chezscheme)</tt> library or some other library:

<p>

<p><tt>(set!&nbsp;cons&nbsp;+)&nbsp;<img src="math/csug/0.gif" alt="<graphic>">&nbsp;<i>exception:&nbsp;cons&nbsp;is&nbsp;immutable</i></tt>
<p>Before assigning a variable bound to the name of a built-in
procedure, the programmer must first define the variable.
For example,

<p>

<p><tt>(define&nbsp;cons-count&nbsp;0)<br>

(define&nbsp;original-cons&nbsp;cons)<br>

(define&nbsp;cons<br>

&nbsp;&nbsp;(lambda&nbsp;(x&nbsp;y)<br>

&nbsp;&nbsp;&nbsp;&nbsp;(set!&nbsp;cons-count&nbsp;(+&nbsp;cons-count&nbsp;1))<br>

&nbsp;&nbsp;&nbsp;&nbsp;(original-cons&nbsp;x&nbsp;y)))</tt>
<p>redefines <tt>cons</tt> to count the number of times it is called, and

<p>

<p><tt>(set!&nbsp;cons&nbsp;original-cons)</tt>
<p>assigns <tt>cons</tt> to its original value.
Once a variable has been defined in the interaction environment using
<tt>define</tt>, a subsequent definition of the same variable is equivalent
to a <tt>set!</tt>, so

<p>

<p><tt>(define&nbsp;cons&nbsp;original-cons)</tt>
<p>has the same effect as the <tt>set!</tt> above.
The expression

<p>

<p><tt>(import&nbsp;(only&nbsp;(chezscheme)&nbsp;cons))</tt>
<p>also binds <tt>cons</tt> to its original value.
It also returns it to its original read-only state.

<p>
The simpler redefinition

<p>

<p><tt>(define&nbsp;cons&nbsp;(let&nbsp;()&nbsp;(import&nbsp;scheme)&nbsp;cons))</tt>
<p>turns <tt>cons</tt> into a mutable variable with the same value as it
originally had.
Doing so, however, prevents the compiler from generating efficient code
for calls to <tt>cons</tt> or producing warning messages when
<tt>cons</tt> is passed the wrong number of arguments.

<p>
All identifiers not bound in the initial interaction environment and
not defined by the programmer are treated as "potentially bound" as
variables to facilitate the definition of mutually recursive
procedures.
For example, assuming that <tt>yin</tt> and <tt>yang</tt> have not
been defined,

<p>

<p><tt>(define&nbsp;yin&nbsp;(lambda&nbsp;()&nbsp;(-&nbsp;(yang)&nbsp;1)))</tt>
<p>defines <tt>yin</tt> at top level as a variable to a procedure that calls
the value of the top-level variable <tt>yang</tt>, even though <tt>yang</tt>
has not yet been defined.
If this is followed by

<p>

<p><tt>(define&nbsp;yang&nbsp;(lambda&nbsp;()&nbsp;(+&nbsp;(yin)&nbsp;1)))</tt>
<p>the result is a mutually recursive pair of procedures that, when called,
will loop indefinitely or until the system runs out of space to hold the
recursion stack.
If <tt>yang</tt> must be defined as anything other than a variable, its
definition should precede the definition of <tt>yin</tt>, since the compiler
assumes <tt>yang</tt> is a variable in the absence of any indication to
the contrary when <tt>yang</tt> has not yet been defined.

<p>
<a name="./use:s13"></a>A subtle consequence of this useful quirk of the interaction environment is that
the procedure
<tt>free-identifier=?</tt> (Section&nbsp;<a href="http://scheme.com/tspl4/./syntax.html#g136">8.3</a> of <i>The Scheme Programming Language, 4th Edition</i>)
does not consider unbound library identifiers to be equivalent to (as yet)
undefined top-level identifiers, even if they have the
same name, because the latter are actually assumed to be valid variable bindings.

<p>

<p><tt>(library&nbsp;(A)&nbsp;(export&nbsp;a)<br>

&nbsp;&nbsp;(import&nbsp;(rnrs))<br>

&nbsp;&nbsp;(define-syntax&nbsp;a<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(x)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax-case&nbsp;x&nbsp;()<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(_&nbsp;id)&nbsp;(free-identifier=?&nbsp;#'id&nbsp;#'undefined)]))))<br>

(let&nbsp;()&nbsp;(import&nbsp;(A))&nbsp;(a&nbsp;undefined))&nbsp;<img src="math/csug/0.gif" alt="<graphic>">&nbsp;#f</tt>
<p><a name="./use:s14"></a>If it is necessary that they have the same binding, as in the case where
an identifier is used as an auxiliary keyword in a syntactic abstraction
exported from a library and used at top level, the library should define
and export a binding for the identifier.

<p>

<p><tt>(library&nbsp;(A)&nbsp;(export&nbsp;a&nbsp;aux-a)<br>

&nbsp;&nbsp;(import&nbsp;(rnrs)&nbsp;(only&nbsp;(chezscheme)&nbsp;syntax-error))<br>

&nbsp;&nbsp;(define-syntax&nbsp;aux-a<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(x)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax-error&nbsp;x&nbsp;"invalid&nbsp;context")))<br>

&nbsp;&nbsp;(define-syntax&nbsp;a<br>

&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(x)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(syntax-case&nbsp;x&nbsp;(aux-a)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(_&nbsp;aux-a)&nbsp;#''okay]<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[(_&nbsp;_)&nbsp;#''oops]))))<br>

(let&nbsp;()&nbsp;(import&nbsp;(A))&nbsp;(a&nbsp;aux-a))&nbsp;<img src="math/csug/0.gif" alt="<graphic>">&nbsp;okay<br>

(let&nbsp;()&nbsp;(import&nbsp;(only&nbsp;(A)&nbsp;a))&nbsp;(a&nbsp;aux-a))&nbsp;<img src="math/csug/0.gif" alt="<graphic>">&nbsp;oops</tt>
<p>This issue does not arise when libraries are used entirely within other
libraries or within RNRS top-level programs, since the interaction
environment does not come into play.


<p>

<h3><a name="g9"></a><a name="./use:h4"></a>Section 2.4. Using Libraries and Top-Level Programs<a name="SECTUSELIBRARIES"></a></h3>


<p>
<a name="./use:s15"></a><a name="./use:s16"></a>An R6RS library can be defined directly in the REPL, loaded explicitly
from a file (using <tt>load</tt> or <tt>load-library</tt>), or loaded
implicitly from a file via <tt>import</tt>.
When defined directly in the REPL or loaded explicitly from a file, a
library form can be used to redefine an existing library, but
<tt>import</tt> never reloads a library once it has been defined.

<p>
A library to be loaded implicitly via <tt>import</tt>
must reside in a file whose name reflects the name of the library.
For example, if the library's name is <tt>(tools&nbsp;sorting)</tt>, the
base name of the file must be <tt>sorting</tt> with a valid extension, and
the file must be in a directory named <tt>tools</tt> which itself resides
in one of the directories searched by <tt>import</tt>.
The set of directories searched by <tt>import</tt> is determined by
the
<a name="./use:s17"></a><tt>library-directories</tt>
parameter, and the set of
extensions is determined by the
<a name="./use:s18"></a><tt>library-extensions</tt>
parameter.

<p>
The values of both parameters are lists of pairs of strings.
The first string in each <tt>library-directories</tt> pair identifies a
source-file base directory, and the second identifies the corresponding
object-file base directory.
Similarly, the first string in each <tt>library-extensions</tt> pair
identifies a source-file extension, and the second identifies the
corresponding object-file extension.
The full path of a library source or object file consists of the source or
object base followed by the components of the library name, separated by
slashes, with the library extension added on the end.
For example, for base <tt>/usr/lib/scheme</tt>, library name
<tt>(app&nbsp;lib1)</tt>, and extension <tt>.sls</tt>, the full path is
<tt>/usr/lib/scheme/app/lib1.sls</tt>.
So, if <tt>(library-directories)</tt> contains the pathnames
<tt>"/usr/lib/scheme/libraries"</tt> and <tt>"."</tt>, and
<tt>(library-extensions)</tt> contains the extensions <tt>.ss</tt>
and <tt>.sls</tt>, the path of the <tt>(tools&nbsp;sorting)</tt>
library must be one of the following.

<p>

<p><tt>/usr/lib/scheme/libraries/tools/sorting.ss<br>

/usr/lib/scheme/libraries/tools/sorting.sls<br>

./tools/sorting.ss<br>

./tools/sorting.sls</tt>
<p>When searching for a library, <tt>import</tt> first constructs a partial
name from the list of components in the library name, e.g., <tt>a/b</tt>
for library <tt>(a&nbsp;b)</tt>.
It then searches for the partial name in each pair
of base directories, in order, trying each of the source extensions then
each of the object extensions in turn before moving onto the next pair of
base directories.
If the partial name is an absolute pathname, e.g., <tt>~/.myappinit</tt>
for a library named <tt>(~/.myappinit)</tt>, only the specified absolute
path is searched, first with each source extension, then with each object
extension.
If the expander finds both a source file and its corresponding object
file, and the object file is not older than the source file, the
expander loads the object file.
If the object file does not exist, if the object file is older, or
if after loading the object file, the expander determines it was
built using a library or include file that has changed, the source
file is loaded or compiled, depending on the value of the parameter
<a name="./use:s19"></a><tt>compile-imported-libraries</tt>.
If <tt>compile-imported-libraries</tt>
is set to <tt>#t</tt>, the expander
compiles the library via the value of the <tt>compile-library-handler</tt>
parameter, which by default calls <tt>compile-library</tt> (which is described below).
Otherwise, the expander loads the source file.
(Loading the source file actually causes the code to be compiled,
assuming the default value of <tt>current-eval</tt>, but the compiled
code is not saved to an object file.)
An exception is raised during this process if a
source or object file exists but is not readable or if an object
file cannot be created.

<p>
<a name="./use:s20"></a><a name="./use:s21"></a>The search process used by the expander when processing an <tt>import</tt>
for a library that has not yet been loaded can be monitored by
setting the parameter <tt>import-notify</tt> to <tt>#t</tt>.
This parameter can be set from the command line via the
<tt>--import-notify</tt> command-line option.

<p>
Whenever the expander determines it must compile a library to a file or
load one from source, it adds the directory in which the file resides to
the front of the
<a name="./use:s22"></a><tt>source-directories</tt>
list while compiling or loading the library.
This allows a library to include files stored in or relative to its
own directory.

<p>
When <tt>import</tt> compiles a library as described above, it does not
also load the compiled library, because this would cause portions of
library to be reevaluated.
Because of this, run-time expressions in the file outside of a
<tt>library</tt> form will not be evaluated.
If such expressions are present and should be evaluated, the library
should be compiled ahead of time or loaded explicitly.

<p>
<a name="./use:s23"></a><a name="./use:s24"></a>A file containing a library may be compiled with <tt>compile-file</tt>
or <tt>compile-library</tt>.
The only difference between the two is that the latter treats the source
file as if it were prefixed by an implicit <tt>#!r6rs</tt>, which
disables <i>Chez&nbsp;Scheme</i> lexical extensions unless an explicit
<tt>#!chezscheme</tt> marker appears in the file.
Any libraries upon which the library depends must be compiled first.
If one of the libraries imported by the library is subsequently
recompiled (say because it was modified), the importing library must also
be recompiled.
Compilation and recompilation of imported libraries must be done
explicitly by default but is done automatically when the parameter
<tt>compile-imported-libraries</tt> is set to <tt>#t</tt> before
compiling the importing library.

<p>
As with <tt>compile-file</tt>, <tt>compile-library</tt> can be used
in "batch" mode via a shell command:

<p>

<p><tt>echo&nbsp;'(compile-library&nbsp;"<i>filename</i>")'&nbsp;|&nbsp;scheme&nbsp;-q</tt>
<p>with single-quote marks surrounding the <tt>compile-library</tt> call
omitted for Windows shells.

<p>
An RNRS top-level-program usually resides in a file, but one can also
enter one directly into the REPL using the <tt>top-level-program</tt>
forms, e.g.:

<p>

<p><tt>(top-level-program<br>

&nbsp;&nbsp;(import&nbsp;(rnrs))<br>

&nbsp;&nbsp;(display&nbsp;"What's&nbsp;up?\n"))</tt>
<p>A top-level program stored in a file does not have the <tt>top-level-program</tt>
wrapper, so the same top-level program in a file is just:

<p>

<p><tt>(import&nbsp;(rnrs))<br>

(display&nbsp;"What's&nbsp;up?\n")</tt>
<p>A top-level program stored in a file can be loaded from the file via the
<tt>load-program</tt> procedure.
A top-level program can also be loaded via <tt>load</tt>, but not without
affecting the semantics.
A program loaded via <tt>load</tt> is scoped at top level, where it can
see all top-level bindings, whereas a top-level program loaded via
<tt>load-program</tt> is self-contained, i.e., it can see only the
bindings made visible by the leading <tt>import</tt> form.
Also, the variable bindings in a program loaded via <tt>load</tt> also
become top-level bindings, whereas they are local to the program when
the program is loaded via <tt>load-program</tt>.
Moreover, <tt>load-program</tt>, like <tt>load-library</tt>, treats the
source file as if it were prefixed by an implicit <tt>#!r6rs</tt>, which
disables <i>Chez&nbsp;Scheme</i> lexical extensions unless an explicit
<tt>#!chezscheme</tt> marker appears in the file.
A program loaded via <tt>load</tt> is also likely to be less efficient. 
Since the program's variables are not local to the program, the compiler
must assume they could change at any time, which inhibits many of its
optimizations.

<p>
<a name="./use:s25"></a>Top-level programs may be compiled using
<a name="./use:s26"></a><tt>compile-program</tt>, which is like
<tt>compile-file</tt> but, as with <tt>load-program</tt>, properly
implements the semantics and lexical restrictions of top-level programs.
<tt>compile-program</tt> also copies the leading <tt>#!</tt> line,
if any, from the source file to the object file, resulting in an
executable object file.
Any libraries upon which the top-level program depends, other than
built-in libraries, must be compiled first.
The program must be recompiled if any of the libraries upon which
it depends are recompiled.
Compilation and recompilation of imported libraries must be done
explicitly by default but is done automatically when the parameter
<tt>compile-imported-libraries</tt> is set to <tt>#t</tt> before
compiling the importing library.

<p>
As with <tt>compile-file</tt> and <tt>compile-library</tt>,
<tt>compile-program</tt> can be used in "batch" mode via a shell
command:

<p>

<p><tt>echo&nbsp;'(compile-program&nbsp;"<i>filename</i>")'&nbsp;|&nbsp;scheme&nbsp;-q</tt>
<p>with single-quote marks surrounding the <tt>compile-program</tt> call
omitted for Windows shells.

<p>
<tt>compile-program</tt> returns a list of libraries directly invoked by
the compiled top-level program. 
When combined with the
<a name="./use:s27"></a><tt>library-requirements</tt> and
<a name="./use:s28"></a><tt>library-object-filename</tt>
procedures, the list of libraries returned by <tt>compile-program</tt> can
be used to determine the set of files that must be distributed with the
compiled program file.

<p>
When run, a compiled program automatically loads the run-time code for
each library upon which it depends, as if via <tt>revisit</tt>.
If the program also imports one of the same libraries at run time, e.g.,
via the <tt>environment</tt> procedure, the system will attempt to load
the compile-time information from the same file.
The compile-time information can also be loaded explicitly from the
same or a different file via <tt>load</tt> or <tt>visit</tt>.

<p>

<h3><a name="g10"></a><a name="./use:h5"></a>Section 2.5. Scheme Shell Scripts<a name="SECTUSESCRIPTING"></a></h3>


<p>
<a name="./use:s29"></a><a name="./use:s30"></a><a name="./use:s31"></a>When the <tt>--script</tt> command-line option is present, the named file is
treated as a Scheme shell script, and the command-line is made
available via the parameter
<tt>command-line</tt>.
This is primarily useful on Unix-based systems, where the script file
itself may be made executable.
To support executable shell scripts, the system ignores the first
line of a loaded script if it begins with <tt>#!</tt> followed by
a space or forward slash.
For example, assuming that the <i>Chez&nbsp;Scheme</i> executable has been
installed as /usr/bin/scheme, the following script prints its command-line
arguments.

<p>

<p><tt>#!&nbsp;/usr/bin/scheme&nbsp;--script<br>

(for-each<br>

&nbsp;&nbsp;(lambda&nbsp;(x)&nbsp;(display&nbsp;x)&nbsp;(newline))<br>

&nbsp;&nbsp;(cdr&nbsp;(command-line)))</tt>
<p>The following script implements the traditional Unix <tt>echo</tt>
command.

<p>

<p><tt>#!&nbsp;/usr/bin/scheme&nbsp;--script<br>

(let&nbsp;([args&nbsp;(cdr&nbsp;(command-line))])<br>

&nbsp;&nbsp;(unless&nbsp;(null?&nbsp;args)<br>

&nbsp;&nbsp;&nbsp;&nbsp;(let-values&nbsp;([(newline?&nbsp;args)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(equal?&nbsp;(car&nbsp;args)&nbsp;"-n")<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(values&nbsp;#f&nbsp;(cdr&nbsp;args))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(values&nbsp;#t&nbsp;args))])<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(do&nbsp;([args&nbsp;args&nbsp;(cdr&nbsp;args)]&nbsp;[sep&nbsp;""&nbsp;"&nbsp;"])<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((null?&nbsp;args))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(printf&nbsp;"~a~a"&nbsp;sep&nbsp;(car&nbsp;args)))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(when&nbsp;newline?&nbsp;(newline)))))</tt>
<p>Scripts may be compiled using <a name="./use:s32"></a><tt>compile-script</tt>, which is like
<tt>compile-file</tt> but differs in two ways:
(1) it copies the leading <tt>#!</tt> line from the source-file script
into the object file, and (2) when the <tt>#!</tt> line is present,
it disables the default compression of the resulting file, which would
otherwise prevent it from being recognized as a script file.

<p>
If <i>Petite&nbsp;Chez&nbsp;Scheme</i> is installed, but not <i>Chez&nbsp;Scheme</i>,
<tt>/usr/bin/scheme</tt> may be
replaced with <tt>/usr/bin/petite</tt>.

<p>
<a name="./use:s33"></a><a name="./use:s34"></a>The <tt>--program</tt> command-line option is like <tt>--script</tt>
except that the script file is treated as an RNRS top-level program
(Chapter&nbsp;<a href="./libraries.html#g88">10</a>).
The following RNRS top-level program implements the traditional Unix
<tt>echo</tt> command, as with the script above.

<p>

<p><tt>#!&nbsp;/usr/bin/scheme&nbsp;--program<br>

(import&nbsp;(rnrs))<br>

(let&nbsp;([args&nbsp;(cdr&nbsp;(command-line))])<br>

&nbsp;&nbsp;(unless&nbsp;(null?&nbsp;args)<br>

&nbsp;&nbsp;&nbsp;&nbsp;(let-values&nbsp;([(newline?&nbsp;args)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(if&nbsp;(equal?&nbsp;(car&nbsp;args)&nbsp;"-n")<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(values&nbsp;#f&nbsp;(cdr&nbsp;args))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(values&nbsp;#t&nbsp;args))])<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(do&nbsp;([args&nbsp;args&nbsp;(cdr&nbsp;args)]&nbsp;[sep&nbsp;""&nbsp;"&nbsp;"])<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;((null?&nbsp;args))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(display&nbsp;sep)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(display&nbsp;(car&nbsp;args)))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(when&nbsp;newline?&nbsp;(newline)))))</tt>
<p>Again, if only <i>Petite&nbsp;Chez&nbsp;Scheme</i> is installed, <tt>/usr/bin/scheme</tt>
may be replaced with <tt>/usr/bin/petite</tt>.

<p>
<tt>scheme-script</tt> may be used in place of <tt>scheme&nbsp;--program</tt>
or <tt>petite&nbsp;--program</tt>, i.e.,

<p>

<p><tt>#!&nbsp;/usr/bin/scheme-script</tt>
<p><tt>scheme-script</tt> runs <i>Chez&nbsp;Scheme</i>, if available,
otherwise <i>Petite&nbsp;Chez&nbsp;Scheme</i>.

<p>
It is also possible to use <tt>/usr/bin/env</tt>, as recommended in the
Revised<sup>6</sup> Report nonnormative appendices, which allows
<tt>scheme-script</tt> to appear anywhere in the user's path.

<p>

<p><tt>#!&nbsp;/usr/bin/env&nbsp;scheme-script</tt>
<p><a name="./use:s35"></a><a name="./use:s36"></a>If a top-level program depends on libraries other than those built into
<i>Chez&nbsp;Scheme</i>, the <tt>--libdirs</tt> option can be used to specify
which source and object directories to search.
Similarly, if a library upon which a top-level program depends has an
extension other than one of the standard extensions, the
<tt>--libexts</tt> option can be used to specify additional extensions
to search.

<p>
<a name="./use:s37"></a><a name="./use:s38"></a>These options set the corresponding <i>Chez&nbsp;Scheme</i> parameters
<tt>library-directories</tt> and <tt>library-extensions</tt>,
which are described in Section&nbsp;<a href="./use.html#g9">2.4</a>.
The format of the arguments to <tt>--libdirs</tt> and
<tt>--libexts</tt> is the same:
a sequence of substrings separated by a single separator
character.
The separator character is a colon (:), except under Windows where it is a
semi-colon (;).
Between single separators, the source and object strings, if both are
specified, are separated by two separator characters.
If a single separator character appears at the end of the string,
the specified pairs are added to the front of the existing list;
otherwise, the specified pairs replace the existing list.

<p>
For example, where the separator is a colon,

<p>

<p><tt>scheme&nbsp;--libdirs&nbsp;"/home/moi/lib:"</tt>
<p>adds the source/object directory pair

<p>

<p><tt>("/home/moi/lib"&nbsp;.&nbsp;"/home/moi/lib")</tt>
<p>to the front of the default set of library directories, and

<p>

<p><tt>scheme&nbsp;--libdirs&nbsp;"/home/moi/libsrc::/home/moi/libobj:"</tt>
<p>adds the source/object directory pair

<p>

<p><tt>("/home/moi/libsrc"&nbsp;.&nbsp;"/home/moi/libobj")</tt>
<p>to the front of the default set of library directories.
The parameters are set after all boot files have been loaded.

<p>
<a name="./use:s39"></a><a name="./use:s40"></a>If no <tt>--libdirs</tt> option appears and the CHEZSCHEMELIBDIRS
environment variable is set, the string value of CHEZSCHEMELIBDIRS is
treated as if it were specified by a <tt>--libdirs</tt> option.
Similarly, if no <tt>--libexts</tt> option appears and the CHEZSCHEMELIBEXTS
environment variable is set, the string value of CHEZSCHEMELIBEXTS is
treated as if it were specified by a <tt>--libexts</tt> option.


<p>

<h3><a name="g11"></a><a name="./use:h6"></a>Section 2.6. Optimization<a name="SECTUSEOPTIMIZATION"></a></h3>


<p>
<a name="./use:s41"></a>To get the most out of the <i>Chez&nbsp;Scheme</i> compiler, it is necessary to
give it a little bit of help.
The most important assistance is to avoid the use of top-level
(interaction-environment) bindings.
Top-level bindings are convenient and appropriate during program
development, since they simplify testing, redefinition, and tracing
(Section&nbsp;<a href="./debug.html#g16">3.1</a>) of individual procedures and
syntactic forms.
This convenience comes at a sizable price, however.

<p>
<a name="./use:s42"></a><a name="./use:s43"></a>The compiler can propagate copies (of one variable to another or of
a constant to a variable) and inline procedures bound to local,
unassigned variables within a single top-level expression.
For the procedures it does not inline, it can avoid constructing and
passing unneeded closures, bypass argument-count checks, branch to the
proper entry point in a case-lambda, and build rest arguments (more
efficiently) on the caller side, where the length of the rest list is
known at compile time.
It can also discard the definitions of unreferenced variables, so there's
no penalty for including a large library of routines, only a few of
which are actually used.
  
<p>
It cannot do any of this with top-level variable bindings, since the
top-level bindings can change at any time and new references to those
bindings can be introduced at any time.

<p>
<a name="./use:s44"></a><a name="./use:s45"></a>Fortunately, it is easy to restructure a program to avoid top-level
bindings.
This is naturally accomplished for portable code by placing the
code into a single RNRS top-level program or by placing a portion
of the code in a top-level program and the remainder in one or
more separate libraries.
Although not portable, one can also put all of the code into a
single top-level <tt>module</tt> form or <tt>let</tt> expression,
perhaps using <tt>include</tt> to bring in portions of the
code from separate files.
The compiler performs some optimization even across library
boundaries, so the penalty for breaking a program up in this
manner is generally acceptable.
The compiler also supports whole-program optimization (via
<tt>compile-whole-program</tt>), which can be used to eliminate all
overhead for placing portions of a program into separate libraries.

<p>
Once an application's code has been placed into a single top-level program or into
a top-level program and one or more libraries, the code can be loaded
from source via <tt>load-program</tt> or compiled via
<a name="./use:s46"></a><tt>compile-program</tt>
and
<a name="./use:s47"></a><tt>compile-library</tt>,
as described in Section&nbsp;<a href="./use.html#g9">2.4</a>.
Be sure not to use <tt>compile-file</tt> for the top-level program
since this does not preserve the semantics nor result in code that
is as efficient.

<p>
With an application structured as a single top-level program or as a
top-level program and one or more libraries that do not interact
frequently, we have done most of what can be done to help the compiler,
but there are still a few more things we can do.

<p>
<a name="./use:s48"></a><a name="./use:s49"></a>First, we can allow the compiler to generate "unsafe" code, i.e.,
allow the compiler to generate code in which the usual run-time type
checks have been disabled.
We do this by using the compiler's "optimize level 3" when compiling
the program and library files.
This can be accomplished by setting the parameter <tt>optimize-level</tt>
to 3 while compiling the library or
program, e.g.:

<p>

<p><tt>(parameterize&nbsp;([optimize-level&nbsp;3])&nbsp;(compile-program&nbsp;"<i>filename</i>"))</tt>
<p><a name="./use:s50"></a>or in batch mode via the <tt>--optimize-level</tt> command-line option:

<p>

<p><tt>echo&nbsp;'(compile-program&nbsp;"<i>filename</i>")'&nbsp;|&nbsp;scheme&nbsp;-q&nbsp;--optimize-level&nbsp;3</tt>
<p>It may also be useful to experiment with some of the other compiler
control parameters and also with the storage manager's run-time
operation.
The compiler-control parameters, including <tt>optimize-level</tt>, are
described in Section&nbsp;<a href="./system.html#g113">12.6</a>, and the storage manager
control parameters are described in Section&nbsp;<a href="./smgmt.html#g125">13.1</a>.

<p>
<a name="./use:s51"></a>Finally, it is often useful to "profile" your code to determine that
parts of the code that are executed most frequently.
While this will not help the system optimize your code, it can help
you identify "hot spots" where you need to concentrate your own
hand-optimization efforts.
In these hot spots, consider using more efficient operators, like
fixnum or flonum operators in place of generic arithmetic operators,
and using explicit loops rather than nested combinations of
linear list-processing operators like <tt>append</tt>, <tt>reverse</tt>,
and <tt>map</tt>.
These operators can make code more readable when used judiciously,
but they can slow down time-critical code.

<p>
Section&nbsp;<a href="./system.html#g114">12.7</a> describes how to use the compiler's support
for automatic profiling.
Be sure that profiling is not enabled when you compile your production
code, since the code introduced into the generated code to perform the
profiling adds significant run-time overhead.

<p>

<h3><a name="g12"></a><a name="./use:h7"></a>Section 2.7. Customization<a name="SECTUSECUSTOMIZATION"></a></h3>


<p>
<a name="./use:s52"></a><a name="./use:s53"></a><a name="./use:s54"></a><a name="./use:s55"></a><i>Chez&nbsp;Scheme</i> and <i>Petite&nbsp;Chez&nbsp;Scheme</i> are built from several
subsystems: a "kernel" encapsulated in a static or shared
library (dynamic link library) that contains operating-system
interface and low-level storage management code,
an executable that parses command-line arguments and calls
into the kernel to initialize and run the system, a base
boot file (petite.boot) that contains the bulk of the run-time library code,
and an additional boot file (scheme.boot), for <i>Chez&nbsp;Scheme</i> only,
that contains the compiler.

<p>
While the kernel and base boot file are essential to the
operation of all programs, the executable may be replaced or
even eliminated, and the compiler boot file need be loaded only
if the compiler is actually used.
In fact, the compiler is typically not loaded for distributed
applications unless the application creates and executes code at run time.

<p>
The kernel exports a set of entry points that are used to initialize
the Scheme system, load boot or heap files, run an interactive Scheme
session, run script files, and deinitialize the system.
In the threaded versions of the system, the kernel also exports
entry points for activating, deactivating, and destroying threads.
These entry points may be used to create your own executable image
that has different (or no) command-line options or to run Scheme
as a subordinate program within another program, i.e., for use as
an extension language.

<p>
These entry points are described in Section&nbsp;<a href="./foreign.html#g34">4.8</a>,
along with other entry points for accessing and modifying Scheme
data structures and calling Scheme procedures.

<p>
<a name="./use:s56"></a>The file main.c in the 'c' subdirectory contains the 
"main" routine for the distributed executable image; look at
this file to gain an understanding of how the system startup
entry points are used.

<p>

<h3><a name="g13"></a><a name="./use:h8"></a>Section 2.8. Building and Distributing Applications<a name="SECTUSEAPPLICATIONS"></a></h3>


<p>
<a name="./use:s57"></a><a name="./use:s58"></a>Although useful as a stand-alone Scheme system,
<i>Petite&nbsp;Chez&nbsp;Scheme</i> was conceived as a run-time system for compiled
<i>Chez&nbsp;Scheme</i> applications.
The remainder of 
this section describes how to create and distribute such applications
using <i>Petite&nbsp;Chez&nbsp;Scheme</i>.
It begins with a discussion of the characteristics of
<i>Petite&nbsp;Chez&nbsp;Scheme</i> and how it compares with <i>Chez&nbsp;Scheme</i>,
then describes how to prepare application source code,
how to build and run applications, and how to distribute them.

<p>
<p><b>Petite Chez Scheme Characteristics.</b>&nbsp;&nbsp;Although interpreter-based, <i>Petite&nbsp;Chez&nbsp;Scheme</i> evaluates Scheme source
code faster than might be expected.
Some of the reasons for this are listed below.

<p>
<ul>
<li>The run-time system is fully compiled, so library implementations
of primitives ranging from <tt>+</tt> and <tt>car</tt> to <tt>sort</tt>
and <tt>printf</tt> are just as efficient as in <i>Chez&nbsp;Scheme</i>, although
they cannot be open-coded as in code compiled by <i>Chez&nbsp;Scheme</i>.

<p>
<li>The interpreter is itself a compiled Scheme application.
Because it is written in Scheme, it directly benefits from various
characteristics of Scheme that would have to be dealt with explicitly
and with additional overhead in most other languages, including
proper treatment of tail calls, first-class procedures, automatic
storage management, and continuations.

<p>
<li>The interpreter employs a preprocessor that 
converts the code into a form that can be interpreted
efficiently.
In fact, the preprocessor shares its front end with the compiler, and
this front end performs a variety of source-level optimizations.
</ul>
<p>

<p>
Nevertheless, compiled code is still more efficient for most
applications.
The difference between the speed of interpreted and compiled code
varies significantly from one application to another, but often amounts
to a factor of five and sometimes to a factor of ten or more.

<p>
Several additional limitations result from the fact that
<i>Petite&nbsp;Chez&nbsp;Scheme</i> does not include the compiler:

<p>
<ul>
<li>The compiler must be present to process <tt>foreign-procedure</tt>
and <tt>foreign-callable</tt> expressions, even when these forms are
evaluated by the interpreter.
These forms cannot be processed by the interpreter alone, so
they cannot appear in source code to be processed by <i>Petite&nbsp;Chez&nbsp;Scheme</i>.
Compiled versions of <tt>foreign-procedure</tt> and <tt>foreign-callable</tt>
forms may, however, be included
in compiled code loaded into <i>Petite&nbsp;Chez&nbsp;Scheme</i>.

<p>
<li>Inspector information is attached to code objects, which are
generated only by the compiler, so source information and variable names
are not available for interpreted procedures or continuations into
interpreted procedures.
This makes the inspector less effective for debugging interpreted code
than it is for debugging compiled code.

<p>
<li>Procedure names are also attached to code objects, so while
the compiler associates a name with each procedure when
an appropriate name can be determined, the interpreter does not do so.
This mostly impacts the quality of error messages, e.g., an error message
might read "incorrect number of arguments to <tt>#&lt;procedure&gt;</tt>"
rather than the likely more useful "incorrect number of arguments to
<tt>#&lt;procedure&nbsp;<i>name</i>&gt;</tt>."

<p>
<li>The compiler detects, at compile time, some potential errors
that the interpreter does not detect and reports them via compile-time
warnings that identify the expression or the location in the source
file, if any, where the expression appears.

<p>
<li>Automatic profiling cannot be enabled for interpreted code as it
is for compiled code when <tt>compile-profile</tt> is set to <tt>#t</tt>.
</ul>
<p>

<p>
Except as noted above, <i>Petite&nbsp;Chez&nbsp;Scheme</i> does not restrict what
programs can do, and like <i>Chez&nbsp;Scheme</i>, it places essentially no
limits on the size of programs or the memory images they create,
beyond the inherent limitations of the underlying hardware or
operating system.

<p>
<p><b>Compiled scripts and programs.</b>&nbsp;&nbsp;One simple mechanism for distributing an application is to structure it as
a script or RNRS top-level program, use
<a name="./use:s59"></a><tt>compile-script</tt> or
<a name="./use:s60"></a><tt>compile-program</tt>, as appropriate
to compile it as described in Section&nbsp;<a href="./use.html#g10">2.5</a>, and
distribute the resulting object file along with a complete distribution of
<i>Petite&nbsp;Chez&nbsp;Scheme</i>.
When this mechanism is used on Unix-based systems, if the source file
begins with <tt>#!</tt> and the path that follows is the path to the
<i>Chez&nbsp;Scheme</i> executable, e.g., <tt>/usr/bin/scheme</tt>, the one at the
front of the object file should be replaced with the path to the
<i>Petite&nbsp;Chez&nbsp;Scheme</i> executable, e.g., <tt>/usr/bin/petite</tt>.
The path may have to be adjusted by the application's installation
program based on where <i>Petite&nbsp;Chez&nbsp;Scheme</i> is installed on the target
system.
When used under Windows, the application's installation program should
set up an appropriate shortcut that starts <i>Petite&nbsp;Chez&nbsp;Scheme</i> with the
<tt>--script</tt> or <tt>--program</tt> option, as appropriate, followed
by the path to the object file.

<p>
The remainder of this section describes how to distribute applications
that do not require <i>Petite&nbsp;Chez&nbsp;Scheme</i> to be installed as a stand-alone
system on the target machine.

<p>
<p><b>Preparing Application Code.</b>&nbsp;&nbsp;While it is possible to distribute applications in source-code form,
i.e., as a set of Scheme source files to be loaded into <i>Petite&nbsp;Chez&nbsp;Scheme</i>
by the end user, distributing compiled code has two major
advantages over distributing source code.
First, compiled code is usually much more efficient, as discussed in
the preceding section, and second, compiled code is in binary form and
thus provides more protection for proprietary application code.

<p>
Application source code generally consists of a set of Scheme source
files possibly augmented by foreign code developed specifically for the
application and packaged in shared libraries (also known as shared
objects or, on Windows, dynamic link libraries).
The following assumes that any shared-library source code has been
converted into object form; how to do this varies by platform.
(Some hints are given in Section&nbsp;<a href="./foreign.html#g32">4.6</a>.)
The result is a set of one or more shared libraries that are loaded
explicitly by the Scheme source code during program initialization.

<p>
Once the shared libraries have been created, the next step is to
compile the Scheme source files into a set of Scheme object files.
Doing so typically involves simply invoking <a name="./use:s61"></a><tt>compile-file</tt>,
<a name="./use:s62"></a><tt>compile-library</tt>,
or 
<a name="./use:s63"></a><tt>compile-program</tt>,
as appropriate,
on each source file to produce the corresponding object file.
This may be done within a build script or "make" file via a
command line such as the following:

<p>

<p><tt>echo&nbsp;'(compile-file&nbsp;"<i>filename</i>")'&nbsp;|&nbsp;scheme</tt>
<p>which produces the object file <tt>filename.so</tt> from the source
file <tt>filename.ss</tt>.

<p>
If the application code has been developed interactively or is usually
loaded directly from source,
it may be necessary to make some adjustments to a file to be
compiled if the file contains expressions or definitions that
affect the compilation of subsequent forms in the file.
This can be accomplished via <tt>eval-when</tt>
(Section&nbsp;<a href="./system.html#g111">12.4</a>).
This is not typically necessary or desirable if the application consists
of a set of RNRS libraries and programs.

<p>
You may also wish to disable generation of inspector information
both to reduce the size of the compiled application code and to
prevent others from having access to the expanded source code that
is retained as part of the inspector information.
To do so, set the parameter
<a name="./use:s64"></a><tt>generate-inspector-information</tt>
to <tt>#f</tt> while compiling each file
The downside of disabling inspector information is that the information
will not be present if you need to debug your application, so it is
usually desirable to disable inspector information only for production
builds of your application.
An alternative is to compile the code with inspector information enabled
and strip out the debugging information later with 
<a name="./use:s65"></a><tt>strip-fasl-file</tt>.

<p>
The Scheme startup procedure determines what the system does when
it is started.
The default startup procedure loads the files listed on the command
line (via <tt>load</tt>) and starts up a new caf&eacute;, like this.

<p>

<p><tt>(lambda&nbsp;fns&nbsp;(for-each&nbsp;load&nbsp;fns)&nbsp;(new-cafe))</tt>
<p>The startup procedure may be changed via the parameter
<a name="./use:s66"></a><tt>scheme-start</tt>.
The following example demonstrates the installation of a variant of the
default startup procedure that prints the name of each file before
loading it.

<p>

<p><tt>(scheme-start<br>

&nbsp;&nbsp;(lambda&nbsp;fns<br>

&nbsp;&nbsp;&nbsp;&nbsp;(for-each<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(lambda&nbsp;(fn)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(printf&nbsp;"loading&nbsp;~a&nbsp;..."&nbsp;fn)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(load&nbsp;fn)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(printf&nbsp;"~%"))<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fns)<br>

&nbsp;&nbsp;&nbsp;&nbsp;(new-cafe)))</tt>
<p>A typical application startup procedure would first invoke the 
application's initialization procedure(s) and then start the
application itself:

<p>

<p><tt>(scheme-start<br>

&nbsp;&nbsp;(lambda&nbsp;fns<br>

&nbsp;&nbsp;&nbsp;&nbsp;(initialize-application)<br>

&nbsp;&nbsp;&nbsp;&nbsp;(start-application&nbsp;fns)))</tt>
<p>Any shared libraries that must be present during the running of an
application must be loaded during initialization.
In addition, all foreign procedure expressions must be executed
after the shared libraries are loaded so that the addresses
of foreign routines are available to be recorded with the resulting foreign
procedures.
The following demonstrates one way in which initialization might be
accomplished for an application that links to a foreign procedure
<tt>show_state</tt> in the Windows shared library <tt>state.dll</tt>:

<p>

<p><tt>(define&nbsp;show-state)
<br>
<br>
(define&nbsp;app-init<br>

&nbsp;&nbsp;(lambda&nbsp;()<br>

&nbsp;&nbsp;&nbsp;&nbsp;(load-shared-object&nbsp;"state.dll")<br>

&nbsp;&nbsp;&nbsp;&nbsp;(set!&nbsp;show-state<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(foreign-procedure&nbsp;"show_state"&nbsp;(integer-32)<br>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;integer-32))))<br>

&nbsp;<br>

(scheme-start<br>

&nbsp;&nbsp;(lambda&nbsp;fns<br>

&nbsp;&nbsp;&nbsp;&nbsp;(app-init)<br>

&nbsp;&nbsp;&nbsp;&nbsp;(app-run&nbsp;fns)))</tt>
<p><p><b>Building and Running the Application.</b>&nbsp;&nbsp;Building and running an application is straightforward once all shared
libraries have been built and Scheme source files have been compiled
to object code.

<p>
Although not strictly necessary, we suggest that you concatenate your
object files, if you have more than one, into a single object file.
This may be done on Unix systems simply via the <tt>cat</tt>
program or on Windows via <tt>copy</tt>.
Placing all of the object code into a single file
simplifies both building and distribution of applications.

<p>
For top-level programs with separate libraries,
<a name="./use:s67"></a><tt>compile-whole-program</tt>
can be used to produce a single, fully optimized object file.
Otherwise, when concatenating object files, put each library after the
libraries it depends upon, with the program last.

<p>
With the Scheme object code contained within a single composite object file,
it is possible to run the application simply by loading the composite
object file into <i>Petite&nbsp;Chez&nbsp;Scheme</i>, e.g.:

<p>

<p><tt>petite&nbsp;app.so</tt>
<p>where <tt>app.so</tt> is the name of the composite object file,
and invoking the startup procedure to restart the system:

<p>

<p><tt>&gt;&nbsp;((scheme-start))</tt>
<p>The point of setting <tt>scheme-start</tt>, however, is to allow the
set of object files to be converted into a 
<a name="./use:s68"></a><i>boot file</i>.
Boot files are loaded during the process of building the initial heap.
Because of this, boot files have the following advantages over ordinary
object files.

<p>
<ul>
<li>Any code and data structures contained in the boot file or created
while it is loaded is automatically compacted along with the base run-time
library code and made static.
Static code and data are never collected by the storage manager, so
garbage collection overhead is reduced.
(It is also possible to make code and data static explicitly at any
time via the <tt>collect</tt> procedure.)

<p>
<li>The system looks for boot files automatically in a set of standard
directories based on the name of the executable image, so you can
install a copy of the <i>Petite&nbsp;Chez&nbsp;Scheme</i> executable image under your
application's name and spare your users from supplying any command-line
arguments or running a separate script to load the application code.
</ul>
<p>

<p>
A boot file is simply an object file, possibly containing the code for
more than one source file, prefixed by a boot header.
The boot header identifies a base boot file upon which the application
directly depends, or possibly two or more alternatives upon which the
application can be run.
In most cases, petite.boot will be identified as the base boot
file, but in a layered application it may be another boot file of your
creation that in turn depends upon petite.boot.
The base boot file, and its base boot file, if any, are loaded
automatically when your application boot file is loaded.

<p>
Boot files are created with <a name="./use:s69"></a><tt>make-boot-file</tt>.
This procedure accepts two or more arguments.
The first is a string naming the file into which the boot header and
object code should be placed, the second is a list of strings naming base
boot files, and the remainder are strings naming input files.
For example, the call:

<p>

<p><tt>(make-boot-file&nbsp;"app.boot"&nbsp;'("petite")&nbsp;"app1.so"&nbsp;"app2.ss"&nbsp;"app3.so")</tt>
<p>creates the boot file app.boot that identifies a dependency upon petite.boot
and contains the object code for app1.so, the object code resulting from
compiling app2.ss, and the object code for app3.so.
The call:

<p>

<p><tt>(make-boot-file&nbsp;"app.boot"&nbsp;'("scheme"&nbsp;"petite")&nbsp;"app.so")</tt>
<p>creates a header file that identifies a dependency upon either
scheme.boot or petite.boot, with the object code from app.so.
In the former case, the system will automatically load petite.boot
when the application boot file is loaded, and in the latter it will
load scheme.boot if it can find it, otherwise petite.boot.
This would allow your application to run on top of the full
<i>Chez&nbsp;Scheme</i> if present, otherwise <i>Petite&nbsp;Chez&nbsp;Scheme</i>.

<p>
In most cases, you can construct your application
so it does not depend upon features of <i>Chez&nbsp;Scheme</i> (specifically,
the compiler) by specifying only <tt>"petite"</tt> in the call to
<tt>make-boot-file</tt>.
If your application calls <tt>eval</tt>, however, and you wish to
allow users to be able to take
advantage of the faster execution speed of compiled code, then specifying
both <tt>"scheme"</tt> and <tt>"petite"</tt>
is appropriate.

<p>
<p><b>Distributing the Application.</b>&nbsp;&nbsp;Distributing an application involves can be as simple as creating a
distribution package that includes the following items:

<p>
<ul>
<li>the <i>Petite&nbsp;Chez&nbsp;Scheme</i> distribution,
<li>the application boot file,
<li>any application-specific shared libraries,
<li>an application installation script.
</ul>
<p>

<p>
The application installation script should install <i>Petite&nbsp;Chez&nbsp;Scheme</i>
if not already installed on the target system.
It should install the application boot file in the same directory as
the <i>Petite&nbsp;Chez&nbsp;Scheme</i> boot file petite.boot is installed,
and it should should install the application shared libraries, if any,
either in the same location or in a standard location for shared libraries
on the target system.
It should also create a link to or copy of the <i>Petite&nbsp;Chez&nbsp;Scheme</i>
executable under the name of your application, i.e., the name given
to your application boot file.
Where appropriate, it should also install desktop and start-menu
shortcuts to run the executable.

<p>

<h3><a name="g14"></a><a name="./use:h9"></a>Section 2.9. Command-Line Options<a name="SECTUSECOMMANDLINE"></a></h3>


<p>
<a name="./use:s70"></a><a name="./use:s71"></a><a name="./use:s72"></a><a name="./use:s73"></a><a name="./use:s74"></a><a name="./use:s75"></a><a name="./use:s76"></a><a name="./use:s77"></a><a name="./use:s78"></a><a name="./use:s79"></a><a name="./use:s80"></a><a name="./use:s81"></a><a name="./use:s82"></a><a name="./use:s83"></a><a name="./use:s84"></a><a name="./use:s85"></a><a name="./use:s86"></a><a name="./use:s87"></a><a name="./use:s88"></a><a name="./use:s89"></a><a name="./use:s90"></a><i>Chez&nbsp;Scheme</i> recognizes the following command-line options.

<p>
<TABLE><TR><TD nowrap align="left">
<tt>-q</tt>, <tt>--quiet</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;suppress greeting and prompt</TD></TR><TR><TD nowrap align="left">
<tt>--script&nbsp;<i>path</i></tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;run as shell script</TD></TR><TR><TD nowrap align="left">
<tt>--program&nbsp;<i>path</i></tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;run rnrs top-level program as shell script</TD></TR><TR><TD nowrap align="left">
<tt>--libdirs&nbsp;<i>dir</i>:...</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;set library directories</TD></TR><TR><TD nowrap align="left">
<tt>--libexts&nbsp;<i>ext</i>:...</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;set library extensions</TD></TR><TR><TD nowrap align="left">
<tt>--compile-imported-libraries</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;compile libraries before loading</TD></TR><TR><TD nowrap align="left">
<tt>--import-notify</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;enable import search messages</TD></TR><TR><TD nowrap align="left">
<tt>--optimize-level&nbsp;0&nbsp;|&nbsp;1&nbsp;|&nbsp;2&nbsp;|&nbsp;3</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;set initial optimize level</TD></TR><TR><TD nowrap align="left">
<tt>--debug-on-exception</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;on uncaught exception, call <tt>debug</tt></TD></TR><TR><TD nowrap align="left">
<tt>--eedisable</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;disable expression editor</TD></TR><TR><TD nowrap align="left">
<tt>--eehistory&nbsp;off&nbsp;|&nbsp;<i>path</i></tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;expression-editor history file</TD></TR><TR><TD nowrap align="left">
<tt>--enable-object-counts</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;have collector maintain object counts</TD></TR><TR><TD nowrap align="left">
<tt>--retain-static-relocation</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;keep reloc info for compute-size, etc.</TD></TR><TR><TD nowrap align="left">
<tt>-b&nbsp;<i>path</i></tt>, <tt>--boot&nbsp;<i>path</i></tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;load boot file</TD></TR><TR><TD nowrap align="left">
<tt>--verbose</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;trace boot-file search process</TD></TR><TR><TD nowrap align="left">
<tt>--version</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;print version and exit</TD></TR><TR><TD nowrap align="left">
<tt>--help</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;print help and exit</TD></TR><TR><TD nowrap align="left">
<tt>--</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;pass through remaining args</TD></TR><TR><TD nowrap align="left">
</TD></TR></TABLE>

<p>
<a name="./use:s91"></a><a name="./use:s92"></a><a name="./use:s93"></a><a name="./use:s94"></a><a name="./use:s95"></a><a name="./use:s96"></a>The following options are recognized but cause the system to print an
error message and exit because saved heaps are no longer supported.

<p>
<TABLE><TR><TD nowrap align="left">
<tt>-h&nbsp;<i>path</i></tt>, <tt>--heap&nbsp;<i>path</i></tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;load heap file</TD></TR><TR><TD nowrap align="left">
<tt>-s[<i>n</i>]&nbsp;<i>path</i></tt>, <tt>--saveheap[<i>n</i>]&nbsp;<i>path</i></tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;save heap file</TD></TR><TR><TD nowrap align="left">
<tt>-c</tt>, <tt>--compact</tt>
    </TD><TD nowrap align="left"> &nbsp;&nbsp;toggle compaction flag</TD></TR><TR><TD nowrap align="left">
</TD></TR></TABLE>

<p>
Any remaining command-line arguments are treated as the names of files
to be loaded before <i>Chez&nbsp;Scheme</i> begins interacting with the user.

<p>
Most of the options are described elsewhere in this chapter, and a few
are self-explanatory.
The remainder pertain the loading of boot files at system start-up
time and are described below.

<p>
<a name="./use:s97"></a><a name="./use:s98"></a>When <i>Chez&nbsp;Scheme</i> is run, it looks for one or more boot files
to load.
Boot files contain the compiled Scheme code that implements most of
the Scheme system, including the interpreter, compiler, and most
libraries.
Boot
files may be specified explicitly on the command
line via <tt>-b</tt>
options or implicitly.
In the simplest case, no <tt>-b</tt>
options
are given and the necessary boot
files are loaded
automatically based on the name of the executable.

<p>
For example, if the executable name is "frob", the
system looks for
"frob.boot" in a set of standard directories.
It also looks for and loads any subordinate
boot files required
by
"frob.boot".

<p>
Subordinate
boot files are also loaded automatically for the
first boot file
explicitly specified via the command line.
Each boot file must be listed before those that depend upon it.

<p>
The <tt>--verbose</tt> option may be used to trace the
file searching process and must appear before any boot
arguments for which search tracing is desired.

<p>
Ordinarily, the search for
boot files is limited to a set of
installation directories, but this may be overridden by setting
the environment variable <a name="./use:s99"></a><tt>SCHEMEHEAPDIRS</tt>.
<tt>SCHEMEHEAPDIRS</tt> should be a colon-separated list of directories, listed in
the order in which they should be searched.
Within each directory, the two-character escape sequence "<tt>%v</tt>"
is replaced by the current version, and the two-character escape sequence
"<tt>%m</tt>" is replaced by the machine type.
A percent followed by any other character is replaced by the second
character; in particular, "<tt>%%</tt>" is replaced by "<tt>%</tt>", and
"<tt>%:</tt>" is replaced by "<tt>:</tt>".
If <tt>SCHEMEHEAPDIRS</tt> ends in a non-escaped colon, the default directories are
searched after those in <tt>SCHEMEHEAPDIRS</tt>; otherwise, only those listed in
<tt>SCHEMEHEAPDIRS</tt> are searched.

<p>
Under Windows, semi-colons are used in place of colons, and one additional
escape is recognized: "<tt>%x</tt>," which is replaced by the directory in
which the executable file resides.
The default search path under Windows consists of "<tt>%x</tt>"
and "<tt>%x\..\..\boot\%m</tt>."
The registry key <tt>HeapSearchPath</tt> in
<tt>HKLM\SOFTWARE\Chez&nbsp;Scheme\csv<i>version</i></tt>, where
<tt><i>version</i></tt> is the <i>Chez&nbsp;Scheme</i> version number, e.g.,
<tt>7.9.4</tt>, can be set to override the default search path,
and the <tt>SCHEMEHEAPDIRS</tt> environment variable
overrides both the default and the registry setting, if any.

<p>
Boot files consist of ordinary compiled code and consist of
a boot header and the compiled code for one or more
source files.
See Section&nbsp;<a href="./use.html#g13">2.8</a> for instructions on how to create
boot files.

<p>


<hr class=copyright align=left>
<p>
<a class=plain href="index.html">Chez Scheme Version 9 User's Guide</a><br>
Copyright &copy; 2016 Cisco Systems, Inc.<br>
Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License Version 2.0</a>
(<a class=plain href="canned/copyright.html">full copyright notice.</a>).</br>
Revised June 2016 for Chez Scheme Version 9.4<br>
<a class=plain href="canned/about.html">about this book</a>
</tr></table>
</body>
</html>