Advanced commands

Building images

,dump <filename> [<identification >]

This writes out the current heap. When the new image is resumed, it starts in the command processor. If present, should be a string (written with double quotes); this string will be part of the greeting message as the image starts up.

,build <exp> <filename >

<exp> should evaluate to a procedure of one argument. When <filename > is resumed, that procedure will be invoked on the VM's -a arguments, which are passed as a list of strings. The procedure should return an integer (as for ,exit). The command processor and debugging system are not included in the image (unless you go to some effort to preserve them, such as retaining a continuation).

Doing ",flush" before building an image will make for smaller images, but if an error occurs, the error message may be less helpful. Doing ",flush source maps" before loading any programs will make the image still smaller.

Modes

When given no argument, all of these commands toggle the corresponding mode. With the argument ?, the current setting is displayed. Otherwise the argument should be ON or OFF.

,batch [on | off | ?]

In "batch mode," any error or interrupt that comes up will cause Scheme 48 to exit immediately with a non-zero exit status. Also, the command processor doesn't print prompts. The default is interactive mode.

,form-preferred [on | off | ?]

Enable or disable "form preferred" mode. In this mode, command processor commands needn't be prefixed by comma. To see the value of a variable (or number - this should be fixed), do (begin ). "Command preferred" mode is the default.

,levels [on | off | ?]

Enable or disable command levels. With levels enabled (the default), errors "push" a new command level, and (see above) or ,reset is required to return to top level. The effects of pushed command levels include:

• a longer prompt
• retention of the continuation in effect at the point of errors
• longer ,previews
• confusion among some newcomers

With levels disabled, one must issue a ,push command immediately following an error in order to retain the error continuation for debugging purposes; otherwise the continuation is lost after the next evaluation request. If you don't know anything about the available debugging tools, then levels might as well be disabled.

This is an experimental feature inspired by gripes about how confusing recursive command loop levels are to newcomers to Scheme. Let me know (jar@ai.mit.edu) if you like it; otherwise it might get flushed.

Each level has its own set of threads, so pushing a new level stops all threads running at the current level.

,break-on-warnings [on | off | ?]

When a warning is produced, enter a new command level, just as when an error occurs.

Resource query and control

,time <exp>

Measure execution time.

,collect

Invoke the garbage collector. Ordinarily this happens automatically, but the command tells how much space is available before and after the collection.

,keep <kind>
,flush <kind >

These control the amount of debugging information retained after compiling procedures. This information can consume a fair amount of space. <kind > is one of the following:

• maps - environment maps (local variable names, for inspector)
• source - source code for continuations (displayed by inspector)
• names - procedure names (as displayed by WRITE and in error messages)
• files - source file names

These commands refer to future compilations only, not to procedures that already exist. To have any effect, they must be done before programs are loaded.

,flush

The flush command with no argument deletes the database of names of initial procedures. Doing ",flush" before a ,build or ,dump will make the resulting image significantly smaller (by up to 200K bytes), but will compromise the information content of many error messages.

Quite obscure

,go <exp>

This is like ,exit <exp> except that the evaluation of <exp> is tail-recursive with respect to the command processor. This means that the command processor itself can probably be GC'ed, should a garbage collection occur in the execution of <exp>. Any errors will be treated as in batch mode.

,translate <from> <to>

For LOAD and the ,load command (but not for OPEN-xxPUT-FILE), file names beginning with the string <from> will be changed so that the initial <from> is replaced by the string <to>. E.g.

        ,translate /usr/gjc/ /zu/gjc/

will cause (load "/usr/gjc/foo.scm") to have the same effect as (load "/zu/gjc/foo.scm").

,from-file <filename > <form > ... ,end

This is used by the cmuscheme48 Emacs library.

Other commands are (or should be) described in the module system document.

Performance

If you want to generally have your code run faster than it normally would, enter "benchmark mode" before loading anything. Otherwise calls to primitives (like + and cons) and in-line procedures (like not and cadr) won't be open-coded, and programs will run more slowly. Enter benchmark mode by issuing the ,bench command to the command processor.

The system doesn't start in benchmark mode by default because the Scheme report permits redefinitions of built-in procedures. In benchmark mode, such redefinitions don't work according to the report, because previously compiled calls may have in-lined the old definition, leaving no opportunity to call the new definition.

",bench" toggles benchmark mode. ",bench on" and ",bench off" turn it on and off.

Disassembler

The ,dis command disassembles procedures.

	> ,dis cons
	cons
	  0 (check-nargs= 2)
	  2 (pop)
	  3 (make-stored-object 2 pair)
	  6 (return)
	> 


The command argument is optional; if unsupplied it defaults to the
current focus object (##).


The disassembler can also be invoked on continuations and templates.




 Ownership, Maintenance and Disclaimers 

 Scheme48 Manual Top Page

 Envision Manual Top Page

Last modified