1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-07-09 19:00:27 +02:00

fold in ludovic's suggestions for new manual sections

* INSTALL: Update from newest merge

* doc/ref/compiler.texi:
* doc/ref/vm.texi: Fold in Ludovic's suggestions
This commit is contained in:
Andy Wingo 2009-01-15 23:04:06 +01:00
parent 0c91a9105d
commit 86872cc392
3 changed files with 45 additions and 97 deletions

82
INSTALL
View file

@ -2,7 +2,7 @@ Installation Instructions
*************************
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
2006, 2007, 2008 Free Software Foundation, Inc.
2006, 2007 Free Software Foundation, Inc.
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
@ -73,9 +73,9 @@ The simplest way to compile this package is:
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that
the `configure' script does not know about. Run `./configure --help'
for details on some of the pertinent environment variables.
Some systems require unusual options for compilation or linking that the
`configure' script does not know about. Run `./configure --help' for
details on some of the pertinent environment variables.
You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment. Here
@ -100,20 +100,6 @@ architecture at a time in the source code directory. After you have
installed the package for one architecture, use `make distclean' before
reconfiguring for another architecture.
On MacOS X 10.5 and later systems, you can create libraries and
executables that work on multiple system types--known as "fat" or
"universal" binaries--by specifying multiple `-arch' options to the
compiler but only a single `-arch' option to the preprocessor. Like
this:
./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
CPP="gcc -E" CXXCPP="g++ -E"
This is not guaranteed to produce working output in all cases, you
may have to build one architecture at a time and combine the results
using the `lipo' tool if you have problems.
Installation Names
==================
@ -152,36 +138,14 @@ find the X include and library files automatically, but if it doesn't,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.
Particular systems
==================
On HP-UX, the default C compiler is not ANSI C compatible. If GNU
CC is not installed, it is recommended to use the following options in
order to use an ANSI C compiler:
./configure CC="cc -Ae"
and if that doesn't work, install pre-built binaries of GCC for HP-UX.
On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
parse its `<wchar.h>' header file. The option `-nodtk' can be used as
a workaround. If GNU CC is not installed, it is therefore recommended
to try
./configure CC="cc"
and if that doesn't work, try
./configure CC="cc -nodtk"
Specifying the System Type
==========================
There may be some features `configure' cannot figure out
automatically, but needs to determine by the type of machine the package
will run on. Usually, assuming the package is built to be run on the
_same_ architectures, `configure' can figure that out, but if it prints
a message saying it cannot guess the machine type, give it the
There may be some features `configure' cannot figure out automatically,
but needs to determine by the type of machine the package will run on.
Usually, assuming the package is built to be run on the _same_
architectures, `configure' can figure that out, but if it prints a
message saying it cannot guess the machine type, give it the
`--build=TYPE' option. TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:
@ -207,9 +171,9 @@ eventually be run) with `--host=TYPE'.
Sharing Defaults
================
If you want to set default values for `configure' scripts to share,
you can create a site shell script called `config.site' that gives
default values for variables like `CC', `cache_file', and `prefix'.
If you want to set default values for `configure' scripts to share, you
can create a site shell script called `config.site' that gives default
values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists. Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
@ -237,19 +201,11 @@ an Autoconf bug. Until the bug is fixed you can use this workaround:
`configure' Invocation
======================
`configure' recognizes the following options to control how it
operates.
`configure' recognizes the following options to control how it operates.
`--help'
`-h'
Print a summary of all of the options to `configure', and exit.
`--help=short'
`--help=recursive'
Print a summary of the options unique to this package's
`configure', and exit. The `short' variant lists options used
only in the top level, while the `recursive' variant lists options
also present in any nested packages.
Print a summary of the options to `configure', and exit.
`--version'
`-V'
@ -276,16 +232,6 @@ operates.
Look for the package's source code in directory DIR. Usually
`configure' can determine that directory automatically.
`--prefix=DIR'
Use DIR as the installation prefix. *Note Installation Names::
for more details, including other options available for fine-tuning
the installation locations.
`--no-create'
`-n'
Run the configure checks, but stop before creating any output
files.
`configure' also accepts some other, not widely useful, options. Run
`configure --help' for more details.

View file

@ -120,7 +120,7 @@ fast.
There is a notion of a ``current language'', which is maintained in
the @code{*current-language*} fluid. This language is normally Scheme,
and may be rebound by the user. The runtime compilation interfaces
and may be rebound by the user. The run-time compilation interfaces
(@pxref{Read/Load/Eval/Compile}) also allow you to choose other source
and target languages.
@ -319,7 +319,7 @@ Return an existing or new toplevel variable named @var{sym}.
@var{toplevel-env} must be a toplevel environment.
@end deffn
@deffn {Scheme Procedure} ghil-var-at-module! env modname sym interface?
Return a variable that will be resolved at runtime with respect to a
Return a variable that will be resolved at run-time with respect to a
specific module named @var{modname}. If @var{interface?} is true, the
variable will be of type @code{public}, otherwise @code{private}.
@end deffn
@ -459,7 +459,7 @@ Like Scheme's @code{values}.
@var{vals})}.
@end deftp
@deftp {Scheme Variable} <ghil-reified-env> env loc
Produces, at runtime, a reification of the environment at compile
Produces, at run-time, a reification of the environment at compile
time. Used in the implementation of Scheme's
@code{compile-time-environment}.
@end deftp
@ -476,7 +476,7 @@ Just as the Scheme to GHIL compiler introduced new hidden state---the
environment---the GHIL to GLIL compiler introduces more state, the
stack. While not represented explicitly, the stack is present in the
compilation of each GHIL expression: compiling a GHIL expression
should leave the runtime value stack in the same state. For example,
should leave the run-time value stack in the same state. For example,
if the intermediate value stack has two elements before evaluating an
@code{if} expression, it should have two elements after that
expression.
@ -495,7 +495,7 @@ Its expression types are defined in @code{(language glil)}, and as
with GHIL, some of its fields parse as rest arguments.
@deftp {Scheme Variable} <glil-program> nargs nrest nlocs nexts meta . body
A unit of code that at runtime will correspond to a compiled
A unit of code that at run-time will correspond to a compiled
procedure. @var{nargs} @var{nrest} @var{nlocs}, and @var{nexts}
collectively define the program's arity; see @ref{Compiled
Procedures}, for more information. @var{meta} should be an alist of
@ -681,7 +681,7 @@ Probably the most important improvement, speed-wise, will be some form
of native compilation, both just-in-time and ahead-of-time. This could
be done in many ways. Probably the easiest strategy would be to extend
the compiled procedure structure to include a pointer to a native code
vector, and compile from bytecode to native code at runtime after a
vector, and compile from bytecode to native code at run-time after a
procedure is called a certain number of times.
The name of the game is a profiling-based harvest of the low-hanging

View file

@ -8,7 +8,7 @@
@section A Virtual Machine for Guile
Guile has both an interpreter and a compiler. To a user, the
difference is largely transparent -- interpreted and compiled
difference is largely transparent---interpreted and compiled
procedures can call each other as they please.
The difference is that the compiler creates and interprets bytecode
@ -32,9 +32,11 @@ machine.
@node Why a VM?
@subsection Why a VM?
For a long time, Guile only had an interpreter, called the evaluator.
Guile's evaluator operates directly on the S-expression representation
of Scheme source code.
@cindex interpreter
@cindex evaluator
For a long time, Guile only had an interpreter, called the
@dfn{evaluator}. Guile's evaluator operates directly on the
S-expression representation of Scheme source code.
But while the evaluator is highly optimized and hand-tuned, and
contains some extensive speed trickery (@pxref{Memoization}), it still
@ -47,7 +49,7 @@ be allocated on the heap. Et cetera.
The solution to this problem is to compile the higher-level language,
Scheme, into a lower-level language for which all of the checks and
dispatching have already been done -- the code is instead stripped to
dispatching have already been done---the code is instead stripped to
the bare minimum needed to ``do the job''.
The question becomes then, what low-level language to choose? There
@ -63,8 +65,8 @@ present on all Guile installations.
The easiest (and most fun) way to depend on a virtual machine is to
implement the virtual machine within Guile itself. This way the
virtual machine provides what Scheme needs (tail calls, multiple
values, call/cc) and can provide optimized inline instructions for
Guile (cons, struct-ref, etc.).
values, @code{call/cc}) and can provide optimized inline instructions
for Guile (@code{cons}, @code{struct-ref}, etc.).
So this is what Guile does. The rest of this section describes that VM
that Guile implements, and the compiled procedures that run on it.
@ -72,7 +74,7 @@ that Guile implements, and the compiled procedures that run on it.
Note that this decision to implement a bytecode compiler does not
preclude native compilation. We can compile from bytecode to native
code at runtime, or even do ahead of time compilation. More
possibilities are discussed in @xref{Extending the Compiler}.
possibilities are discussed in @ref{Extending the Compiler}.
@node VM Concepts
@subsection VM Concepts
@ -84,7 +86,7 @@ virtual machine per thread. When a VM-compiled procedure is run, Guile
looks up the virtual machine for the current thread and executes the
procedure using that VM.
Guile's virtual machine is a stack machine -- that is, it has few
Guile's virtual machine is a stack machine---that is, it has few
registers, and the instructions defined in the VM operate by pushing
and popping values from a stack.
@ -114,7 +116,7 @@ is described in the next section.
A virtual machine executes by loading a compiled procedure, and
executing the object code associated with that procedure. Of course,
that procedure may call other procedures, tail-call others, ad
infinitum -- indeed, within a guile whose modules have all been
infinitum---indeed, within a guile whose modules have all been
compiled to object code, one might never leave the virtual machine.
@c wingo: I wish the following were true, but currently we just use
@ -189,8 +191,8 @@ The @code{ip} to return to if this application returns multiple
values. For continuations that only accept one value, this value will
be @code{NULL}; for others, it will be an @code{ip} that points to a
multiple-value return address in the calling code. That code will
expect the top value on the stack to be an integer -- the number of
values being returned -- and that below that integer there are the
expect the top value on the stack to be an integer---the number of
values being returned---and that below that integer there are the
values being returned.
@item Dynamic link
@ -320,7 +322,7 @@ Bytecode:
At @code{ip} 0 and 2, we do the copy from argument to heap for
@code{a}. @code{Ip} 4 loads up the compiled lambda, and then at
@code{ip} 6 we make a closure -- binding code (from the compiled
@code{ip} 6 we make a closure---binding code (from the compiled
lambda) with data (the heap-allocated variables). Finally we return
the closure.
@ -385,7 +387,7 @@ instructions. More instructions may be added over time.
@subsubsection Environment Control Instructions
These instructions access and mutate the environment of a compiled
procedure -- the local bindings, the ``external'' bindings, and the
procedure---the local bindings, the ``external'' bindings, and the
toplevel bindings.
@deffn Instruction local-ref index
@ -575,7 +577,7 @@ procedure. This instruction pops the following values from the stack:
@itemize
@item Optionally, a thunk, which when called should return metadata
associated with this program -- for example its name, the names of its
associated with this program---for example its name, the names of its
arguments, its documentation string, debugging information, etc.
Normally, this thunk its itself a compiled procedure (with no
@ -852,7 +854,7 @@ to avoid the overhead of creating new stack frames.
Since most of these operations are historically implemented as C
primitives, not inlining them would entail constantly calling out from
the VM to the interpreter, which has some costs -- registers must be
the VM to the interpreter, which has some costs---registers must be
saved, the interpreter has to dispatch, called procedures have to do
much typechecking, etc. It's much more efficient to inline these
operations in the virtual machine itself.