suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

clean out _loader compilation support; merge compiler library docs into mzc manual; improve mzscheme cmdline handling so that configuration options do not cancel defaults like -i and -u

Browse Source 
svn: r8432
This commit is contained in:
Matthew Flatt 2008-01-27 14:20:42 +00:00
parent c65b519351
commit e35c94f91d
32 changed files with 1104 additions and 1291 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
collects/compiler/compiler-unit.ss
View File

@ -68,10 +68,7 @@
(case mode
[(compile-extension) compile-extension]
[(compile-extension-to-c) compile-extension-to-c]
[(compile-c-extension) compile-c-extension]
[(compile-extension-part) compile-extension-part]
[(compile-extension-part-to-c) compile-extension-part-to-c]
[(compile-c-extension-part) compile-c-extension-part]))])
[(compile-c-extension) compile-c-extension]))])
(invoke-unit
(compound-unit
(import (COMPILE : dynext:compile^)
@ -111,49 +108,6 @@
(define compile-c-extensions
(make-unprefixed-compiler 'compile-c-extension))
(define compile-extension-parts
(make-compiler 'compile-extension-part))
(define compile-extension-parts-to-c
(make-compiler 'compile-extension-part-to-c))
(define compile-c-extension-parts
(make-unprefixed-compiler 'compile-c-extension-part))
(define (link/glue-extension-parts link? compile? source-files destination-directory)
(let ([u (c-dynamic-require 'compiler/ld-unit 'ld@)]
[init (unit
(import compiler:linker^)
(export)
(if link?
link-extension
(if compile?
glue-extension
glue-extension-source)))])
(let ([f (invoke-unit
(compound-unit
(import (COMPILE : dynext:compile^)
(LINK : dynext:link^)
(DFILE : dynext:file^)
(OPTION : compiler:option^))
(export)
(link [((LINKER : compiler:linker^))
u
COMPILE LINK DFILE OPTION]
[() init LINKER]))
(import dynext:compile^
dynext:link^
dynext:file^
compiler:option^))])
(f source-files destination-directory))))
(define (link-extension-parts source-files destination-directory)
(link/glue-extension-parts #t #t source-files destination-directory))
(define (glue-extension-parts source-files destination-directory)
(link/glue-extension-parts #f #t source-files destination-directory))
(define (glue-extension-parts-to-c source-files destination-directory)
(link/glue-extension-parts #f #f source-files destination-directory))
(define (compile-to-zo src dest namespace eval?)
((if eval? (lambda (t) (t)) with-module-reading-parameterization)
(lambda ()
@ -276,15 +230,9 @@
[info (c-get-info cp)])
(compile-directory dir info zos?)))
(define (compile-collection-extension collection . cp)
(compile-collection (cons collection cp) #f))
(define (compile-collection-zos collection . cp)
(compile-collection (cons collection cp) #t))
(define (compile-directory-extension dir info)
(compile-directory dir info #f))
(define (compile-directory-zos dir info)
(compile-directory dir info #t))

661
collects/compiler/doc.txt
View File

@ -1,661 +0,0 @@
The Compiler
============
To use the compiler within a Scheme program, require _compiler.ss_:
(require (lib "compiler.ss" "compiler"))
The _compiler.ss_ library defines the following functions (plus a few
signatures). Options that control the compiler are documented in the
next section.
Extension compilation
---------------------
> ((compile-extensions expr) scheme-file-list dest-dir)
`(compile-extensions expr)' returns a compiler that is
initialized with the expression `expr', as described below.
The compiler takes a list of Scheme files and compiles each of
them to an extension, placing the resulting extensions in the
directory specified by `dest-dir'. If `dest-dir' is #f, each
extension is placed in the same directory as its source file.
If `dest-dir' is 'auto, each extension file is placed in a
"compiled/native/<PLATFORM>" subdirectory relative to the source
file, where <PLATFORM> is the result of
`system-library-subpath'. (The directory is created if
necessary.)
`expr' effect:
If `expr' is anything other than #f, then a namespace is
created for compiling the files that are supplied later; `expr'
is evaluated to initialize the created namespace. For example,
`expr' might load a set of macros. In addition, the
expansion-time part of each expression later compiled is
evaluated in the namespace before being compiled, so that the
effects are visible when compiling later expressions.
If `expr' is #f, then no compilation namespace is created, and
expressions in the files are assumed to compile independently
(so there's no need to evaluate the expansion-time part of an
expression to compile).
Typically, `expr' is #f for compiling `module' files and
`(void)' for compiling files with top-level definitions and
expressions.
> ((compile-extensions-to-c expr) scheme-file-list dest-dir)
Like `compile-extensions', but only .c files are produced, not
extensions.
> (compile-c-extensions c-file-list dest-dir)
Compiles each .c file (usually produced with `compile-extensions-to-c')
in c-file-list to an extension. `dest-dir' is handled as in
`compile-extensions'.
zo compilation
--------------
> ((compile-zos expr) scheme-file-list dest-dir)
`(compile-zos expr)' returns a compiler that is initialized with
the expression `expr'.
See `compile-extensions' above for information about the effect
of `expr'.
The returned compiler takes a list of Scheme files and compiles
each of them to a .zo file, placing the resulting .zo files in
the directory specified by `dest-dir'. If `dest-dir' is #f,
each .zo file is placed in the same directory as its source
file. If `dest-dir' is 'auto, each .zo file is placed in a
"compiled" subdirectory relative to the source file. (The
directory is created if necessary.)
Collection compilation
----------------------
> (compile-collection-extension collection sub-collection ...)
Compiles the specified (sub-)collection to an extension
"_loader", putting intermediate .c and .kp files in the
collection's "compiled/native" directory, and object files and
the resulting "_loader" extension in the collection's
"compiled/native/PLATFORM" directory (where `PLATFORM' is the
system name for the current platform).
The collection compiler reads the collection's _info.ss_ file
(see the mzc manual for information about info.ss) to obtain
information about compiling the collection. The following
fields are used:
> name - the name of the collection as a string.
> compile-omit-files - a list of filenames (without paths); all
Scheme files in the collection are compiled except for the
files in this list. Note: files that are required by other
files that are compiled will get compiled in the process even
when listed here.
> compile-extension-omit-files - a list of filenames to extend
the list returned for `compile-omit-files'. Unlike the list
returned for `compile-omit-files', this extension is not used
when compiling .zo files.
> compile-subcollections - a list of collection paths, where each
path is a list of strings. `compile-collection-extension' is
applied to each of the collections.
Only the `name' field is required from info.ss.(Note: Setup PLT
uses this field as an indication that the collection should be
compiled.)
The compilation process is driven by the 'make-collection'
function in the "collection.ss" library of the "make"
collection.
> (compile-directory-extension path info-function)
Like `compile-collection-extension', but compiles the given
directory rather than a collection. Also takes an info
function (the result of `get-info' or `get-info/full'; see
the setup collection's documentation for more information)
that will be used to guide compilation instead of looking for
an info.ss file in the directory.
> (compile-collection-zos collection sub-collection ...)
Compiles the specified (sub-)collection files to .zo files.
The .zo files are placed into the collection's "compiled"
directory.
The _info.ss_ file is used as in `compile-collection-extension',
except for `compile-extension-omit-files'. In addition, the
following two fields are used:
> compile-zo-omit-files - a list of filenames to extend the
list returned for 'compile-omit-files.
The compilation process is driven by the `managed-compile-zo'
function in the "cm.ss" library of the "mzlib" collection.
> (compile-directory-zos path info-function)
Like `compile-collection-zos', but compiles the given directory
rather than a collection. Also takes an info function (the
result of `get-info' or `get-info/full'; see the setup
collection's documentation for more information) that will be
used to guide compilation instead of looking for an info.ss file
in the directory.
Loading compiler support
------------------------
The compiler unit loads certain tools on demand via `dynamic-require'
and `get-info'. If the namespace used during compilation is different
from the namespace used to load the compiler, or if other load-related
parameters are set, then the following parameter can be used to
restore settings for `dynamic-require'.
> current-compiler-dynamic-require-wrapper
A parameter whose value is a procedure that takes a thunk to
apply. The default wrapper sets the current namespace (via
`parameterize') before calling the thunk; it sets it to the
namespace that was current at the time that the "compiler-unit.ss"
module was evaluated.
---------------------------------------------------------------------------
Options for the Compiler
========================
To set options for the _compile.ss_ extension compiler, use the
_option.ss_ module. Options are set by the following parameters:
> verbose - #t causes the compiler to print
verbose messages about its operations. Default = #f.
> setup-prefix - a string to embed in public names.
This is used mainly for compiling extensions with the collection
name so that cross-extension conflicts are less likely in
architectures that expose the public names of loaded extensions.
Note that `compile-collection' handles prefixing automatically
(by setting this option). Default = "".
> clean-intermediate-files - #t keeps intermediate
.c/.o files. Default = #f.
> compile-subcollections - #t uses info.ss's
'compile-subcollections' for compiling collections. Default = #t.
> compile-for-embedded - #t creates .c files and
object files to be linked directly with an embedded MzScheme
run-time system, instead of .c files and object files to
be dynamically loaded into MzScheme as an extension.
Default = #f.
> propagate-constants - #t improves the code by
propagating constants. Default = #t.
> assume-primitives - #t adds `(require mzscheme)'
to the beginning of the program. This is useful only
with non-`module' code.
Default = #f.
> stupid - Allow obvious non-syntactic errors; e.g.:
((lambda () 0) 1 2 3). Default = #f.
> vehicles - Controls how closures are compiled. The
possible values are: 'vehicles:automatic - auto-groups
'vehicles:functions - groups by procedure
'vehicles:units - usupported
'vehicles:monolithic - groups randomly
Default = 'vehicles:automatic.
> vehicles:monoliths - Sets the number of random
groups for 'vehicles:monolithic.
> seed - Sets the randomizer seed for
'vehicles:monolithic.
> max-exprs-per-top-level-set - Sets the number of
top-level Scheme expressions crammed into one C function. Default
= 25.
> unpack-environments - #f might help for
register-poor architectures. Default = #t.
> debug - #t creates debug.txt debugging file. Default
= #f.
> test - #t ignores top-level expressions with syntax
errors. Default = #f.
More options are defined by the compile.ss and link.ss libraries in
the `dynext' collection . Those options control the actual C compiler
and linker that are used. See doc.txt in the `dynext' collection for
more information about those options.
The _option-unit.ss_ library is a unit exporting the signature
> compiler:option^
which contains these options. The _sig.ss_ library defines the
`compiler:option^' signature.
---------------------------------------------------------------------------
The Compiler as a Unit
======================
The _compiler-unit.ss_ library provides a unit
> compiler@
exporting the signature
> compiler^
which provides the compiler.ss functions. This signature and all
auxiliary signatures needed by compiler@ are defined by the
_sig.ss_ library.
The signed unit requires the following imports:
compiler:option^ - From sig.ss, impl by _option-unit.ss_ or _option.ss_
dynext:compile^ - From the `dynext' collection
dynext:link^
dynext:file^
---------------------------------------------------------------------------
Low-level Extension Compiler and Linker
=======================================
The high-level compiler.ss interface relies on low-level
implementations of the extension compiler and linker.
The _comp-unit.ss_ and _ld-unit.ss_ libraries define units for the
low-level extension compiler and multi-file linker,
> ld@
and
> comp@
respectively.
The low-level compiler functions from comp@ are:
> (eval-compile-prefix expr) - Evaluates an S-expression `expr'.
Future calls to mzc:compile-XXX will see the effects of the
expression.
> (compile-extension scheme-source dest-dir) - Compiles a
single Scheme file to an extension.
> (compile-extension-to-c scheme-source dest-dir) - Compiles
a single Scheme file to a .c file.
> (compile-c-extension c-source dest-dir) - Compiles a single .c
file to an extension.
> (compile-extension-part scheme-source dest-dir) - Compiles a
single Scheme file to a compiled object and .kp file toward a
multi-file extension.
> (compile-extension-part-to-c scheme-source dest-dir) - Compiles
a single Scheme file to .c and .kp files towards a multi-file
extension.
> (compile-c-extension-part c-source dest-dir) - Compiles a single
.c file to a compiled object towards a multi-file extension.
The low-level linker functions from ld@ are:
> (link-extension object-and-kp-file-list dest-dir) - Links
compiled object and .kp files into a multi-file extension.
Both units require the following imports:
dynext:compile^ - From the `dynext' collection
dynext:link^
dynext:file^
compiler:option^ - From sig.ss, impl by _option-unit.ss_ or _option.ss_
---------------------------------------------------------------------------
Embedding Scheme Code to Create a Stand-alone Executable
========================================================
The _embed.ss_ library provides a function to embed Scheme code into a
copy of MzScheme or MrEd, thus creating a _stand-alone_ Scheme
executable. To package the executable into a distribution that is
indpendent of your PLT installation, use `assemble-distribution'
from "distribute.ss"
Embedding walks the module dependency graph to find all modules needed
by some initial set of top-level modules, compiling them if needed,
and combining them into a "module bundle". In addition to the module
code, the bundle extends the module name resolver, so that modules can
be `require'd with their original names, and they will be retrieved
from the bundle instead of the filesystem.
The `make-embedding-executable' function combines the bundle with an
executable (MzScheme or MrEd). The `write-module-bundle' function
prints the bundle to the current output port, instead; this stream can
be `load'ed directly by a running program, as long as the
`read-accept-compiled' parameter is true.
The _embedr-unit.ss_ library provides a unit, _compiler:embed@_
that imports nothing and exports the functions below. The
_embedr-sig.ss_ library provides the signature, _compiler:embed^_.
> (create-embedding-executable dest
[#:modules mod-list]
[#:literal-files literal-file-list]
[#:literal-expression literal-sexp]
[#:cmdline cmdline-list]
[#:mred? mred?]
[#:variant variant]
[#:aux aux]
[#:collects-path path-or-list]
[#:on-extension ext-proc]
[#:launcher? launcher?]
[#:verbose? verbose?]
[#:compiler compile-proc]
[#:expand-namespace expand-namespace]
[#:src-filter src-filter-proc]
[#:get-extra-imports extra-imports-proc])
- Copies the MzScheme (if `mred?' is #f) or MrEd (otherwise) binary,
embedding code into the copied executable to be loaded on startup.
(Under Unix, the binary is actually a wrapper executable that execs
the original; see also 'original-exe? below.)
See the mzc documentation for a simpler interface that is
well-suited to programs defined with `module'.
The embedding executable is written to `dest', which is
overwritten if it exists already (as a file or directory).
The embedded code consists of module declarations followed by
additional (arbitrary) code. When a module is embedded, every module
that it imports is also embedded. Library modules are embedded so
that they are accessible via their `lib' paths in the initial
namespace' except as specified in `mod-list', other modules
(accessed via local paths and absolute paths) are embedded with a
generated prefix, so that they are not directly accessible.
The `mod-list' argument designates modules to be embedded, as
described below. The `literal-file-list' and `literal-sexp'
arguments specify literal code to be copied into the executable:
the content of each file in `literal-file-list' is copied in order
(with no intervening space), followed by `literal-sexp'. The
`literal-file-list' files or `literal-sexp' can contain compiled
bytecode, and it's possible that the content of the
`literal-file-list' files only parse when concatenated; the files
and expression are not compiled or inspected in any way during the
embedding process. If `literal-sexp' is #f, no literal expression is
included in the executable.
The `cmdline-list' argument contains command-line strings that are
prefixed onto any actual command-line arguments that are provided to
the embedding executable. A command-line argument that evaluates an
expression or loads a file will be executed after the embedded code
is loaded.
Each element of the `mod-list' argument is a 2-item list, where the
first item is a prefix for the module name, and the second item is a
module path datum (that's in the format understood by the default
module name resolver). The prefix can be a symbol, #f to indicate no
prefix, or #t to indicate an auto-generated prefix. For example,
'((#f "m.ss"))
embeds the module `m' from the file "m.ss", without prefixing the
name of the module; the `literal-sexpr' argument to go with the
above might be '(require m).
All modules are compiled before they are embedded into the target
executable; see also `compile-proc' below. When a module declares
run-time paths via the forms of MzLib's "runtime-path.ss", the
generated executable records the path (for use both by immediate
execution and for creating a distribution tha contains the
executable).
The optional `aux' argument is an association list for
platform-specific options (i.e., it is a list of pairs where the
first element of the pair is a key symbol and the second element is
the value for that key). The currently supported keys are as
follows:
_'icns_ (Mac OS X) - an icon file path (suffix ".icns") to
use for the executable's desktop icon
_'ico_ (Windows) - an icon file path (suffix ".ico") to
use for the executable's desktop icon; the executable
will have 16x16, 32x32, and 48x48 icons at 4-bit,
8-bit, and 32-bit (RBBA) depths; the icons are
copied and generated from any 16x16, 32x32, and 48x48
icons in the ".ico" file
_'creator_ (Mac OS X) - provides a 4-character string to use as
the application signature
_'file-types_ (Mac OS X) - provides a list of association lists,
one for each type of file handled by the application;
each association is a 2-element list, where the first (key)
element is a string recognized by Finder, and the second
element is a plist value (see doc.tx in the "xml" collection);
see plt/collects/drscheme/drscheme.filetypes for an example
-'resource-files_ (Mac OS X) - extra files to copy into the
"Resources" directory of the generated executable
_'framework-root_ (Mac OS X) - a string to prefix the
executable's path to the MzScheme and MrEd frameworks
(including a separating slash); note that when the
prefix start "@executable_path/" works for a
MzScheme-based application, the corresponding prefix
start for a MrEd-based application is
"@executable_path/../../../"; if #f is supplied, the
executable's framework path is left as-is, otherwise
the original executable's path to a framework is
converted to an absolute path if it was relative
_'dll-dir_ (Windows) - a string/path to a directory that
contains PLT DLLs needed by the executable, such as
"pltmzsch<version>.dll", or a boolean; a path can be
relative to the executable; if #f is supplied, the path
is left as-is; if #t is supplied, the path is dropped
(so that the DLLs must be in the system directory or the
user's PATH); if no value is supplied the original
executable's path to DLLs is converted to an absolute
path if it was relative
_'subsystem_ (Windows) - a symbol, either 'console for a console
application or 'windows for a consoleless application;
the default is 'console for a MzScheme-based application
and 'windows for a MrEd-based application; see also
'single-instance?, below
_'single-instance?_ (Windows) - a boolean for MrEd-based apps; the
default is #t, which means that the app looks for instances
of itself on startup and merely brings the other instance to
the front; #f means that multiple instances are expected
_'forget-exe?_ (Windows, Mac OS X) - a boolean; #t for a launcher
(see `launcher?' below) does not preserve the original
executable name for `(find-system-path 'exec-file)'; the
main consequence is that library collections will be
found relative to the launcher instead of the original
executable
_'original-exe?_ (Unix) - a boolean; #t means that the embedding
uses the original MzScheme or MrEd executable, instead
of a wrapper binary that execs the original; the default is
#f
See also `build-aux-from-path' in the "launcher" collection. The
default `aux' is `null'.
If the #:collects-path argument is #f, then the created executable
maintains its built-in (relative) path to the main "collects"
directory --- which will be the result of `(find-system-path
'collects-dir)' when the executable is run --- plus a potential
list of other directories for finding library collections --- which
are used to initialize the `current-library-collection-paths' list
in combination with "PLTCOLLECTS" environment variable. Otherwise,
the argument specifies a replacement; it must be either a path,
string, or non-empty list of paths and strings. In the last case,
the first path or string specifies the main collection directory,
and the rest are additional directories for the collection search
path (placed, in order, after the user-specific "collects"
directory, but before the main "collects" directory; then the
search list is combined with "PLTCOLLECTS", if it is defined).
If the `on-extension' argument is a procedure, the procedure is
called when the traversal of module dependencies arrives at an
extension (i.e., a DLL or shared object). The default, #f, causes a
reference to a single-module extension (in its current location) to
be embedded into the executable, since an extension itself cannot
be embedded in executables, the default raises an erorr when only a
_loader (instead of a single-module extension) variant is
available. The procedure is called with two arguments: a path for
the extension, and a boolean that is #t if the extension is a
_loader variant.
If `launcher?' is #t, then no `modules' should be null,
`literal-file-list' should be null, `literal-sexp' should be #f,
and the platform should be Windows or Mac OS X. The embedding
executable is created in such a way that `(find-system-path
'exec-file)' produces the source MzScheme or MrEd path instead of
the embedding executable (but the result of `(find-system-path
'run-file)' is still the embedding executable).
The `variant' argument indicates which variant of the original
binary to use for embedding. The default is `(system-type 'gc)';
see `current-launcher-variant' in the "launcher" collection for
more information.
The `compile-proc' argument is used to compile the source of
modules to be included in the executable (when a compiled form is
not already available). It should accept a single argument that is
a syntax object for a `module' form. The default procedure uses
`compile' parameterized to set the current namespace to
`expand-namespace'.
The `expand-namespace' argument selects a namespace for expanding
extra modules (and for compiling using the default `compile-proc').
Extra-module expansion is needed to detect run-time path
declarations in included modules, so that the path resolutions can
be directed to the current locations (and, unltimately, redirected
to copies in a distribution).
The `src-filter-proc' takes a path and returns true if the
corresponding file source be included in the embedding executable
in source form (insteda of compiled form), #f otherwise. The
default returns #f for all paths. Beware that the current output
port may be redirected to the result executable when the filter
procedure is called.
The `extra-imports-proc' takes a source pathname and compiled
module for each module to be included in the executable. It returns
a list of quoted module paths (absolute, as opposed to relative to
the module) for extra modules to be included in the executable in
addition to the modules that the source module `require's,
`require-for-syntax's, and `require-for-template's. For example,
these modules might correspond to reader extensions needed to parse
a module that will be included as source, as long as the reader is
referenced through an absolute module path.
> (make-embedding-executable dest mred? verbose? mod-list literal-file-list literal-sexpr cmdline-list [aux launcher? variant])
Old (keywordless) interface to `create-embedding-executable'.
> (write-module-bundle verbose? mod-list literal-file-list literal-sexpr)
- Like `make-embedding-executable', but the module bundle is written
to the current output port instead of being embedded into an
executable. The output of this function can be `read' to load and
instantiate `mod-list' and its dependencies, adjust the module name
resolver to find the newly loaded modules, evaluate the forms
included from `literal-file-list', and finally evaluate
`literal-sexpr'. The `read-accept-compiled' parameter must be true
to read the stream.
> (embedding-executable-is-directory? mred?) - Returns #t if
Mzscheme/MrEd executables for the current platform correspond to
directories from the user's perspective.
> (embedding-executable-is-actually-directory? mred?) - Returns #t if
Mzscheme/MrEd executables for the current platform are implemented
as directories (as on Mac OS X).
> (embedding-executable-put-file-extension+style+filters mred?) -
Returns three values suitable for use as the `extension', `style',
and `filters' arguments to `put-file', respectively. If
MzScheme/MrEd launchers for this platform are directories, the
`style' result is suitable for use with `get-directory', and the
`extension' result may be a string indicating a required extension
for the directory name (e.g., "app" for Mac OS X).
> (embedding-executable-add-suffix path mred?) - Returns a path with a
suitable executable suffix added, if it's not present already.
Assembling Stand-alone Executables with Shared Libraries
========================================================
The _distribute.ss_ library provides a function to combine a
stand-alone executable created with "embed.ss" with any DLLs,
frameworks, or shared libraries that it needs to run on other machines
(with the same OS).
> (assemble-distribution dest-dir
list-of-exec-files
[#:collects-path path]
[#:copy-collects list-of-dirs])
Copies the executables in `list-of-exec-files' to the directory
`dest-dir', along with DLLs, frameworks, and/or shared libraries
that the executables need to run a different machine.
The arrangement of the executables and support files in `dest-dir'
depends on the platform. In general `assemble-distribution' tries to
do the Right Thing.
If a #:collects-path argument is given, it overrides the default
location of the main "collects" directory for the packaged
executables. It should be relative to the `dest-dir' directory
(typically inside it).
The content of each directory in the #:copy-collects argument is
copied into the main "collects" directory for the packaged
executables.
Packing Stand-alone Executables into a Distribution
===================================================
The _bundle-dist.ss_ library provides a function to pack a directory
(usually assembled by `assemble-distribution') into a distribution
file. Under Windows, the result is a ".zip" archive; under Mac OS X,
it's a ".dmg" disk image; under Unix, it's a ".tgz" archive.
> (bundle-directory dist-file dir [for-exe?])
Packages `dir' into `dist-file'. If `dist-file' has no extension,
a file extension is added automatcially (using the first result
of `bundle-put-file-extension+style+filters').
The created archive contains a directory with the same name as `dir'
--- except under Mac OS X when `for-exe?' is true and `dir' contains
a single a single file or directory, in which case the created disk
image contains just the file or directory. The default for
`for-exe?' is #f.
Archive creation fails if `dist-file' exists.
> (bundle-put-file-extension+style+filters)
Returns three values suitable for use as the `extension', `style',
and `filters' arguments to `put-file', respectively to select
a distribution-file name.

1
collects/compiler/info.ss
View File

@ -1,6 +1,5 @@
(module info setup/infotab
(define doc.txt "doc.txt")
(define name "mzc")
(define scribblings '(("cffi.scrbl")))

311
collects/compiler/ld-unit.ss
View File

@ -1,311 +0,0 @@
(module ld-unit mzscheme
(require (lib "unit.ss")
(lib "list.ss"))
(require "sig.ss")
(require (lib "file-sig.ss" "dynext")
(lib "link-sig.ss" "dynext")
(lib "compile-sig.ss" "dynext"))
(provide ld@)
(define-unit ld@
(import dynext:compile^
dynext:link^
dynext:file^
(prefix compiler:option: compiler:option^))
(export (rename compiler:linker^
[link-extension* link-extension]))
;; Copied from library.ss; please fix me!
(define compiler:bad-chars
(string->list "#+-.*/<=>!?:$%_&~^@;^()[]{}|\\,~\"`' "))
(define (compiler:clean-string s)
(let* ((str (string->list s)))
(list->string
(map (lambda (c) (if (member c compiler:bad-chars)
#\_
c))
str))))
(define (link-extension*
files
dest-dir)
(do-link-extension #t #t files dest-dir))
(define (glue-extension
files
dest-dir)
(do-link-extension #f #t files dest-dir))
(define (glue-extension-source
files
dest-dir)
(do-link-extension #f #f files dest-dir))
(define (do-link-extension
link?
compile?
files
dest-dir)
(define _loader.c (append-c-suffix "_loader"))
(define _loader.o (append-object-suffix "_loader"))
(define _loader.so (append-extension-suffix "_loader"))
(define __ (printf "\"~a\":~n" (build-path dest-dir _loader.c)))
(define all-names
(map
(lambda (file)
(let*-values ([(base name dir?) (split-path file)])
(let ([o (extract-base-filename/o name)]
[kp (extract-base-filename/kp name)])
(cond
[o (list 'o file o)]
[kp (cons 'kp file)]
[else (error 'mzld "file is not a compiled object for constant pool file: ~a"
file)]))))
files))
(define-values (o-files ; just .o files
names ; just .o names
kps) ; just .kp files
(let loop ([l all-names][ofs null][os null][kps null])
(if (null? l)
(values (reverse ofs)
(map path->string (reverse os))
(reverse kps))
(if (eq? (caar l) 'o)
(loop (cdr l) (cons (cadar l) ofs) (cons (caddar l) os) kps)
(loop (cdr l) ofs os (cons (cdar l) kps))))))
(define linker-prefix (compiler:option:setup-prefix))
(define suffixes
(let ([linker-prefix (compiler:clean-string linker-prefix)])
(map
(lambda (name)
(string-append linker-prefix "_" (compiler:clean-string name)))
names)))
(define symbol-table (make-hash-table))
(define (add-symbol s spos pos uninterned?)
(let ([v (hash-table-get symbol-table s (lambda () null))])
(hash-table-put! symbol-table s
(cons (list spos pos) v))))
;; Read in symbol info
(define kp-suffixes/counts
(let loop ([kps kps][kpos 0])
(if (null? kps)
null
(let-values ([(suffix count)
(call-with-input-file (car kps)
(lambda (in)
(let ([info (read in)])
(let ([suffix (car info)]
[symbols (cdadr info)])
(let loop ([l symbols][p 0])
(unless (null? l)
(let ([s (car l)])
;; s might be a list containing a symbol to
;; indicate that it's uninterned
(add-symbol (if (string? s)
(string->symbol s)
(string->uninterned-symbol (car s)))
kpos p
(pair? s)))
(loop (cdr l) (add1 p))))
(values suffix (length symbols))))))])
(let ([rest (loop (cdr kps)
(if (zero? count)
kpos
(add1 kpos)))])
(if (zero? count)
rest
(cons (cons suffix count) rest)))))))
;; Compile content of symbol table into dispatching information
(define symbols (hash-table-map symbol-table (lambda (key info) key)))
(define symbol-dispatches
(apply
append
(hash-table-map
symbol-table
(lambda (key info)
(cons (length info)
(apply append info))))))
(with-output-to-file
(build-path dest-dir _loader.c)
(lambda ()
(printf "#include \"~ascheme.h\"~n"
(if (compiler:option:compile-for-embedded)
""
"e"))
(printf "#include \"mzclink.h\"~n~n")
(for-each
(lambda (suffix)
(printf "extern Scheme_Object * scheme_setup~a(Scheme_Env *e);~n" suffix)
(printf "extern Scheme_Object * scheme_reload~a(Scheme_Env *e);~n" suffix))
suffixes)
(for-each
(lambda (kp-suffix/count)
(let ([suffix (car kp-suffix/count)]
[count (cdr kp-suffix/count)])
(printf "extern Scheme_Object * SYMBOLS~a[~a];~n"
suffix count)))
kp-suffixes/counts)
(printf "~nstatic struct {~n")
(for-each
(lambda (suffix)
(printf " Scheme_Object * ~a_symbol;~n" suffix))
suffixes)
(printf "} syms;~n~n")
(unless (null? symbols)
(printf "static const char *SYMBOL_STRS[~a] = {~n" (length symbols))
(for-each
(lambda (s)
(printf " ~s,~n" (symbol->string s)))
symbols)
(printf "}; /* end of SYMBOL_STRS */~n~n")
(printf "static long SYMBOL_LENS[~a] = {~n" (length symbols))
(for-each
(lambda (s)
(printf " ~s,~n" (string-length (symbol->string s))))
symbols)
(printf "}; /* end of SYMBOL_LENS */~n~n")
(printf "static char SYMBOL_INTERNS[~a] = {~n" (length symbols))
(for-each
(lambda (s)
(printf " ~s,~n" (if (eq? s (string->symbol (symbol->string s))) 1 0)))
symbols)
(printf "}; /* end of SYMBOL_INTERNS */~n~n")
(printf "static const int SYMBOL_DISPATCHES[~a] = {~n " (length symbol-dispatches))
(let loop ([l symbol-dispatches][line 0])
(unless (null? l)
(if (= line 20)
(begin
(printf "~n ")
(loop l 0))
(begin
(printf "~a, " (car l))
(loop (cdr l) (add1 line))))))
(printf "~n}; /* end of SYMBOL_DISPATCHES */~n~n")
(printf "static setup_pooled_symbols(void) {~n Scheme_Object * * symbol_tables[~a];~n int i, j;~n"
(length kp-suffixes/counts))
(let loop ([l kp-suffixes/counts][p 0])
(unless (null? l)
(printf " symbol_tables[~a] = SYMBOLS~a;~n scheme_register_extension_global(&SYMBOLS~a, sizeof(SYMBOLS~a));~n"
p (caar l)
(caar l) (caar l))
(loop (cdr l) (add1 p))))
(printf " for (i = j = 0; i < ~a; i++) {~n" (length symbols))
(printf " Scheme_Object * s;~n")
(printf " int c, k;~n")
(printf " if (SYMBOL_INTERNS[i])~n")
(printf " s = scheme_intern_exact_symbol(SYMBOL_STRS[i], SYMBOL_LENS[i]);~n")
(printf " else~n")
(printf " s = scheme_make_exact_symbol(SYMBOL_STRS[i], SYMBOL_LENS[i]);~n")
(printf " c = SYMBOL_DISPATCHES[j++];~n")
(printf " for (k = c; k--; j += 2)~n")
(printf " symbol_tables[SYMBOL_DISPATCHES[j]][SYMBOL_DISPATCHES[j+1]] = s;~n")
(printf " }~n")
(printf "}~n~n"))
(printf "static Scheme_Object * loader_dispatch(void *v, int argc, Scheme_Object * * argv) {~n")
(printf " Scheme_Env * env = scheme_get_env(scheme_current_config());~n")
(printf " return ((Scheme_Object *(*)(Scheme_Env *))v)(env);~n}~n~n")
(printf "static Scheme_Object * loader_dispatch_all(int argc, Scheme_Object * * argv) {~n")
(printf " Scheme_Env * env = scheme_get_env(scheme_current_config());~n")
(printf " Scheme_Object * v = scheme_void;~n")
(for-each
(lambda (suffix)
(printf " v = LOCAL_PROC(scheme_reload~a)(env);~n"
suffix))
suffixes)
(printf " return v;~n}~n~n")
(printf "static Scheme_Object * loader(int argc, Scheme_Object * * argv) {~n")
(printf " Scheme_Object *a[2];~n")
(printf " Scheme_Object * name = argv[0];~n")
(printf " if (name == scheme_true) {~n")
(printf " a[0] = scheme_make_prim_w_arity(loader_dispatch_all, \"_loader-dispatch-all\", 0, 0);~n")
(printf " a[1] = scheme_false;~n")
(printf " }~n")
(for-each
(lambda (suffix)
(printf " else if (name == syms.~a_symbol) {~n" suffix)
(printf " a[0] = scheme_make_closed_prim_w_arity(loader_dispatch, LOCAL_PROC(scheme_reload~a), \"_loader-dispatch\", 0, 0);~n" suffix)
(printf " a[1] = ~ascheme_module_name();~n" suffix)
(printf " }~n"))
suffixes)
(printf " else {~n")
(printf " a[0] = scheme_false;~n")
(printf " a[1] = scheme_false;~n")
(printf " }~n")
(printf " return scheme_values(2, a);~n}~n~n")
(printf "Scheme_Object * scheme_reload(Scheme_Env * env) {~n")
(printf " return scheme_make_prim_w_arity(loader, \"_loader\", 1, 1);~n}~n~n")
(printf "Scheme_Object * scheme_initialize(Scheme_Env * env) {~n")
(unless (null? symbols)
(printf " setup_pooled_symbols();~n"))
(for-each
(lambda (suffix)
;; (printf " printf(\"~a is %lx\\n\", scheme_setup~a);~n" suffix suffix)
(printf " LOCAL_PROC(scheme_setup~a)(env);~n" suffix))
suffixes)
(printf " scheme_register_extension_global(&syms, sizeof(syms));~n")
(for-each
(lambda (suffix name)
(printf " syms.~a_symbol = scheme_intern_exact_symbol(~s, ~a);~n" suffix name (string-length name)))
suffixes names)
(printf " return scheme_reload(env);~n}~n")
(printf "Scheme_Object * scheme_module_name() { return NULL; }~n"))
'truncate)
(when compile?
(let ([tmp-dir (let ([d (getenv "PLTLDTMPDIR")])
(and d (directory-exists? d) d))])
(compile-extension (not (compiler:option:verbose))
(build-path dest-dir _loader.c)
(build-path dest-dir _loader.o)
(list (collection-path "compiler")))
(when (compiler:option:clean-intermediate-files)
(delete-file (build-path dest-dir _loader.c)))
(if link?
(begin
(link-extension (not (compiler:option:verbose))
(cons (build-path dest-dir _loader.o) o-files)
(build-path (if tmp-dir
tmp-dir
dest-dir)
_loader.so))
(when tmp-dir
(copy-file (build-path tmp-dir _loader.so)
(build-path dest-dir _loader.so))
(delete-file (build-path tmp-dir _loader.so)))
(when (compiler:option:clean-intermediate-files)
(delete-file (build-path dest-dir _loader.o)))
(printf " [output to \"~a\"]~n" (build-path dest-dir _loader.so)))
(printf " [output to \"~a\"]~n" (build-path dest-dir _loader.o))))))))

3
collects/compiler/main.ss
View File

@ -483,9 +483,6 @@
"already up-to-date at")
dest))))
source-files)))]
[(collection-extension)
(compiler-warning)
(apply compile-collection-extension source-files)]
[(collection-zos)
(apply compile-collection-zos source-files)]
[(cc)

25
collects/compiler/sig.ss
View File

@ -5,8 +5,7 @@
(provide compiler:option^
compiler^
compiler:inner^
compiler:linker^)
compiler:inner^)
;; Compiler options
(define-signature compiler:option^
@ -75,20 +74,9 @@
compile-extensions-to-c
compile-c-extensions
compile-extension-parts
compile-extension-parts-to-c
compile-c-extension-parts
link-extension-parts
glue-extension-parts
glue-extension-parts-to-c
compile-zos
compile-collection-extension
compile-collection-zos
compile-directory-extension
compile-directory-zos
current-compiler-dynamic-require-wrapper
@ -99,13 +87,4 @@
(compile-extension
compile-extension-to-c
compile-c-extension
compile-extension-part
compile-extension-part-to-c
compile-c-extension-part
eval-compile-prefix))
;; Low-level multi-file extension linker interface
(define-signature compiler:linker^
(link-extension
glue-extension
glue-extension-source)))
eval-compile-prefix)))

33
collects/make/collection-unit.ss
View File

@ -66,42 +66,13 @@
(unless zo-compiler
(set! zo-compiler (compile-zos #f)))
(zo-compiler (list ss) "compiled"))))
sses zos)]
[ss->c-list
(map (lambda (ss c)
`(,c (,ss)
,(lambda ()
(unless ext-compiler
(set! ext-compiler (compile-extension-parts-to-c #f)))
(parameterize ([compiler:option:setup-prefix
(string-append "_" collection-name)])
(ext-compiler (list ss) (build-path "compiled" "native"))))))
sses cs)]
[c->o-list
(map (lambda (c obj)
`(,obj (,c)
,(lambda ()
(parameterize ([compiler:option:setup-prefix
(string-append "_" collection-name)])
(compile-c-extension-parts (list c) dest-dir)))))
cs objs)]
[o->so
`(,(build-path dest-dir (append-extension-suffix "_loader"))
,objs
,(lambda ()
(parameterize ([compiler:option:setup-prefix (string-append "_" collection-name)])
(link-extension-parts
(append objs kps)
dest-dir))))])
sses zos)])
(unless (directory-exists? "compiled") (make-directory "compiled"))
(unless (or (equal? argv #("zo"))
(directory-exists? dest-dir))
(make-directory* dest-dir))
(make/proc
(append
(list o->so)
`(("zo" ,zos))
ss->zo-list
ss->c-list
c->o-list)
ss->zo-list)
argv)))))

19
collects/plot/pre-installer.ss
View File

@ -1,9 +1,7 @@
(module pre-installer mzscheme
(require (lib "etc.ss") (lib "file.ss") (lib "list.ss")
(lib "file.ss" "dynext") (lib "link.ss" "dynext")
(lib "compile.ss" "dynext")
(lib "compiler.ss" "compiler")
(prefix option: (lib "option.ss" "compiler")))
(lib "compile.ss" "dynext"))
(define top-dir (this-expression-source-directory))
(define src-dir (build-path top-dir "src"))
@ -31,10 +29,6 @@
[else '("-DHAVE_LIBPNG" "-DPLD_png")]))]
;; we compile a simple .so, not an extension
[current-standard-link-libraries '()]
;; no 3m transformation:
[option:3m #f]
[link-variant 'cgc]
[compile-variant 'cgc]
)
(define c-files (filter (lambda (f)
(regexp-match "\\.[cC]$" (path->string f)))
@ -47,7 +41,16 @@
c-files)))
(printf "plot: compiling \"~a\" -> \"~a\"...\n" lib so-name)
(make-directory* tmp-dir)
(compile-c-extension-parts c-files tmp-dir)
(for-each (lambda (c-file)
(compile-extension #f
c-file
(build-path tmp-dir
(append-object-suffix
(path-replace-suffix
c-file
#"")))
null))
c-files)
(parameterize ([current-directory tmp-dir])
(link-extension #f (append
(directory-list tmp-dir)

1
collects/plot/src/fit/fit.c
View File

@ -65,6 +65,7 @@
#include "matrix.h"
#include "fit.h"
#include <math.h>
/* #define STANDARD stderr */

4
collects/plot/src/fit/matrix.c
View File

@ -40,10 +40,10 @@ static char *RCSid = "$Id: matrix.c,v 1.4 2005/03/15 23:21:26 eli Exp $";
#include "fit.h"
#include "matrix.h"
#include <math.h>
// create a simple gc malloc...
typedef struct {
typedef struct Node {
struct Node * next;
void * ptr;
} Node;

2
collects/scribble/html-render.ss
View File

@ -584,7 +584,7 @@
(cond
[(string? i)
(let ([m (and (extra-breaking?)
(regexp-match-positions #rx"[-:/]" i))])
(regexp-match-positions #rx"[-:/+]" i))])
(if m
(list* (substring i 0 (cdar m))
;; Most browsers wrap after a hyphen. The

23
collects/scribblings/guide/running.scrbl
View File

@ -17,8 +17,9 @@ Depending on command-line arguments, MzScheme runs in
@subsection[#:tag "start-interactive-mode"]{Interactive Mode}
When @exec{mzscheme} is run with no command-line arguments, then it
starts a @tech{REPL} with a @litchar{> } prompt:
When @exec{mzscheme} is run with no command-line arguments (other than
confguration options, like @Flag{j}), then it starts a @tech{REPL}
with a @litchar{> } prompt:
@verbatim[" Welcome to MzScheme\n > "]
@ -32,8 +33,9 @@ results. Finally, @exec{mzscheme} loads the file reported by
@scheme[(find-system-path 'init-file)], if it exists, before starting
the @tech{REPL}.
If any command-line arguments are provided, add @Flag{i} or
@DFlag{repl} to re-enable the @tech{REPL}. For example,
If any command-line arguments are provided (other than configuration
options), add @Flag{i} or @DFlag{repl} to re-enable the
@tech{REPL}. For example,
@commandline{mzscheme -q -i}
@ -74,9 +76,9 @@ in addition to the exports of @schememodname[scheme].
@subsection[#:tag "start-module-mode"]{Module Mode}
If a file argument is supplied to @exec{mzscheme} before any
command-line switch, then the file is required as a module, and
(unless @Flag{i}/@DFlag{repl} is specified), no @tech{REPL} is
started. For example,
command-line switch (other than configuration options), then the file
is required as a module, and (unless @Flag{i}/@DFlag{repl} is
specified), no @tech{REPL} is started. For example,
@commandline{mzscheme hello.ss}
@ -100,11 +102,10 @@ The @Flag{l} or @DFlag{lib} flag is similar to
@Flag{t}/@DFlag{require}, but it requires a module using a
@scheme[lib] module path instead of a file path. For example,
@commandline{mzscheme -l help}
@commandline{mzscheme -l compiler}
is the same as running the @exec{plt-help} executable with no
arguments, since the @scheme[help] module is the main @exec{plt-help}
module.
is the same as running the @exec{mzc} executable with no arguments,
since the @scheme[compiler] module is the main @exec{mzc} module.
@; ----------------------------------------

375
collects/scribblings/mzc/api.scrbl Normal file
View File

@ -0,0 +1,375 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
compiler/compiler
compiler/sig
compiler/compiler-unit
compiler/option-unit
compiler/comp-unit
launcher/launcher))
@title{Scheme API for Compilation}
@defmodule[compiler/compiler]{
The @schememodname[compiler/compiler] library provides the
functionality of @exec{mzc} for compilation to bytecode and via C, but
through a Scheme API.}
@; ----------------------------------------------------------------------
@section[#:tag "api:zo"]{Bytecode Compilation}
@defproc[((compile-zos [expr any/c])
[scheme-files (listof path-string?)]
[dest-dir (or/c path-string? false/c (one-of/c 'auto))])
void?]{
Supplying just @scheme[expr] returns a compiler that is initialized
with the expression @scheme[expr], as described below.
The compiler takes a list of Scheme files and compiles each of them to
bytecode, placing the resulting bytecode in a @filepath{.zo} file
within the directory specified by @scheme[dest-dir]. If
@scheme[dest-dir] is @scheme[#f], each bytecode result is placed in
the same directory as its source file. If @scheme[dest-dir] is
@scheme['auto], each bytecode file is placed in a @filepath{compiled}
subdirectory relative to the source; the directory is created if
necessary.
If @scheme[expr] is anything other than @scheme[#f], then a namespace
is created for compiling the files that are supplied later;
@scheme[expr] is evaluated to initialize the created namespace. For
example, @scheme[expr] might load a set of macros. In addition, the
expansion-time part of each expression later compiled is evaluated in
the namespace before being compiled, so that the effects are visible
when compiling later expressions.
If @scheme[expr] is @scheme[#f], then no compilation namespace is
created, and expressions in the files are assumed to compile
independently (so there's no need to evaluate the expansion-time part
of an expression to compile).
Typically, @scheme[expr] is @scheme[#f] for compiling @scheme[module]
files, and it is @scheme[(void)] for compiling files with top-level
definitions and expressions.}
@defproc[(compile-collection-zos [collection string?] ...+)
void?]{
Compiles the specified collection's files to @filepath{.zo} files.
The @filepath{.zo} files are placed into the collection's
@filepath{compiled} directory.
The collection compiler reads the collection's @filepath{info.ss} file
(see @secref[#:doc '(lib "scribblings/reference/reference.scrbl")
"info.ss"]) to obtain information about compiling the collection. The
following fields are used:
@itemize{
@item{@scheme[name] : The name of the collection as a string.}
@item{@scheme[compile-omit-files] : A list of filenames (without
directory paths); all Scheme files in the collection are
compiled except for the files in this list. Files that are
required by other files that are compiled, however, will get
compiled in the process, even when listed with this field.}
@item{@scheme[compile-zo-omit-files] - A List of filenames to extend
the list for @scheme[compile-omit-files]. Historically, this
list of files was not used for other compilation modes that are
no longer supported.}
@item{@scheme[compile-subcollections] : A list of collection paths,
where each path is a list of
strings. @scheme[compile-collection-extension] is applied to
each of the collections.}
}
Only the @scheme[name] field is required from @filepath{info.ss},
since @exec{setup-plt} uses @scheme[name] as an indication that the
collection should be compiled.
The compilation process is driven by @scheme[managed-compile-zo] from
@schememodname[compiler/cm].}
@defproc[(compile-directory-zos [path path-string?]
[info ()])
void?]{
Like @scheme[compile-collection-zos], but compiles the given directory
rather than a collection. The @scheme[info] function behaves like the
result of @scheme[get-info] to supply @filepath{info.ss} fields,
instead of using an @filepath{info.ss} file (if any) in the directory.}
@; ----------------------------------------------------------------------
@section[#:tag "api:ext"]{Compilation via C}
@defproc[((compile-extensions [expr any/c])
[scheme-files (listof path-string?)]
[dest-dir (or/c path-string? false/c (one-of/c 'auto))])
void?]{
Like @scheme[compile-zos], but the @scheme[scheme-files] are compiled
to native-code extensions via C. If @scheme[dest-dir] is
@scheme['auto], each extension file (@filepath{.dll}, @filepath{.so},
or @filepath{.dylib}) is placed in a subdirectory relative to the
source produced by @scheme[(build-path "compiled" "native"
(system-library-subpath))]; the directory is created if necessary.}
@defproc[((compile-extensions-to-c [expr any/c])
[scheme-files (listof path-string?)]
[dest-dir (or/c path-string? false/c (one-of/c 'auto))])
void?]{
Like @scheme[compile-extensions], but only @filepath{.c} files are
produced, not extensions.}
@defproc[(compile-c-extensions
[c-files (listof path-string?)]
[dest-dir (or/c path-string? false/c (one-of/c 'auto))])
void?]{
Compiles each @filepath{.c} file (usually produced with
@scheme[compile-extensions-to-c]) in @scheme[c-files] to an
extension. The @scheme[dest-dir] argument is handled as in
@scheme[compile-extensions]. }
@; ----------------------------------------------------------------------
@section[#:tag "api:loading"]{Loading compiler support}
The compiler unit loads certain tools on demand via @scheme[dynamic-require]
and @scheme[get-info]. If the namespace used during compilation is different
from the namespace used to load the compiler, or if other load-related
parameters are set, then the following parameter can be used to
restore settings for @scheme[dynamic-require].
@defparam[current-compiler-dynamic-require-wrapper
proc
((-> any) . -> . any)]{
A parameter whose value is a procedure that takes a thunk to
apply. The default wrapper sets the current namespace (via
@scheme[parameterize]) before calling the thunk, using the namespace
in which the @scheme[compiler/compiler] library was originally
instantiated.}
@; ----------------------------------------------------------------------
@section[#:tag "api:options"]{Options for the Compiler}
@defmodule[compiler/option]{
The @schememodname[compiler/option] module provides options (in the
form of parameters) that control the compiler's behaviors.}
More options are defined by the @schememodname[dynext/compile] and
@schememodname[dynext/link] libraries, which control the actual C
compiler and linker that are used for compilation via C.
@defboolparam[verbose on?]{
A @scheme[#t] value for the parameter causes the compiler to print
verbose messages about its operations. The default is @scheme[#f].}
@defparam[setup-prefix str string?]{
A parameter that specifies a string to embed in public function names
when compiling via C. This is used mainly for compiling extensions
with the collection name so that cross-extension conflicts are less
likely in architectures that expose the public names of loaded
extensions. The default is @scheme[""].}
@defboolparam[clean-intermediate-files clean?]{
A @scheme[#f] value for the parameter keeps intermediate @filepath{.c}
and @filepath{.o} files generated during compilation via C. The
default is @scheme[#t].}
@defparam[compile-subcollections cols (or/c (listof (listof string?)) (one-of/c #t))]{
A parameter that specifies sub-collections for
@scheme[compile-collection-zos] to compile. A @scheme[#t] value
indicates that the collection's @filepath{info.ss} should be used, or
that sub-collections should be determined automatically by looking for
sub-directories that contain @filepath{info.ss} files. The default is
@scheme[#t].}
@defboolparam[compile-for-embedded embed?]{
A @scheme[#t] values for this parameter creates @filepath{.c} files
and object files to be linked directly with an embedded PLT Scheme
run-time system, instead of @filepath{.c} files and object files to be
dynamically loaded into PLT Scheme as an extension. The default is
@scheme[#f].}
@defboolparam[propagate-constants prop?]{
A parameter to control the compiler's constant propagating when
compiling via C. The default is @scheme[#t].}
@defboolparam[assume-primitives assume?]{
A @scheme[#t] parameter value effectively adds @scheme[(require
mzscheme)] to the beginning of the program. This parameter is useful
only when compiling non-@scheme[module] code. The default is
@scheme[#f].}
@defboolparam[stupid allow?]{
A parameter that allow obvious non-syntactic errors, such as
@scheme[((lambda () 0) 1 2 3)], when compiling via C. The default is
@scheme[#f].}
@defparam[vehicles mode symbol?]{
A parameter that controls how closures are compiled via C. The
possible values are:
@itemize{
@item{@scheme['vehicles:automatic] : automatic grouping}
@item{@scheme['vehicles:functions] : groups within a procedure}
@item{@scheme['vehicles:monolithic] : groups randomly}
}}
@defparam[vehicles:monoliths count exact-nonnegative-integer?]{
A parameter that determines the number of random
groups for @scheme['vehicles:monolithic] mode.}
@defparam[seed val exact-nonnegative-integer?]{
Sets the randomizer seed for @scheme['vehicles:monolithic] mode.}
@defparam[max-exprs-per-top-level-set n exact-nonnegative-integer?]{
A parameter that determines the number of top-level Scheme expressions
crammed into one C function when compiling via C. The default is
@scheme[25].}
@defboolparam[unpack-environments unpack?]{
Setting this parameter to @scheme[#f] might help compilation via C
for register-poor architectures. The default is @scheme[#t].}
@defboolparam[debug on?]{
A @scheme[#t] creates a @filepath{debug.txt} debugging file when
compiling via C. The default is @scheme[#f].}
@defboolparam[test on?]{
A @scheme[#t] value for this parameter causes compilation via C to
ignore top-level expressions with syntax errors. The default is
@scheme[#f].}
@; ----------------------------------------------------------------------
@section[#:tag "api:unit"]{The Compiler as a Unit}
@; ----------------------------------------
@subsection{Signatures}
@defmodule[compiler/sig]
@defsignature/splice[compiler^ ()]{
Includes all of the names exported by
@schememodname[compiler/compiler].}
@defsignature/splice[compiler:option^ ()]{
Includes all of the names exported by
@schememodname[compiler/option].}
@defsignature[compiler:inner^ ()]{
@signature-desc{The high-level @schememodname[compiler/compiler]
interface relies on a low-level implementation of the extension
compiler, which is available from @schememodname[compiler/comp-unit]
as implementing the @scheme[compiler:inner^] signature.}
@defproc[(eval-compile-prefix [expr any/c]) void?]{
Evaluates @scheme[expr]. Future calls to @sigelem[compiler:inner^
compile-extension] or @sigelem[compiler:inner^ compile-extension-to-c]
see the effects of the evaluation.}
@defproc[(compile-extension [scheme-source path-string?]
[dest-dir path-string?])
void?]{
Compiles a single Scheme file to an extension.}
@defproc[(compile-extension-to-c [scheme-source path-string?]
[dest-dir path-string?])
void?]{
Compiles a single Scheme file to a @filepath{.c} file.}
@defproc[(compile-c-extension [c-source path-string?]
[dest-dir path-string?])
void?]{
Compiles a single @filepath{.c} file to an extension.}
}
@; ----------------------------------------
@subsection{Main Compiler Unit}
@defmodule[compiler/compiler-unit]
@defthing[compiler@ unit?]{
Provides the exports of @schememodname[compiler/compiler] in unit
form, where C-compiler operations are imports to the unit.
The unit imports @scheme[compiler:option^], @scheme[dynext:compile^],
@scheme[dynext:link^], and @scheme[dynext:file^]. It exports
@scheme[compiler^].}
@; ----------------------------------------
@subsection{Options Unit}
@defmodule[compiler/option-unit]
@defthing[option@ unit?]{
Provides the exports of @schememodname[compiler/option] in unit
form. It imports no signatures, and exports
@scheme[compiler:option^].}
@; ----------------------------------------
@subsection{Compiler Inner Unit}
@defmodule[compiler/comp-unit]
@defthing[comp@ unit?]{
The unit imports @scheme[compiler:option^], @scheme[dynext:compile^],
@scheme[dynext:link^], and @scheme[dynext:file^]. It exports
@scheme[compiler:inner^].}

45
collects/scribblings/mzc/bundle-api.scrbl Normal file
View File

@ -0,0 +1,45 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
compiler/bundle-dist))
@title{Scheme API for Bundling Distributions}
@defmodule[compiler/bundle-dist]{
The @schememodname[compiler/bundle-dist] library provides a function
to pack a directory (usually assembled by
@scheme[assemble-distribution]) into a distribution file. Under
Windows, the result is a @filepath{.zip} archive; under Mac OS X, it's
a @filepath{.dmg} disk image; under Unix, it's a @filepath{.tgz}
archive.}
@defproc[(bundle-directory [dist-file file-path?]
[dir file-path?]
[for-exe? any/c #f])
void?]{
Packages @scheme[dir] into @scheme[dist-file]. If @scheme[dist-file]
has no extension, a file extension is added automatcially (using the
first result of @scheme[bundle-put-file-extension+style+filters]).
The created archive contains a directory with the same name as
@scheme[dir]---except under Mac OS X when @scheme[for-exe?] is true
and @scheme[dir] contains a single a single file or directory, in
which case the created disk image contains just the file or
directory. The default for @scheme[for-exe?] is @scheme[#f].
Archive creation fails if @scheme[dist-file] exists.}
@defproc[(bundle-put-file-extension+style+filters)
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Returns three values suitable for use as the @scheme[extension],
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
respectively to select a distribution-file name.}

38
collects/scribblings/mzc/dist-api.scrbl Normal file
View File

@ -0,0 +1,38 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
compiler/distribute
launcher/launcher))
@title{Scheme API for Distributing Executables}
@defmodule[compiler/distribute]{
The @schememodname[compiler/distribute] library provides a function to
perform the same work as @exec{mzc --exe} or @exec{mzc --gui-exe}.}
@defproc[(assemble-distribution [dest-dir path-string?]
[exec-files (listof path-string?)]
[#:collects-path path (or/c false/c (and/c path-string? relative-path?)) #f]
[#:copy-collects dirs (listof path-string?) null])
void?]{
Copies the executables in @scheme[exec-files] to the directory
@scheme[dest-dir], along with DLLs, frameworks, and/or shared
libraries that the executables need to run a different machine.
The arrangement of the executables and support files in
@scheme[dest-dir] depends on the platform. In general
@scheme[assemble-distribution] tries to do the Right Thing.
If a @scheme[#:collects-path] argument is given, it overrides the
default location of the main @filepath{collects} directory for the
packaged executables. It should be relative to the @scheme[dest-dir]
directory (typically inside it).
The content of each directory in the @scheme[#:copy-collects] argument
is copied into the main @filepath{collects} directory for the packaged
executables.}

83
collects/scribblings/mzc/dist.scrbl Normal file
View File

@ -0,0 +1,83 @@
#lang scribble/doc
@(require scribble/manual
"common.ss"
(for-label scheme/runtime-path))
@title[#:tag "exe-dist"]{Distributing Stand-Alone Executables}
The command-line flag @DFlag{exe-dir} directs @|mzc| to combine a
stand-alone executable (created via @DFlag{exe} or @DFlag{gui-exe})
with all of the shared libraries that are needed to run it, along with
any run-time files declared via @scheme[define-runtime-path]. The
resulting package can be moved to other machines that run the same
operating system.
After the @DFlag{exe-dir} flag, supply a directory to contain the
combined files for a distribution. Each command-line argument is an
executable to include in the distribution, so multiple executables can
be packaged together. For example, under Windows,
@commandline{mzc --exe-dir geetings hello.exe goodbye.exe}
creates a directory @filepath{greetings} (if the directory doesn't
exist already), and it copies the executables @filepath{hello.exe} and
@filepath{goodbye.exe} into @filepath{greetings}. It also creates a
@filepath{lib} sub-directory in @filepath{greetings} to contain DLLs,
and it adjusts the copied @filepath{hello.exe} and
@filepath{goodbye.exe} to use the DLLs in @filepath{lib}.
The layout of files within a distribution directory is
platform-specific:
@itemize{
@item{Under Windows, executables are put directly into the
distribution directory, and DLLs and other run-time files go
into a @filepath{lib} sub-directory.}
@item{Under Mac OS X, @DFlag{gui-exe} executables go into the
distribution directory, @DFlag{exe} executables go into a
@filepath{bin} subdirectory, and frameworks (i.e., shared
libraries) go into a @filepath{lib} sub-directory along with
other run-time files. As a special case, if the distribution has
a single @DFlag{gui-exe} executable, then the @filepath{lib}
directory is hidden inside the application bundle.}
@item{Under Unix, executables go into a @filepath{bin} subdirectory,
shared libraries (if any) go into a @filepath{lib} subdirectory
along with other run-time files, and wrapped executables are
placed into a @filepath{lib/plt} subdirectory with
version-specific names. This layout is consistent with Unix
installation conventions; the version-specific names for shared
libraries and wrapped executables means that distributions can
be safely unpacked into a standard place on target machines
without colliding with an existing PLT Scheme installation or
other executables created by @|mzc|.}
}
A distribution also has a @filepath{collects} directory that is used
as the main library collection directory for the packaged executables.
By default, the directory is empty. Use @|mzc|'s
@as-index{@DPFlag{copy-collects}} flag to supply a directory whose
content is copied into the distribution's @filepath{collects}
directory. The @DPFlag{copy-collects} flag can be used multiple times
to supply multiple directories.
When multiple executables are disrtibuted together, then separately
creating the executables with @DFlag{exe} and @DFlag{gui-exe} can
generate multiple copies of collection-based libraries that are used
by multiple executables. To share the library code, instead, specify a
target directory for library copies using the
@as-index{@DFlag{collects-dest}} flag with @DFlag{exe} and
@DFlag{gui-exe}, and specify the same directory for each executable
(so that the set of libraries used by all executables are pooled
together). Finally, when packaging the distribution with
@DFlag{exe-dir}, use the @DPFlag{copy-collects} flag to include the
copied libraries in the distribution.
@; ----------------------------------------------------------------------
@include-section["dist-api.scrbl"]
@include-section["bundle-api.scrbl"]

376
collects/scribblings/mzc/exe-api.scrbl Normal file
View File

@ -0,0 +1,376 @@
#lang scribble/doc
@(require scribble/manual
scribble/bnf
(for-label scheme/gui
compiler/compiler
compiler/sig
compiler/compiler-unit
compiler/option-unit
compiler/comp-unit
compiler/distribute
compiler/bundle-dist
scheme/runtime-path
launcher/launcher))
@title{Scheme API for Creating Executables}
@defmodule[compiler/embed]{
The @schememodname[compiler/embed] library provides a function to
embed Scheme code into a copy of MzScheme or MrEd, thus creating a
stand-alone Scheme executable. To package the executable into a
distribution that is indpendent of your PLT installation, use
@scheme[assemble-distribution] from
@schememodname[compiler/distribute].}
Embedding walks the module dependency graph to find all modules needed
by some initial set of top-level modules, compiling them if needed,
and combining them into a ``module bundle.'' In addition to the module
code, the bundle extends the module name resolver, so that modules can
be @scheme[require]d with their original names, and they will be
retrieved from the bundle instead of the filesystem.
The @scheme[create-embedding-executable] function combines the bundle
with an executable (MzScheme or MrEd). The
@scheme[write-module-bundle] function prints the bundle to the current
output port, instead; this stream can be @scheme[load]ed directly by a
running program, as long as the @scheme[read-accept-compiled]
parameter is true.
@defproc[(create-embedding-executable [dest path-string?]
[#:modules mod-list
(listof (list/c (or/c symbol? (one-of/c #t #f))
module-path?))
null]
[#:literal-files literal-files
(listof path-string?)
null]
[#:literal-expression literal-sexp
any/c
null]
[#:cmdline cmdline (listof string?)
null]
[#:mred? mred? any/c #f]
[#:variant variant (one-of/c 'cgc '3m)
(system-type 'gc)]
[#:aux aux (listof (cons/c symbol? any/c)) null]
[#:collects-path collects-path
(or/c false/c
path-string?
(listof path-string?))
#f]
[#:launcher? launcher? any/c #f]
[#:verbose? verbose? any/c #f]
[#:compiler compile-proc (any/c . -> . compiled-expression?)
(lambda (e)
(parameterize ([current-namespace
expand-namespace])
(compile e)))]
[#:expand-namespace expand-namespace namespace? (current-namespace)]
[#:src-filter src-filter (path? . -> . any) (lambda (p) #t)]
[#:on-extension ext-proc
(or/c false/c (path-string? boolean? . -> . any))
#f]
[#:get-extra-imports extras-proc
(path? compiled-module?
. -> . (listof module-path?))
(lambda (p m) null)])
void?]{
Copies the MzScheme (if @scheme[mred?] is @scheme[#f]) or MrEd
(otherwise) binary, embedding code into the copied executable to be
loaded on startup. Under Unix, the binary is actually a wrapper
executable that execs the original; see also the
@scheme['original-exe?] tag for @scheme[aux].
The embedding executable is written to @scheme[dest], which is
overwritten if it exists already (as a file or directory).
The embedded code consists of module declarations followed by
additional (arbitrary) code. When a module is embedded, every module
that it imports is also embedded. Library modules are embedded so that
they are accessible via their @scheme[lib] paths in the initial
namespace except as specified in @scheme[mod-list], other modules
(accessed via local paths and absolute paths) are embedded with a
generated prefix, so that they are not directly accessible.
The @scheme[#:modules] argument @scheme[mod-list] designates modules
to be embedded, as described below. The @scheme[literal-files] and
@scheme[literal-sexp] arguments specify literal code to be copied into
the executable: the content of each file in @scheme[literal-files]
is copied in order (with no intervening space), followed by
@scheme[literal-sexp]. The @scheme[literal-files] files or
@scheme[literal-sexp] can contain compiled bytecode, and it's possible
that the content of the @scheme[literal-files] files only parse
when concatenated; the files and expression are not compiled or
inspected in any way during the embedding process. If
@scheme[literal-sexp] is @scheme[#f], no literal expression is
included in the executable.
The @scheme[#:cmdline] argument @scheme[cmdline] contains command-line
strings that are prefixed onto any actual command-line arguments that
are provided to the embedding executable. A command-line argument that
evaluates an expression or loads a file will be executed after the
embedded code is loaded.
Each element of the @scheme[@:modules] argument @scheme[mod-list] is a
two-item list, where the first item is a prefix for the module name,
and the second item is a module path datum (that's in the format
understood by the default module name resolver). The prefix can be a
symbol, @scheme[#f] to indicate no prefix, or @scheme[#t] to indicate
an auto-generated prefix. For example,
@schemeblock['((#f "m.ss"))]
embeds the module @scheme[m] from the file @filepath{m.ss}, without
prefixing the name of the module; the @scheme[literal-sexpr] argument
to go with the above might be @scheme['(require m)].
All modules are compiled before they are embedded into the target
executable; see also @scheme[compile-proc] below. When a module
declares run-time paths via @scheme[define-runtime-path], the
generated executable records the path (for use both by immediate
execution and for creating a distribution that contains the
executable).
The optional @scheme[aux] argument is an association list for
platform-specific options (i.e., it is a list of pairs where the first
element of the pair is a key symbol and the second element is the
value for that key). The currently supported keys are as follows:
@itemize{
@item{@scheme['icns] (Mac OS X) : An icon file path (suffix
@filepath{.icns}) to use for the executable's desktop icon.}
@item{@scheme['ico] (Windows) : An icon file path (suffix
@filepath{.ico}) to use for the executable's desktop icon;
the executable will have 16x16, 32x32, and 48x48 icons at
4-bit, 8-bit, and 32-bit (RBBA) depths; the icons are copied
and generated from any 16x16, 32x32, and 48x48 icons in the
@filepath{.ico} file.}
@item{@scheme['creator] (Mac OS X) : Provides a 4-character string
to use as the application signature.}
@item{@scheme['file-types] (Mac OS X) : Provides a list of
association lists, one for each type of file handled by the
application; each association is a two-element list, where the
first (key) element is a string recognized by Finder, and the
second element is a plist value. See
@filepath{drscheme.filetypes} in the @filepath{drscheme}
collection for an example.}
@item{@scheme['resource-files] (Mac OS X) : extra files to copy into
the @filepath{Resources} directory of the generated
executable.}
@item{@scheme['framework-root] (Mac OS X) : A string to prefix the
executable's path to the MzScheme and MrEd frameworks
(including a separating slash); note that when the prefix
starts @filepath{@"@"executable_path/} works for a
MzScheme-based application, the corresponding prefix start for
a MrEd-based application is
@filepath{@"@"executable_path/../../../}; if @scheme[#f] is
supplied, the executable's framework path is left as-is,
otherwise the original executable's path to a framework is
converted to an absolute path if it was relative.}
@item{@scheme['dll-dir] (Windows) : A string/path to a directory
that contains PLT DLLs needed by the executable, such as
@filepath{pltmzsch@nonterm{version}.dll}, or a boolean; a path
can be relative to the executable; if @scheme[#f] is supplied,
the path is left as-is; if @scheme[#t] is supplied, the path
is dropped (so that the DLLs must be in the system directory
or the user's @envvar{PATH}); if no value is supplied the
original executable's path to DLLs is converted to an absolute
path if it was relative.}
@item{@scheme['subsystem] (Windows) : A symbol, either
@scheme['console] for a console application or
@scheme['windows] for a consoleless application; the default
is @scheme['console] for a MzScheme-based application and
@scheme['windows] for a MrEd-based application; see also
@scheme['single-instance?], below.}
@item{@scheme['single-instance?] (Windows) : A boolean for
MrEd-based apps; the default is @scheme[#t], which means that
the app looks for instances of itself on startup and merely
brings the other instance to the front; @scheme[#f] means that
multiple instances are expected.}
@item{@scheme['forget-exe?] (Windows, Mac OS X) : A boolean;
@scheme[#t] for a launcher (see @scheme[launcher?] below) does
not preserve the original executable name for
@scheme[(find-system-path 'exec-file)]; the main consequence
is that library collections will be found relative to the
launcher instead of the original executable.}
@item{@scheme['original-exe?] (Unix) : A boolean; @scheme[#t] means
that the embedding uses the original MzScheme or MrEd
executable, instead of a wrapper binary that execs the
original; the default is @scheme[#f].}
}
See also @scheme[build-aux-from-path]. The default @scheme[aux] is
@scheme[null].
If the @scheme[#:collects-path] argument is @scheme[#f], then the
created executable maintains its built-in (relative) path to the main
@filepath{collects} directory---which will be the result of
@scheme[(find-system-path 'collects-dir)] when the executable is
run---plus a potential list of other directories for finding library
collections---which are used to initialize the
@scheme[current-library-collection-paths] list in combination with
@envvar{PLTCOLLECTS} environment variable. Otherwise, the argument
specifies a replacement; it must be either a path, string, or
non-empty list of paths and strings. In the last case, the first path
or string specifies the main collection directory, and the rest are
additional directories for the collection search path (placed, in
order, after the user-specific @filepath{collects} directory, but
before the main @filepath{collects} directory; then the search list is
combined with @envvar{PLTCOLLECTS}, if it is defined).
If the @scheme[#:launcher?] argument is @scheme[#t], then no
@scheme[module]s should be null, @scheme[literal-files] should be
null, @scheme[literal-sexp] should be @scheme[#f], and the platform
should be Windows or Mac OS X. The embedding executable is created in
such a way that @scheme[(find-system-path 'exec-file)] produces the
source MzScheme or MrEd path instead of the embedding executable (but
the result of @scheme[(find-system-path 'run-file)] is still the
embedding executable).
The @scheme[#:variant] argument indicates which variant of the
original binary to use for embedding. The default is
@scheme[(system-type 'gc)]; see also
@scheme[current-launcher-variant].
The @scheme[#:compiler] argument is used to compile the source of
modules to be included in the executable (when a compiled form is not
already available). It should accept a single argument that is a
syntax object for a @scheme[module] form. The default procedure uses
@scheme[compile] parameterized to set the current namespace to
@scheme[expand-namespace].
The @scheme[#:expand-namespace] argument selects a namespace for
expanding extra modules (and for compiling using the default
@scheme[compile-proc]). Extra-module expansion is needed to detect
run-time path declarations in included modules, so that the path
resolutions can be directed to the current locations (and, ultimately,
redirected to copies in a distribution).
The @scheme[#:src-filter] argument takes a path and returns true if
the corresponding file source should be included in the embedding
executable in source form (instead of compiled form), @scheme[#f]
otherwise. The default returns @scheme[#f] for all paths. Beware that
the current output port may be redirected to the result executable
when the filter procedure is called.
If the @scheme[#:on-extension] argument is a procedure, the procedure
is called when the traversal of module dependencies arrives at an
extension (i.e., a DLL or shared object). The default, @scheme[#f],
causes a reference to a single-module extension (in its current
location) to be embedded into the executable. The procedure is called
with two arguments: a path for the extension, and a @scheme[#f] (for
historical reasons).
The @scheme[#:get-extra-imports] argument takes a source pathname and
compiled module for each module to be included in the executable. It
returns a list of quoted module paths (absolute, as opposed to
relative to the module) for extra modules to be included in the
executable in addition to the modules that the source module
@scheme[require]s. For example, these modules might correspond to
reader extensions needed to parse a module that will be included as
source, as long as the reader is referenced through an absolute module
path.}
@defproc[(make-embedding-executable [dest path-string?]
[mred? any/c]
[verbose? any/c]
[mod-list (listof (list/c (or/c symbol? (one-of/c #t #f))
module-path?))]
[literal-files (listof path-string?)]
[literal-sexp any/c]
[cmdline (listof string?)]
[aux (listof (cons/c symbol? any/c)) null]
[launcher? any/c #f]
[variant (one-of/c 'cgc '3m) (system-type 'gc)])
void?]{
Old (keywordless) interface to @scheme[create-embedding-executable].}
@defproc[(write-module-bundle [verbose? any/c]
[mod-list (listof (list/c (or/c symbol? (one-of/c #t #f))
module-path?))]
[literal-files (listof path-string?)]
[literal-sexp any/c])
void?]{
Like @scheme[make-embedding-executable], but the module bundle is
written to the current output port instead of being embedded into an
executable. The output of this function can be @scheme[read] to load
and instantiate @scheme[mod-list] and its dependencies, adjust the
module name resolver to find the newly loaded modules, evaluate the
forms included from @scheme[literal-files], and finally evaluate
@scheme[literal-sexpr]. The @scheme[read-accept-compiled] parameter
must be true to read the stream.}
@defproc[(embedding-executable-is-directory? [mred? any/c]) boolean]{
Indicates whether MzScheme/MrEd executables for the current platform
correspond to directories from the user's perspective. The result is
currently @scheme[#f] for all platforms.}
@defproc[(embedding-executable-is-actually-directory? [mred? any/c])
boolean?]{
Indicates whether MzScheme/MrEd executables for the current platform
actually correspond to directories. The result is @scheme[#t] under
Mac OS X when @scheme[mred?] is @scheme[#t], @scheme[#f] otherwise.}
@defproc[(embedding-executable-put-file-extension+style+filters [mred? any/c])
(values (or/c string? false/c)
(listof (one-of/c 'packages 'enter-packages))
(listof (list/c string? string?)))]{
Returns three values suitable for use as the @scheme[extension],
@scheme[style], and @scheme[filters] arguments to @scheme[put-file],
respectively. If MzScheme/MrEd launchers for this platform are
directories, the @scheme[style] result is suitable for use with
@scheme[get-directory], and the @scheme[extension] result may be a
string indicating a required extension for the directory name (e.g.,
@scheme["app"] for Mac OS X). }
@defproc[(embedding-executable-add-suffix [path path-string?] [mred? any/c])
path-string?]{
Adds a suitable executable suffix, if it's not present already.}
@; ----------------------------------------
@section{Executable Creation Signature}
@defmodule[compiler/embed-sig]
@defsignature/splice[compiler:embed^ ()]{
Includes the identifiers provided by @schememodname[compiler/embed].}
@; ----------------------------------------
@section{Executable Creation Unit}
@defmodule[compiler/embed-unit]
@defthing[compiler:embed@ unit?]{
A unit that imports nothing and exports @scheme[compiler:embed^].}

88
collects/scribblings/mzc/exe.scrbl
View File

@ -3,16 +3,7 @@
"common.ss"
(for-label scheme/runtime-path))
@title[#:tag "exe"]{Creating and Distributing Stand-Alone Executables}
Whether bytecode or native code, the compiled code produced by @|mzc|
relies on MzScheme (or MrEd) to provide run-time support to the
compiled code. However, @|mzc| can also package code together with its
run-time support to form a complete executable, and then the
executable can be packaged into a distribution that works on other
machines.
@section{Stand-Alone Executables from Scheme Code}
@title{Stand-Alone Executables from Scheme Code}
The command-line flag @DFlag{exe} directs @|mzc| to embed a
module, from source or byte code, into a copy of the MzScheme
@ -57,80 +48,9 @@ run it without starting MzScheme, MrEd, or DrScheme. However, the
executable depends on MzScheme and/or MrEd shared libraries, and
possibly other run-time files declared via
@scheme[define-runtime-path]. The executable can be packaged with
support libraries to create a distribution, as described in the
next section.
support libraries to create a distribution, as described in
@secref["exe-dist"].
@; ----------------------------------------------------------------------
@section[#:tag "exe-dist"]{Distributing Stand-Alone Executables}
The command-line flag @DFlag{exe-dir} directs @|mzc| to combine a
stand-alone executable (created via @DFlag{exe} or @DFlag{gui-exe})
with all of the shared libraries that are needed to run it, along with
any run-time files declared via @scheme[define-runtime-path]. The
resulting package can be moved to other machines that run the same
operating system.
After the @DFlag{exe-dir} flag, supply a directory to contain the
combined files for a distribution. Each command-line argument is an
executable to include in the distribution, so multiple executables can
be packaged together. For example, under Windows,
@commandline{mzc --exe-dir geetings hello.exe goodbye.exe}
creates a directory @filepath{greetings} (if the directory doesn't
exist already), and it copies the executables @filepath{hello.exe} and
@filepath{goodbye.exe} into @filepath{greetings}. It also creates a
@filepath{lib} sub-directory in @filepath{greetings} to contain DLLs,
and it adjusts the copied @filepath{hello.exe} and
@filepath{goodbye.exe} to use the DLLs in @filepath{lib}.
The layout of files within a distribution directory is
platform-specific:
@itemize{
@item{Under Windows, executables are put directly into the
distribution directory, and DLLs and other run-time files go
into a @filepath{lib} sub-directory.}
@item{Under Mac OS X, @DFlag{gui-exe} executables go into the
distribution directory, @DFlag{exe} executables go into a
@filepath{bin} subdirectory, and frameworks (i.e., shared
libraries) go into a @filepath{lib} sub-directory along with
other run-time files. As a special case, if the distribution has
a single @DFlag{gui-exe} executable, then the @filepath{lib}
directory is hidden inside the application bundle.}
@item{Under Unix, executables go into a @filepath{bin} subdirectory,
shared libraries (if any) go into a @filepath{lib} subdirectory
along with other run-time files, and wrapped executables are
placed into a @filepath{lib/plt} subdirectory with
version-specific names. This layout is consistent with Unix
installation conventions; the version-specific names for shared
libraries and wrapped executables means that distributions can
be safely unpacked into a standard place on target machines
without colliding with an existing PLT Scheme installation or
other executables created by @|mzc|.}
}
A distribution also has a @filepath{collects} directory that is used
as the main library collection directory for the packaged executables.
By default, the directory is empty. Use @|mzc|'s
@as-index{@DPFlag{copy-collects}} flag to supply a directory whose
content is copied into the distribution's @filepath{collects}
directory. The @DPFlag{copy-collects} flag can be used multiple times
to supply multiple directories.
When multiple executables are disrtibuted together, then separately
creating the executables with @DFlag{exe} and @DFlag{gui-exe} can
generate multiple copies of collection-based libraries that are used
by multiple executables. To share the library code, instead, specify a
target directory for library copies using the
@as-index{@DFlag{collects-dest}} flag with @DFlag{exe} and
@DFlag{gui-exe}, and specify the same directory for each executable
(so that the set of libraries used by all executables are pooled
together). Finally, when packaging the distribution with
@DFlag{exe-dir}, use the @DPFlag{copy-collects} flag to include the
copied libraries in the distribution.
@include-section["exe-api.scrbl"]

15
collects/scribblings/mzc/mzc.scrbl
View File

@ -6,9 +6,15 @@
@title{@exec{mzc}: PLT Compilation and Packaging}
The @exec{mzc} tool is a kind of Swiss-army knife for PLT Scheme
compilation and packaging tasks. Its main action is determined through
one of the following command-line flags:
The @exec{mzc} tool supports various PLT Scheme compilation and
packaging tasks.
@table-of-contents[]
@section{Running @|mzc|}
The main action of @|mzc| is determined through one of the following
command-line flags:
@itemize{
@ -47,9 +53,10 @@ one of the following command-line flags:
@include-section["make.scrbl"]
@include-section["cc.scrbl"]
@include-section["exe.scrbl"]
@include-section["sa.scrbl"]
@include-section["plt.scrbl"]
@include-section["ext.scrbl"]
@include-section["zo.scrbl"]
@include-section["api.scrbl"]
@index-section[]

17
collects/scribblings/mzc/sa.scrbl Normal file
View File

@ -0,0 +1,17 @@
#lang scribble/doc
@(require scribble/manual
"common.ss")
@title[#:tag "exe" #:style 'toc]{Creating and Distributing Stand-Alone Executables}
Whether bytecode or native code, the compiled code produced by @|mzc|
relies on MzScheme (or MrEd) to provide run-time support to the
compiled code. However, @|mzc| can also package code together with its
run-time support to form a complete executable, and then the
executable can be packaged into a distribution that works on other
machines.
@local-table-of-contents[]
@include-section["exe.scrbl"]
@include-section["dist.scrbl"]

49
collects/scribblings/reference/startup.scrbl
View File

@ -64,12 +64,14 @@ any raises an uncaught exception, then the remaining @scheme[eval]s,
After running all command-line expressions, files, and modules,
MzScheme or MrEd then starts a read-eval-print loop for interactive
evaluation if no command line flags are provided. If any command-line
argument is provided, then the read-eval-print-loop is not started,
unless the @Flag{i}/@DFlag{repl} or @Flag{z}/@DFlag{text-repl} flag is
provided on the command line to specifically re-enable it. In
addition, just before the command line is started, MzScheme loads the
file @scheme[(find-system-path 'init-file)] and MrEd loads the file
evaluation if no command line flags are provided other than
@tech{configuration options}. If any command-line argument is
provided that is not a @tech{configuration option}, then the
read-eval-print-loop is not started, unless the @Flag{i}/@DFlag{repl}
or @Flag{z}/@DFlag{text-repl} flag is provided on the command line to
specifically re-enable it. In addition, just before the command line
is started, MzScheme loads the file @scheme[(find-system-path
'init-file)] and MrEd loads the file
@scheme[(find-graphical-system-path 'init-file)] is loaded, unless the
@Flag{q}/@DFlag{no-init-file} flag is specified on the command line.
@ -183,7 +185,7 @@ flags:
}}
@item{Configuration options:
@item{@deftech{Configuration options}:
@itemize{
@ -243,13 +245,18 @@ flags:
}
If at least one command-line argument is provided, and if the first
one is not a flag, then a @Flag{u}/@DFlag{--require-script} flag is
implicitly added before the first argument.
one after any @tech{configuration option} is not a flag, then a
@Flag{u}/@DFlag{--require-script} flag is implicitly added before the
first non-flag argument.
If no command-line arguments are supplied other than
@tech{configuration options}, then the @Flag{i}/@DFlag{--repl} flag is
effectively added.
For MrEd under X11, the follow flags are recognized when they appear
at the beginning of the command line, and they do not otherwise count
as command-line flags (i.e., they do not disable the read-eval-print
loop or prevent the insertion of @Flag{u}/@DFlag{require-script}):
at the beginning of the command line, and they count as configuration
options (i.e., they do not disable the read-eval-print loop or prevent
the insertion of @Flag{u}/@DFlag{require-script}):
@itemize{
@ -282,16 +289,16 @@ loop or prevent the insertion of @Flag{u}/@DFlag{require-script}):
}
Under Mac OS X, a leading switch starting with @FlagFirst{psn_} is
treated specially. It indicates that Finder started the application,
so the current input, output, and error output are redirected to a GUI
window. It does not count as a command-line flag otherwise.
Similarly, under Mac OS X, a leading switch starting with
@FlagFirst{psn_} is treated as a special configuration option. It
indicates that Finder started the application, so the current input,
output, and error output are redirected to a GUI window.
Multiple single-letter switches (the ones preceded by a single @litchar{-}) can
be collapsed into a single switch by concatenating the letters, as long
as the first switch is not @Flag{-}. The arguments for each switch
are placed after the collapsed switches (in the order of the
switches). For example,
Multiple single-letter switches (the ones preceded by a single
@litchar{-}) can be collapsed into a single switch by concatenating
the letters, as long as the first switch is not @Flag{-}. The
arguments for each switch are placed after the collapsed switches (in
the order of the switches). For example,
@commandline{-ifve @nonterm{file} @nonterm{expr}}

1
collects/setup/option-sig.ss
View File

@ -11,7 +11,6 @@
clean
compile-mode
make-zo
make-so
make-info-domain
make-launchers
make-docs

1
collects/setup/option-unit.ss
View File

@ -16,7 +16,6 @@
(define clean (make-parameter #f))
(define compile-mode (make-parameter #f))
(define make-zo (make-parameter #t))
(define make-so (make-parameter #f))
(define make-launchers (make-parameter #t))
(define make-info-domain (make-parameter #t))
(define make-docs (make-parameter #t))

1
collects/setup/plt-single-installer.ss
View File

@ -60,7 +60,6 @@
(when clean?
(clean #t)
(make-zo #f)
(make-so #f)
(make-launchers #f)
(make-info-domain #t)
(call-install #f)))

20
collects/setup/private/doc-path.ss Normal file
View File

@ -0,0 +1,20 @@
#lang scheme/base
(require setup/dirs
setup/main-collects)
(provide doc-path)
(define (doc-path dir name flags)
(cond
[(memq 'main-doc-root flags)
(find-doc-dir)]
[(memq 'user-doc-root flags)
(find-user-doc-dir)]
[(memq 'user-doc flags)
(build-path (find-user-doc-dir) name)]
[(or (memq 'main-doc flags)
(pair? (path->main-collects-relative dir)))
(build-path (find-doc-dir) name)]
[else
(build-path dir "doc" name)]))

13
collects/setup/scribble.ss
View File

@ -2,6 +2,7 @@
(require "getinfo.ss"
"dirs.ss"
"private/doc-path.ss"
scheme/class
scheme/file
setup/main-collects
@ -95,17 +96,7 @@
(cadr d)
(let-values ([(base name dir?) (split-path (car d))])
(path-replace-suffix name #"")))])
(cond
[(memq 'main-doc-root flags)
(find-doc-dir)]
[(memq 'user-doc-root flags)
(find-user-doc-dir)]
[(memq 'user-doc flags)
(build-path (find-user-doc-dir) name)]
[else
(if under-main?
(build-path (find-doc-dir) name)
(build-path dir "doc" name))]))
(doc-path dir name flags))
flags
under-main?
cat)))

2
collects/setup/setup-cmdline.ss
View File

@ -47,8 +47,6 @@
(add-flags '((make-docs #f)))]
[("--no-planet") "Do not setup PLaneT packages"
(add-flags '((make-planet #f)))]
[("-e" "--extension") "Produce native code extensions"
(add-flags '((make-so #t)))]
[("-v" "--verbose") "See names of compiled files and info printfs"
(add-flags '((verbose #t)))]
[("-m" "--make-verbose") "See make and compiler usual messages"

1
collects/setup/setup-go.ss
View File

@ -35,7 +35,6 @@
call-install
call-post-install
make-launchers
make-so
verbose
make-verbose
trust-existing-zos

4
collects/setup/setup-unit.ss
View File

@ -511,7 +511,7 @@
(with-handlers ([exn:fail:filesystem? (warning-handler (void))])
(with-output-to-file fn void #:exists 'truncate/replace))))))))
(when (or (make-zo) (make-so))
(when (make-zo)
(compiler:option:verbose (compiler-verbose))
(compiler:option:compile-subcollections #f))
@ -638,8 +638,6 @@
;; Make .zos
(compile-directory-zos dir info))
make-base-empty-namespace))))
(when (make-so)
(make-it "extensions" compile-directory-extension current-namespace))
;; ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Info-Domain Cache ;;

16
collects/setup/xref.ss
View File

@ -2,8 +2,7 @@
(require scribble/xref
setup/getinfo
setup/dirs
setup/main-collects)
"private/doc-path.ss")
(provide load-collections-xref)
@ -24,18 +23,7 @@
(let-values ([(base name dir?) (split-path (car d))])
(path-replace-suffix name #"")))])
(build-path
(cond
[(memq 'main-doc-root flags)
(find-doc-dir)]
[(memq 'user-doc-root flags)
(find-user-doc-dir)]
[(memq 'user-doc flags)
(build-path (find-user-doc-dir) name)]
[(or (memq 'main-doc flags)
(pair? (path->main-collects-relative dir)))
(build-path (find-doc-dir) name)]
[else
(build-path dir "doc" name)])
(doc-path dir name flags)
"out.sxref"))))
scribblings
categories)))

39
collects/web-server/default-web-root/configuration-table.ss
View File

@ -6,13 +6,20 @@
(default-indices "index.html" "index.htm")
(log-format parenthesized-default)
(messages
(servlet-message "servlet-error.html")
(authentication-message "forbidden.html")
(servlets-refreshed "servlet-refresh.html")
(passwords-refreshed "passwords-refresh.html")
(file-not-found-message "not-found.html")
(protocol-message "protocol-error.html")
(collect-garbage "collect-garbage.html"))
(servlet-message
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/servlet-error.html")
(authentication-message
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/forbidden.html")
(servlets-refreshed
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/servlet-refresh.html")
(passwords-refreshed
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/passwords-refresh.html")
(file-not-found-message
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/not-found.html")
(protocol-message
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/protocol-error.html")
(collect-garbage
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./conf/collect-garbage.html"))
(timeouts
(default-servlet-timeout 30)
(password-connection-timeout 300)
@ -21,10 +28,16 @@
(file-base-connection-timeout 30))
(paths
(configuration-root "conf")
(host-root ".")
(log-file-path "log")
(file-root "htdocs")
(servlet-root ".")
(mime-types "mime.types")
(password-authentication "passwords"))))
(host-root
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/.")
(log-file-path
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./log")
(file-root
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./htdocs")
(servlet-root
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./.")
(mime-types
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./mime.types")
(password-authentication
"/Users/mflatt/proj/plt/collects/web-server/default-web-root/./passwords"))))
(virtual-host-table))

74
src/mzscheme/cmdline.inc
View File

@ -489,6 +489,7 @@ static int run_from_cmd_line(int argc, char *_argv[],
int alternate_rep = 0;
int no_front = 0;
#endif
int was_config_flag = 0, saw_nc_flag = 0;
int no_compiled = 0;
int init_ns = 0, no_init_ns = 0;
FinishArgs *fa;
@ -656,21 +657,6 @@ static int run_from_cmd_line(int argc, char *_argv[],
eval_kind = (int *)malloc(sizeof(int) * argc);
num_enl = 0;
if (!argc) {
/* No args => repl */
use_repl = 1;
init_ns = 1;
} else if ((argv[0][0] != '-') && !is_number_arg(argv[0] + 1)) {
/* No switches => -u mode */
script_mode = 1;
no_more_switches = 1;
sprog = argv[0];
evals_and_loads[num_enl] = argv[0];
eval_kind[num_enl++] = mzcmd_REQUIRE;
argv++;
--argc;
}
while (!no_more_switches && argc && argv[0][0] == '-' && !is_number_arg(argv[0] + 1)) {
real_switch = argv[0];
@ -757,9 +743,11 @@ static int run_from_cmd_line(int argc, char *_argv[],
argv++;
--argc;
collects_path = scheme_make_path(argv[0]);
was_config_flag = 1;
break;
case 'U':
scheme_set_ignore_user_paths(1);
was_config_flag = 1;
break;
case 'S':
if (argc < 2) {
@ -773,9 +761,11 @@ static int run_from_cmd_line(int argc, char *_argv[],
collects_extra = scheme_make_null();
collects_extra = scheme_make_pair(scheme_make_path(argv[0]),
collects_extra);
was_config_flag = 1;
break;
case 'c':
no_compiled = 1;
was_config_flag = 1;
break;
case 'm':
evals_and_loads[num_enl] = "";
@ -878,6 +868,7 @@ static int run_from_cmd_line(int argc, char *_argv[],
argv++;
--argc;
sprog = argv[0];
was_config_flag = 1;
break;
case 'q':
no_init_file = 1;
@ -903,12 +894,15 @@ static int run_from_cmd_line(int argc, char *_argv[],
break;
case 'j':
scheme_set_startup_use_jit(0);
was_config_flag = 1;
break;
case 'd':
scheme_set_startup_load_on_demand(0);
was_config_flag = 1;
break;
case 'b':
scheme_set_binary_mode_stdio(1);
was_config_flag = 1;
break;
#ifdef CMDLINE_STDIO_FLAG
case 'z':
@ -931,10 +925,32 @@ static int run_from_cmd_line(int argc, char *_argv[],
specific_switch[1] = 0;
goto bad_switch;
}
if (was_config_flag)
was_config_flag = 0;
else
saw_nc_flag = 1;
}
argv++;
--argc;
}
}
if (!saw_nc_flag) {
if (!argc) {
/* No args => repl */
use_repl = 1;
init_ns = 1;
} else if ((argv[0][0] != '-') && !is_number_arg(argv[0] + 1)) {
/* No switches => -u mode */
script_mode = 1;
no_more_switches = 1;
sprog = argv[0];
evals_and_loads[num_enl] = argv[0];
eval_kind[num_enl++] = mzcmd_REQUIRE;
argv++;
--argc;
}
argv++;
--argc;
}
if (use_repl) {
@ -1072,7 +1088,7 @@ static int run_from_cmd_line(int argc, char *_argv[],
PROGRAM_LC " [<option> ...] <argument> ...\n"
# ifndef MZSCHEME_CMD_LINE
# ifdef wx_x
" X options (must precede all other options):\n"
" X configuration options (must precede all other options):\n"
" -display <display>, -geometry <geometry>, -fn <font>, -font <font>,\n"
" -bg <color>, -background <color>, -fg <color>, -foreground <color>,\n"
" -iconic, -name <name>, -rv, -reverse, +rv, -selectionTimeout <timeout>,\n"
@ -1120,24 +1136,22 @@ static int run_from_cmd_line(int argc, char *_argv[],
" -- : No argument following this switch is used as a switch\n"
" -h, --help : Show this information and exits, ignoring other options\n"
"Default options:\n"
" If no switches/arguments are provided, -i is assumed.\n"
" If no switch appears before the first argument, -u is inserted.\n"
" If -t/-l/-p/-u apears before the first -i/-e/-f/-r, -n is inserted.\n"
" If only configuration options are provided, -i is added\n"
" If only configuration options are before the first argument, -u is added\n"
" If -t/-l/-p/-u apears before the first -i/-e/-f/-r, -n is added\n"
"Switch syntax:\n"
" Multiple single-letter switches can be collapsed, with arguments placed\n"
" after the collapsed switches; the first collapsed switch cannot be --.\n"
" after the collapsed switches; the first collapsed switch cannot be --\n"
" Example: `-ifve file expr' is the same as `-i -f file -v -e expr'\n"
"Start-up sequence:\n"
" 1. Set `current-library-collection-paths' [unless -x].\n"
" 2. Require `(lib \"" INITIAL_NAMESPACE_MODULE "\")' [when " REPL_FLAGS "/-e/-f/-r, unless -n].\n"
" 3. Evaluate/load expressions/files in order, until first error.\n"
" 4. Load \"" INIT_FILENAME "\" [when " REPL_FLAGS "].\n"
" 5. Run read-eval-print loop [when " REPL_FLAGS "].\n"
" 1. Set `current-library-collection-paths'\n"
" 2. Require `(lib \"" INITIAL_NAMESPACE_MODULE "\")' [when " REPL_FLAGS "/-e/-f/-r, unless -n]\n"
" 3. Evaluate/load expressions/files in order, until first error\n"
" 4. Load \"" INIT_FILENAME "\" [when " REPL_FLAGS "]\n"
" 5. Run read-eval-print loop [when " REPL_FLAGS "]\n"
# ifdef YIELD_BEFORE_EXIT
" 6. Run `(yield 'wait)' [unless -V].\n"
" 6. Run `(yield 'wait)' [unless -V]\n"
# endif
"For general information about " PROGRAM ", see:\n"
" http://www.plt-scheme.org/software/" PROGRAM_LC "/\n"
);
PRINTF(prog, BANNER);
#if defined(WINDOWS_FILE_HANDLES)