Note: the procedures described in this section are only available in the
`compiler.com' world image. Furthermore,
cf is only
available on machines that support native-code compilation.
cf compiles the file `foo.scm', producing the file
`foo.com' (incidentally it will also produce `foo.bin',
`foo.bci', and possibly `foo.ext'). If you later evaluate
`foo.com' will be loaded rather than `foo.scm'.
If destination is given, it says where the output files should go. If this argument is a directory, they go in that directory, e.g.:
(cf "foo" "../bar/")
will take `foo.scm' and generate the file `../bar/foo.com'. If destination is not a directory, it is the root name of the output:
(cf "foo" "bar")
takes `foo.scm' and generates `bar.com'.
About the `.bci' files: these files contain the debugging
information that Scheme uses when you call
debug to examine
compiled code. When you load a `.com' file, Scheme remembers where
it was loaded from, and when the debugger (or
pp) looks at the
compiled code from that file, it attempts to find the `.bci' file
in the same directory from which the `.com' file was loaded. Thus
it is a good idea to leave these files together.
`.bci' files are stored in a compressed format. The debugger has to uncompress the files when it looks at them, and on a slow machine this can take a noticeable time. The system takes steps to reduce the impact of this behaviour: debugging information is cached in memory, and uncompressed versions of `.bci' files are kept around. The default behavior is that a temporary file is created and the `.bci' file is uncompressed into it. The temporary file is kept around for a while afterwards, and during that time if the uncompressed `.bci' file is needed the temporary file is used. Each such reference updates an `access time' that is associated with the temporary file. The garbage collector checks the access times of all such temporary files, and deletes any that have not been accessed in five minutes or more. All of the temporaries are deleted automatically when the Scheme process is killed.
Two other behaviors are available. One of them uncompresses the `.bci'
file each time it is referenced, and the other uncompresses the `.bci'
file and writes it back out as a `.bif' file (the old default).
The `.bif' file remains after Scheme exits.
The time interval and the behavior are controlled by variables. (These
variables are not in the global environment; perhaps they should be.
They are in the
(runtime compiler-info) package environment.)
sfis the program that transforms a source-code file into binary SCode form; it is used on machines that do not support native-code compilation. It performs numerous optimizations that can make your programs run considerably faster than unoptimized interpreted code. Also, the binary files that it generates load very quickly compared to source-code files.
The simplest way to use
sf is just to say:
This will cause your file to be transformed, and the resulting binary
file to be written out with the same name, but with pathname type
"bin". If you do not specify a pathname type on the input file,
"scm" is assumed.
load, the first argument to
sf may be a list of
filenames rather than a single filename.
sf takes an optional second argument, which is the filename of
the output file. If this argument is a directory, then the output file
has its normal name but is put in that directory instead.
Several declarations can be added to your programs to help
sf make them more efficient.
Normally, all files have a line
near their beginning, which tells the compiler that free variables whose
names are defined in
system-global-environment will not be
shadowed by other definitions when the program is loaded. If you
redefine some global name in your code, for example
cons, you should indicate it in the declaration:
(declare (usual-integrations car cdr cons))
You can obtain an alphabetically-sorted list of the names that the
usual-integrations declaration affects by evaluating the
(eval '(sort (append usual-integrations/constant-names usual-integrations/expansion-names) (lambda (x y) (string<=? (symbol->string x) (symbol->string y)))) (->environment '(scode-optimizer)))
Another useful facility is the ability to in-line code procedure definitions. In fact, the compiler will perform full beta conversion, with automatic renaming, if you request it. Here are the relevant declarations:
integratedeclaration, except that it only substitutes for references that appear in the operator position of a combination. All other references are ignored.
If filename is a relative filename (the normal case), it is interpreted as being relative to the file in which the declaration appears. Thus if the declaration appears in file `/usr/cph/foo.scm', then the compiler looks for a file called `/usr/cph/filename.ext'.
Note: When the compiler finds top-level integrations, it collects them
and outputs them into an auxiliary file with extension `.ext'.
This `.ext' file is what the
Note that the most common use of this facility, in-line coding of
procedure definitions, requires a somewhat complicated use of these
declarations. Because this is so common, there is a special form,
define-integrable, which is like
define but performs the
appropriate declarations. For example:
(define-integrable (foo-bar foo bar) (vector-ref (vector-ref foo bar) 3))
Here is how you do the same thing without this special form: there
should be an
integrate-operator declaration for the procedure's
name, and (internal to the procedure's definition) an
declaration for each of the procedure's parameters, like this:
(declare (integrate-operator foo-bar)) (define foo-bar (lambda (foo bar) (declare (integrate foo bar)) (vector-ref (vector-ref foo bar) 3)))
The reason for this complication is as follows: the
integrate-operator declaration finds all the references to
foo-bar and replaces them with the lambda expression from the
definition. Then, the
integrate declarations take effect because
the combination in which the reference to
supplies code which is substituted throughout the body of the procedure
definition. For example:
(foo-bar (car baz) (cdr baz))
First use the
((lambda (foo bar) (declare (integrate foo bar)) (vector-ref (vector-ref foo bar) 3)) (car baz) (cdr baz))
Next use the internal
((lambda (foo bar) (vector-ref (vector-ref (car baz) (cdr baz)) 3)) (car baz) (cdr baz))
Next notice that the variables
bar are not used,
and eliminate them:
((lambda () (vector-ref (vector-ref (car baz) (cdr baz)) 3)))
Finally, remove the
((lambda () ...)) to produce
(vector-ref (vector-ref (car baz) (cdr baz)) 3)
Useful tip: to see the effect of integration declarations (and of macros) on a source file, pretty-print the `.bin' file like this (be prepared for a lot of output).
(sf "foo.scm") (pp (fasload "foo.bin"))
replace-operator declaration is provided to inform the
compiler that certain operators may be replaced by other operators
depending on the number of arguments.
(declare (replace-operator (map (2 map-2) (3 map-3))))
(map f x y z) ==> (map f x y z) (map f x y) ==> (map-3 f x y) (map f x) ==> (map-2 f x) (map f) ==> (map f) (map) ==> (map)
map-3 are efficient versions of
map that are written for exactly two and three arguments
respectively. All the other cases are not expanded but are handled by the
map procedure, which is less efficient because
it must handle a variable number of arguments.
The syntax of this declaration is
(replace-operator (name (nargs1 value1) (nargs2 value2) ...))
(primitive primitive-name [arity])
The meanings of these fields are:
otherwise, then the operation is replaced with a call to the corresponding valueN. Only one of the nargsN may be of this form.
otherwise, then the operation is not replaced.
reduce-operator declaration is provided to inform the
compiler that certain names are n-ary versions of binary operators.
Here are some examples:
(declare (reduce-operator (cons* cons)))
(cons* x y z w) ==> (cons x (cons y (cons z w))), (cons* x y) ==> (cons x y) (cons* x) ==> x (cons*) error--> too few arguments
(declare (reduce-operator (list cons (null-value '() any))))
(list x y z w) ==> (cons x (cons y (cons z (cons w '())))) (list x y) ==> (cons x (cons y '())) (list x) ==> (cons x '()) (list) ==> '()
(declare (reduce-operator (- %- (null-value 0 single) (group left))))
(- x y z w) ==> (%- (%- (%- x y) z) w) (- x y) ==> (%- x y) (- x) ==> (%- 0 x) (-) ==> 0
(declare (reduce-operator (+ %+ (null-value 0 none) (group right))))
(+ x y z w) ==> (%+ x (%+ y (%+ z w))) (+ x y) ==> (%+ x y) (+ x) ==> x (+) ==> 0
Note: This declaration does not cause an appropriate definition of
%+ (in the last example) to appear in your code. It merely
informs the compiler that certain optimizations can be performed on
+ by replacing them with calls to
%+. You should
provide a definition of
%+ as well, although it is not required.
(declare (reduce-operator (apply (primitive cons) (group right) (wrapper (global apply) 1))))
(apply f x y z w) ==> ((access apply ()) f (cons x (cons y (cons z w)))) (apply f x y) ==> ((access apply ()) f (cons x y)) (apply f x) ==> (apply f x) (apply f) ==> (apply f) (apply) ==> (apply)
(reduce-operator (name binop [(group ordering)] [(null-value value null-option)] [(singleton unop)] [(wrapper wrap [n])] [(maximum m)] ))
(primitive primitive-name [arity])
The meaning of these fields is:
groupoption specifies whether name associates to the right or left.
null-valueoption specifies a value to use in the following cases:
singletonoption specifies a function, unop, to be invoked on the single argument left. This option supersedes the
null-valueoption, which can only take the value
wrapperoption specifies a function, wrap, to be invoked on the result of the outermost call to binop after the expansion. If n is provided it must be a non-negative integer indicating a number of arguments that are transferred verbatim from the original call to the wrapper. They are passed to the left of the reduction.