This is bigloo.info, produced by makeinfo version 4.5 from bigloo.texi.

  This file documents Bigloo, an implementation of an extended version
of the Scheme programming language.

  Copyright (C) 1992-99, 2000-02 Manuel Serrano

     This program is free software; you can redistribute it
     and/or modify it under the terms of the GNU General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public
     License along with this program; if not, write to the Free
     Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
     MA 02111-1307, USA.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* bigloo: (bigloo).            The Bigloo Scheme compiler
END-INFO-DIR-ENTRY


File: bigloo.info,  Node: SRFIs,  Next: Bigloo Libraries,  Prev: Java Interface,  Up: Top

SRFIs
*****

  Bigloo supports various SRFIs (Scheme Request For Implementation).
Some of them are integrated in the Bigloo core libraries. Some others
are implemented by the means of Bigloo libraries (*note Bigloo
Libraries::). Only the first ones are described in the manual.

  The current Bigloo core library support the following SRFIs:

   * `srfi-0' (Conditional execution).

   * `srfi-2' (AND-LET*: an AND with local bindings, a guarded LET*
     special form).

   * `srfi-6' (Basic String Ports).

   * `srfi-8' (Binding to multiple values).

   * `srfi-9' (_Records_ specification).

   * `srfi-18' (Multithreading support).

   * `srfi-22' (Script interpreter invocation).

   * `srfi-28' (Basic Format Strings).

   * `srfi-30' (Multi-line comments).

SRFI 0
======

 - bigloo syntax: cond-expand [clause]
     The `cond-expand' form tests for the existence of features at
     macro-expansion time. It either expands into the body of one of its
     clauses or signals and error during syntactic processing.
     `cond-expand' expands into the body of the first clause whose
     feature requirement is currently satisfied (the `else' clause, if
     present, is selected if none of the previous clauses is selected).

     A feature requirement has an obvious interpretation as a logical
     formual, where the variables have meaning _true_ is the feature
     corresponding to the feature identifier, as specified in the _SRFI_
     registry, is in effect at the location of the `cond-expand' form,
     and _false_ otherwise. A feature requirement is satisfied it its
     formual is true under this interpretation. The formula may makes
     use of identifier, `and', `or' and `not' operators.

     Examples:

          (write (cond-expand
                    (srfi-0 (* 1 2))
                    (else (+ 3 4))))
             -| 2
          
          (cond-expand
             (bigloo (define (command-line-arguments) (argv)))
             (else (define (command-line-arguments) '())))

     The second example assumes that `bigloo' is an alias for the SRFI
     associated with the specification of Bigloo (i.e. the
     documentation for that Scheme system).

     When writing portable code, the case used for the feature
     identifier should match the one in the SRFI registry. This is to
     ensure that the feature identifier will be correctly recognized
     whether or not the Scheme system is case-sensitive. To support
     case-insensitive Scheme systems, the feature identifiers in the
     SRFI registry are guaranteed to be unique even when ignoring the
     case.

     Bigloo implements differents SRFI for the compiler and the
     interpreter.  Thus, their are two Bigloo SRFI registers. One for
     the compiler and one for the interpreter. Bigloo compiler SRFI
     register contains at least the following symbols:

        * `srfi-0'

        * `srfi-2'

        * `srfi-6'

        * `srfi-8'

        * `srfi-9'

        * `srfi-22'

        * `srfi-28'

        * `srfi-30'

        * `bigloo'

        * `bigloo<major-release>'

        * `bigloo<major-release><minor-release>'

     With respect to the currently used Bigloo back-end, one of these
     symbols is registered:

        * `bigloo-c'

        * `bigloo-jvm'

     Bigloo interpreter implements the following SRFI:

        * `srfi-0'

        * `srfi-6'

        * `srfi-8'

        * `srfi-9'

        * `srfi-22'

        * `srfi-28'

        * `srfi-30'

        * `bigloo'

        * `bigloo-eval'

        * `bigloo<major-release>'

        * `bigloo<major-release><minor-release>'

     When a library is used, the name of the library is added to the
     compiler SRFI register. That is:

          (module foo
             (library srfi-1))
          
          (print (cond-expand (srfi-1 'with-srfi-1) (else 'nothing)))
             -| 'with-srfi-1
          (print (eval '(cond-expand (srfi-1 'with-srfi-1) (else 'nothing))))
             -| 'with-srfi-1

 - bigloo procedure: register-eval-srfi! srfi-name
     This argument SRFI-NAME is a symbol. It registers SRFI-NAME in the
     Bigloo interpreter SRFI register. This function must only be used
     when implementing a library. The code of that library must contain
     one unique call to `register-eval-srfi!'. Let's suppose, for
     instance, a `format' library. The implementation for that library
     must contain an expression like:

          (register-eval-srfi! 'format)

     Calling `(register-eval-srfi! name)' makes `name' supported by
     interpreted `cond-expand' forms.

     _Note:_ There is no `register-compiler-srfi!' because the compiler
     automatically registers SRFI when the `-library' flags are used.
     However, it exists several ways to tell the compiler that it
     actually supports some srfis when compiling some modules.

        * The first way is to insert calls to `register-eval-srfi!' in
          the `.bigloorc' file (*note Compiler Description::).

        * The second, is to use `option' (*note Module Declaration::)
          module clause, such as:

               (module example
                  ...
                  (option (register-srfi! 'srfi-foobar)))
               
               ...

        * The last way is to use the command line option `-srfi' (*note
          Compiler Description::).


SRFI 22
=======

  The SRFI 22 describes basic prerequisites for running Scheme programs
as Unix scripts in a uniform way. A file (henceforth a _scipt_)
conforming SRFI 22 has the following syntax:

     <script>         ==> <script prelude>? <program>
     <script prelude> ==> `#!' <space> <all but linebreak>* <linebreak>

  A Scheme script interpreter loads the `<script>'. It ignores the
script prelude and interprets the rest of the file according to the
language dialect specified by the name of the interpreter.

  The Scheme script interpreter may also load a different file after
making a reasonable check that loading it is semantically equivalent to
loading `<script>'. For example, the script interpreter may assume that
a file with a related name (say, with an additional extension) is a
compiled version of `<script>'.

An example of SRFI-22 script
----------------------------

  Let us consider the following Bigloo script located in a file
`foo.scm':

     #! /usr/bin/env ./execute
     (module foo
        (main main))
     
     (define (main argv)
        (print "foo: " argv))

  Let us consider the following `execute' shell script:

     $ cat > execute
     #!/bin/sh
     bigloo -i $*

  Provided that `foo.scm' as the execute flag switched on, it is
possible to _execute_ it:

     $ chmod u+x foo.scm
     $ ./foo.scm
       -| foo: (./foo.scm)

  The same Bigloo module can be compiled and executed such as:

     $ bigloo foo.scm
     $ ./a.out
       -| foo: (a.out)

Lazy compilation with SRFI-22
-----------------------------

  SRFI-22 can be used to implement _lazy_ compilation. For instance,
let us consider the following shell script:

     $ cat > bgl
     #!/bin/sh
     SOURCEFILE=$1
     case $SOURCEFILE in
         *.scm)
             OUTFILE=${SOURCEFILE%.scm}
             if ( bigloo -s -o $OUTFILE $SOURCEFILE ); then
                 /bin/rm $OUTFILE.o
                 shift
                 ./$OUTFILE $@
             fi
             ;;
         *)
             echo Error: need a \*.scm file!
             ;;
     esac

  And the following Bigloo script:

     #! /usr/bin/env ./bgl
     (module foo
        (main main))
     
     (define (main argv)
        (print "foo: " argv))

  When executed in the following way:

     $ chmod u+x foo.scm
     $ ./foo.scm
       -| foo: (./foo.scm)

  The Bigloo module `foo.scm' will first be compiled and then executed.
Of course, one may consider more complex compiler drivers where it is
first checked that the module is not already compiled.


File: bigloo.info,  Node: DSSSL Support,  Next: Compiler Description,  Prev: Extending the Runtime System,  Up: Top

DSSSL support
*************

  Bigloo supports extensions for the DSSSL expression language
[Dsssl96]:

   * Keywords. Bigloo supports full Dsssl keywords.

   * Named constants. Bigloo implements the three DSSSL named constants:
     `#!optional', `#!rest' and `#!key'.

   * Dsssl formal argument lists.

DSSSL formal argument lists
===========================

  DSSSL formal argument lists are defined by the following grammar:

     <formal-argument-list> ==> <required-formal-argument>*
       [`(#!optional' <optional-formal-argument>*`)']
       [`(#!rest' <rest-formal-argument>`)']
       [`(#!key' <key-formal-argument>*`)']
     <required-formal-argument> ==> <ident>
     <optional-formal-argument> ==> <ident>
          | `('<ident> <initializer>`)'
     <rest-formal-argument> ==> <ident>
     <key-formal-argument> ==> <ident>
          | `('<ident> <initializer>`)'
     <initializer> ==> <expr>

  When a procedure is applied to a list of actual arguments, the formal
and actual arguments are processed from left to right as follows:

   * _Variables_ in _required-formal-arguments_ are bound to successive
     actual arguments starting with the first actual argument. It shall
     be an error if there are fewer actual arguments than
     _required-formal-arguments_.

   * Next, _variables_ in _optional-formal-arguments_ are bound to any
     remaining actual arguments. If there are fewer remaining actual
     arguments than _optional-formal-arguments_, then variables are
     bound to the result of the evaluation of _initializer_, if one was
     specified, and otherwise to `#f'. The _initializer_ is evaluated
     in an environment in which all previous formal arguments have been
     bound.

   * If there is a _rest-formal-argument_, then it is bound to a list
     of all remaining actual arguments. The remaining actual arguments
     are also eligible to be bound to _keyword-formal-arguments_.  If
     there is no _rest-formal-argument_ and there are no
     _keyword-formal-arguments_, the it shall be an error if there are
     any remaining actual arguments.

   * If `#!key' was specified in the _formal-argument-list_, there
     shall be an even number of remaining actual arguments. These are
     interpreted as a series of pairs, where the first member of each
     pair is a keyword specifying the argument name, and the second is
     the corresponding value. It shall be an error if the first member
     of a pair is not a keyword. It shall be an error if the argument
     name is not the same as a variable in a _keyword-formal-argument_,
     unless there  is a _rest-formal-argument_. If the same argument
     name occurs more than once in the list of actual arguments, then
     the first value is used. If there is no actual argument for a
     particular _keyword-formal-argument_, then the variable is bound
     to the result of evaluating _initializer_ if one was specified,
     and otherwise `#f'. The _initializer_ is evaluated in an
     environment in which all previous formal arguments have been bound.

  It shall be an error for an <ident> to appear more than once in a
_formal-argument-list_.

  Example:

     ((lambda (x y) x) 3 4 5 6)   =>(3 4 5 6)
     ((lambda (x y #!rest z) z)
      3 4 5 6)                    => (5 6)
     ((lambda (x y #!optional z #!rest r #!key i (j 1))
         (list x y z i: i j: j))
      3 4 5 i: 6 i: 7)            => (3 4 5 i: 6 j: 1)

Modules and DSSSL formal argument lists
=======================================

  Functions using DSSSL formal argument lists can be exported or
imported in the same way as all regular Bigloo functions. When
exporting such a Dsssl function, the named constants must be included
in the prototype of the function but the formal parameters are not
required. That is, for instance, the exportation prototype for the
function:

     (define (foo x y #!optional z #!key i (j 1)) ...)

looks like:

     (export (foo x y #!optional #!key))


File: bigloo.info,  Node: Compiler Description,  Next: User Extensions,  Prev: DSSSL Support,  Up: Top

Compiler description
********************

C requirement
=============

  Instead of producing assembly code, Bigloo produces C code.  This C
code is ISO-C compliant [IsoC]. So, it is necessary to have an ISO-C
compiler. The current version has been developed with `gcc'
[Stallman95].

JVM requirement
===============

  In order to compile the Bigloo JVM back-end, you have to be provided
with a JDK 1.2 or more recent (available at `http://www.javasoft.com').
The JVM must support for `-noverify' option because, by default, Bigloo
produces JVM code that is not conform to the rules enforced by the Java
byte code verifiers.

Linking
=======

  It is easier to use Bigloo for linking object files which have been
compiled by Bigloo. An easy way to perform this operation is, after
having compiled all the files using the `-c' option, to invoke Bigloo
with the name of the compiled files.

  When Bigloo is only given object file name as argument, it searches
in the current directory and the directory named in the `*load-path*'
list the Scheme source file in order to perform a correct link. Scheme
source files are supposed to be ended by the suffix `.scm'. Additional
suffixes can be added using the `-suffix' option. Hence, if source
files are named foo1.sc and foo2.sc, a link command line could look
like:

     bigloo -suffix sc foo1.o foo2.o -o foo

  Note: In order to understand how the Bigloo linkers operates and which
libraries it uses, it might be useful to  use the `-v2' option which
unveil all the details of the compilation and the link.

The compiler environment and options
====================================

  There are four ways to change the behaviour of Bigloo. Flags on the
command line, the `option' module clause runtime-command file and
environment variables *Note Modules::. When the compiler is invoked, it
first gets the environment variables, then it scans the runtime-command
file and, at end, it parses the command line.  If the same option is
set many times, Bigloo uses the last one.

Efficiency
----------

  In order to get maximum speed, compile with the `-Obench' option.
This will enable all compiler optimization options and disable dynamic
type checks. To improve arithmetic performance see next section.

Stack allocation
----------------

  When the `-fstack' flag is enabled, the compiler may automatically
replace some heap allocations with stack allocations. This may improve
performance because stack allocations are handled more efficiently than
heap allocations. On some cases, `-fstack' may also cause slow down or
memory extra retentions. In this last case, when compile using
`-fstack' the program will consume more memory. Unfortunately, this is
nasty phenomenon is unpredictable (it depends on the nature of the
source file).

Genericity of arithmetic procedures
-----------------------------------

  By default, arithmetic procedures are generic. This means that it is
allowed to use them with flonum and fixnum. This feature, of course,
implies performances penalty. To improve performance, you may use
specialized procedures (such as `+fx', `=fx', ... or `+fl', `=fl', ...)
but, it is possible to suppress the genericity and to make all generic
arithmetic procedures (`=' for example) fixnum ones. For this you must
use the compiler option `-farithmetic', or add the following module
clause `(option (set! *genericity* #f))' in your module declaration.

Safety
------

  It is possible to generate _safe_ or _unsafe_ code.  The safety's
scope is `type', `arity', `version' and `range'.  Let's see an example:

     (define (foo f v indice)
        (car (f (vector-ref v indice))))

  In safe mode, the result of the compilation will be:

     (define (foo f v indice)
       (let ((pair
             (if (and (procedure? f)
                   ;; type check
                   (= (procedure-arity f) 1))
                   ;; arity check
                (if (vector? v)
                   ;; type check
                   (if (and (integer? k)
                         ;; type check
                         (>= k 0)
                         ;; range check
                         (< k (vector-length v)))
                         ;; range check
                     (f (vector-ref v indice))
                     (error ...))
                   (error ...))
                (error ...))))
         (if (pair? pair)
            ;; type check
            (car pair)
            (error ...))))

  It is possible to remove some or all safe checks. For example, here is
the result of the compilation where safe check on types have been
removed:

     (define (foo f v indice)
       (let ((pair (if (= (procedure-arity f) 1)
                  ;; arity check
                  (if (and (>= k 0)
                        ;; range check
                        (< k (vector-length v)))
                        ;; range check
                     (f (vector-ref v indice))
                     (error ...))
                  (error ...))))
          (car pair)))

The runtime-command file
------------------------

  Each Bigloo's user can use a special configuration file. This file
must be named "`.bigloorc'" or "`~/.bigloorc'". Bigloo tries to load
one of these in this order. This file is a Scheme file. Bigloo exports
variables which allow the user to change the behavior of the compiler.
All these variables can be checked using the -help2 option.

  The Bigloo's runtime command file is read before the arguments are
parsed.

The Bigloo command line
-----------------------

  If no input file is specified, Bigloo enters its interpreter.  Here
is the exhaustive list of Bigloo options and configuration variables:


     usage: bigloo [options] [name.suf]
     
     
     Misc:
        -                        Read source code on current input channel
        -help,--help             This help message
        -help2                   The exhaustive help message
        -help-manual             The help message formatted for the manual
        -o FILE                  Name the output FILE
        --to-stdout              Write C code on current output channel
        -c                       Suppress linking and produce a .o file
        -suffix SUFFIX           Recognize suffix as Scheme source
        -afile FILE              Name of the access file (default .afile)
        -access MODULE FILE      Set access between module and file
        -jfile FILE              Name of the Jvm package file (default .jfile)
        -jadd MODULE QTYPE       Set JVM qualifed type name for module
        -main FUN                Set the main function
        -with MODULE             Import addition module
        -multiple-inclusion      Enables multiple inclusions of the Bigloo includes
        -library LIBRARY         Compile/link with additional Bigloo library
        -srfi SRFI               Declares srfi support
        -dload-sym               Emit a Bigloo dynamic loading entry point
        -heapsize SIZE           Set the initial heap size value (in megabyte)
     
     Configuration and path:
        -version                 The current release
        -revision                The current release (short format)
        -query                   Dump the current configuration
        -q                       Do not load any rc file
        -eval STRING             Evaluate STRING
        -I DIR                   Add DIR to the load path
        -lib-dir DIR             Set lib-path to DIR
        -lib-version VERSION     Set the version of the libraries
        -L NAME                  Set additional library path
     
     Back-end:
        -native                  Compile module to native object file (via C)
        -jvm                     Compile module to JVM .class files
        -dotnet                  Compile module to .NET object files
        -saw                     Cut the AST in the saw-mill
        -no-saw                  Disable saw back-ends
        -i                       Interprete module
     
     Dialect:
        -nil                     Evaluate '() as #f in `if' expression
        -call/cc                 Enable call/cc function
        -hygien                  Obsolete (R5rs macros are always supported)
        -fno-reflection          Disable reflection code production
        +fno-reflection          Enable reflection code production
        -farithmetic             Suppress genericity of arithmetic operators
        -fcase-sensitive         Case sensitive reader (default)
        -fcase-insensitive       Case insensitive reader (downcase symbols)
     
     Optimization:
        -Obench                  Benchmarking mode
        -O[2..6]                 Optimization modes
        -fcfa-arithmetic         Enable arithmetic spec. (enabled from -O2)
        -fno-cfa-arithmetic      Disable arithmetic spec.
        -funroll-loop            Enable loop unrolling (enabled from -O3)
        -fno-unroll-loop         Disable loop unrolling
        -fno-loop-inlining       Disable loop inlining
        -floop-inlining          Enable loop inlining (default)
        -fno-inlining            Disable inline optimization
        -fno-user-inlining       Disable user inline optimization
        -fbeta-reduce            Enable simple beta reduction (enable from -O3)
        -fno-beta-reduce         Disable simple beta reduction
        -fdataflow               Enable dataflow optimizations (enable from -O)
        -fno-dataflow            Disable dataflow optimizations
        -fO-macro                Enable Optimization macro (default)
        -fno-O-macro             Disable Optimization macro
     
     Safety:
        -unsafe[atrsvl]          Don't check [type/arity/range/struct/version/library]
     
     Debug:
        -glines                  Emit # line directives
        -gbdb-no-line            Don't emit # line directives
        -gbdb[23]                Compile with bdb debug informations
        -gself                   Enables self compiler debug options
        -gheap                   Enables heap debugging (set with -gbdb2)
        -gmodule                 Debug module initialization
        -g[234]                  Produce Bigloo debug informations
        -cg                      Compile C files with debug option
        -export-all              Eval export-all all routines
        -export-exports          Eval export-exports all routines
        -export-mutable          Enables Eval redefinition of all "::obj" routines
     
     Profiling:
        -p[2]                    Compile files for profiling
        -pg                      Compile files with profiling option
     
     Verbosity:
        -s                       Be silent and inhibit all warning messages
        -v[23]                   Be verbose
        -no-hello                Dont' say hello even in verbose mode
        -w                       Inhibit all warning messages
        -wslots                  Inhibit overriden slots warning messages
        -Wall                    warn about all possible type errors
     
     Compilation modes:
        <-/+>rm                  Don't or force removing .c or .il files
        -extend NAME             Extend the compiler
        -fsharing                Attempt to share constant data
        -fno-sharing             Do not attempt to share constant data
        -fmco                    Produce an .mco file
        -fmco-include-path DIR   Add dir to mco C include path
     
     Native specific options:
        -cc COMPILER             Specify the C compiler
        -stdc                    Generate strict ISO C code
        -copt STRING             Invoke cc with STRING
        -ldopt STRING            Invoke ld with STRING
        -ldpostopt STRING        Invoke ld with STRING (end of arguments)
        --force-cc-o             Force the C compiler to use -o instead of mv
        -ld-relative             Link using -l notation for libraries (default)
        -ld-absolute             Link using absolute path names for libraries
        -static-bigloo           Link with the static bigloo library
        -ld-libs1                Add once user libraries when linking
        -ld-libs2                Add twice user libraries when linking (default)
        -lLIBRARY                Link with host library
     
     Jvm specific options:
        -jvm-shell SHELL         Shell for JVM scripts ("sh", "msdos")
        -jvm-purify              Produce byte code verifier compliant JVM code
        -no-jvm-purify           Don't care about JVM code verifier (default)
        -jvm-mainclass CLASS     JVM main class
        -jvm-classpath PATH      JVM application classpath
        -jvm-bigloo-classpath P  JVM Bigloo rts classpath
        -jvm-path-separator SEP  Set the JVM classpath separator
        -jvm-directory NAME      Directory where to store class files.
        -jvm-catch-errors        Catch internal JVM errors
        -no-jvm-catch-errors     Don't catch internal JVM errors
        -jvm-jarpath NAME        Set the JVM classpath for the produced jar file
        -fjvm-inlining           Enable JVM back-end inlining
        -fjvm-constr-inlining    Enable JVM back-end inlining for constructors
        -fno-jvm-inlining        Disable JVM back-end inlining
        -fno-jvm-constr-inlining Disable JVM back-end inlining for constructors
        -fjvm-peephole           Enable JVM back-end peephole
        -fno-jvm-peephole        Disable JVM back-end peephole
        -fjvm-branch             Enable JVM back-end branch
        -fno-jvm-branch          Disable JVM back-end branch
        -fjvm-fasteq             EQ? no longer works on integers (use =FX)
        -fno-jvm-fasteq          Disable JVM back-end fasteq transformation
        -jvm-env VAR             Make the shell variable visible to GETENV
        -jvm-jar                 Enable JVM jar files generation
        -no-jvm-jar              Disable JVM jar files generation (default)
        -jvm-java FILE           Use FILE as JVM
        -jvm-opt STRING          JVM invocation option
     
     .NET specific options:
        -dotnet-clr FILE         Use FILE as .NET CLR
        -dotnet-clr-style S      Use CLR invokation style
        -dotnet-clr-opt FILE     Use FILE as .NET CLR options
        -dotnet-ld FILE          Use FILE as .NET LD
        -dotnet-ld-style STRING  Use LD invokation style
        -dotnet-dll-path NAME    Set the .NET DLL search path
        -dotnet-external-asm     Enable external assembler (default)
        -no-dotnet-external-asm  Disable external assembler
     
     Traces:
        -t[2|3|4]                Generate a trace file (*)
        +tPASS                   Force pass to be traced
        -shape[mktTalu]          Some debugging tools (private)
     
     Compilation stages:
        -mco                     Stop after .mco production
        -syntax                  Stop after the syntax stage (see -hygiene)
        -expand                  Stop after the preprocessing stage
        -ast                     Stop after the ast construction stage
        -bdb-spread-obj          Stop after the bdb obj spread stage
        -trace                   Stop after the trace pass
        -callcc                  Stop after the callcc pass
        -bivalue                 Stop after the bivaluation stage
        -inline                  Stop after the inlining stage
        -inline+                 Stop after the 2nd inlining stage
        -fail                    Stop after the failure replacement stage
        -fuse                    Stop after the fuse stage
        -user                    Stop after the user pass
        -coerce                  Stop after the type coercing stage
        -effect                  Stop after the effect stage
        -effect+                 Stop after the 2nd effect stage
        -reduce                  Stop after the reduction opt. stage
        -reduce+                 Stop after the 2nd reduction opt. stage
        -assert                  Stop after the assertions stage
        -cfa                     Stop after the cfa stage
        -closure                 Stop after the globalization stage
        -recovery                Stop after the type recovery stage
        -bdb                     Stop after the Bdb code production
        -cnst                    Stop after the constant allocation
        -integrate               Stop after the integration stage
        -egen                    Produce an include file for effects (requires -saw)
        -hgen                    Produce a C header file with class definitions
        -cgen                    Do not C compile and produce a .c file
        -indent                  Produce an indented .c file
        -jvmas                   Produce a JVM .jas file
        -il                      Produce a .NET .asm file
     
     Constant initialization:
        -init-[lib|read|intern]  Constants initialization mode
     
     Bootstrap and setup:
        -mklib                   Compile a library module
        -mkaddlib                Compile an additional library module
        -mkheap                  Build an heap file
        -mkaddheap               Build an additional heap file
        -mkdistrib               Compile a main file for a distribution
        -license                 Display the Bigloo license and exit
        -LICENSE                 Add the license to the generated C files
        -heap NAME               Specify an heap file (or #f to not load heap)
        -dump-heap               Dump the contains of a heap
        -dheap NAME              Dump the contains of a heap
        -addheap NAME            Specify an additional heap file
        -fread-internal          Read source from binary interned file
        -fread-plain             Read source from plain text file
        -target LANG             DON'T USE, (see -native, -jvm, -dotnet)
     
     Shell Variables:
        - TMPDIR
          tmp directory (default "/tmp")
        - BIGLOOLIB
          libraries' directory
        - BIGLOOHEAP
          the initial heap size in megabytes (4 MB by default)
        - BIGLOOSTACKDEPTH
          the error stack depth printing
        - BIGLOOLIVEPROCESS
          the maximum number of Bigloo live processes
     
     Runtime Command file:
        - ~/.bigloorc
     
     
     ------------
      * : only available in developing mode
      . : option enabled from -O3 mode
     
     
     Bigloo Control Variables:
        All the Bigloo control variables can be changed from the
        interpreter, by the means of the `-eval' option, or using
        the module clause `option'. For instance the option
        "-eval '(set! *strip* #t)'" will set the variable
        `*strip*' to the value `#t'.
        These variables are:
     
        - *access-file* :
          The access file name
          default: #f
        - *access-file-default* :
          The default access file name
          default: ".afile"
        - *additional-bigloo-libraries* :
          The user extra Bigloo libraries
          default: ()
        - *additional-bigloo-zips* :
          The user extra Bigloo Zip files
          default: ()
        - *additional-heap-name* :
          A name of an additional heap file name to be build
          default: #f
        - *additional-heap-names* :
          A list of Bigloo additional heap file name
          default: ()
        - *additional-include-foreign* :
          The additional C included files
          default: ()
        - *ast-case-sensitive* :
          Case sensitivity
          default: #t
        - *auto-mode* :
          auto-mode (extend mode) list
          default: (("ml" . "caml") ("mli" . "caml") ("oon" . "meroon"))
        - *bdb-debug* :
          Bdb debugging mode
          default: 0
        - *bigloo-abort?* :
          Do we have the bigloo-abort function in executables?
          default: #f
        - *bigloo-lib-base-name* :
          The Bigloo library base name
          default: ("bigloo" . "2.6b")
        - *bigloo-libraries-translation-table* :
          An assoc table between symbolic lib names and native lib names
          default: ()
        - *bigloo-licensing?* :
          Add the Bigloo license ?
          default: #f
        - *bigloo-name* :
          The Bigloo name
          default: "Bigloo (2.6b)"
        - *bigloo-specific-version* :
          The Bigloo specific version
          default: ""
        - *bigloo-strict-r5rs-strings* :
          Disables/enables non R5Rs string escape sequences
          default: #f
        - *bigloo-tmp* :
          The tmp directory name
          default: "/tmp"
        - *bigloo-user-lib* :
          The user extra C libraries
          default: ("-lm")
        - *bigloo-version* :
          The Bigloo major release number
          default: "2.6b"
        - *bigloo-vlib* :
          The Bigloo library
          default: ("bigloo" . "2.6b")
        - *c-debug* :
          C debugging mode?
          default: #f
        - *c-debug-lines-info* :
          Emit # line directives
          default: #f
        - *c-debug-option* :
          cc debugging option
          default: "-g"
        - *c-files* :
          The C source files
          default: ()
        - *c-object-file-extension* :
          The C object file extension
          default: "o"
        - *c-split-string* :
          C split long strings
          default: #f
        - *c-suffix* :
          C legal suffixes
          default: ("c")
        - *call/cc?* :
          Shall we enable call/cc?
          default: #f
        - *cc* :
          The C compiler
          default: "gcc-2.95"
        - *cc-move* :
          Use mv or -o when C compiling
          default: #t
        - *cc-o-option* :
          The C compiler -o option
          default: "-o "
        - *cc-options* :
          cc options
          default: " -Wpointer-arith -Wswitch -Wtrigraphs"
        - *cc-style* :
          The C compiler style
          default: "gcc"
        - *cflags* :
          The C compiler option
          default: " -Wpointer-arith -Wswitch -Wtrigraphs"
        - *cflags-optim* :
          The C compiler optimization option
          default: "-O3  -Wpointer-arith -Wswitch -Wtrigraphs"
        - *cflags-prof* :
          The C compiler profiling option
          default: "-pg -fno-inline  -Wpointer-arith -Wswitch -Wtrigraphs"
        - *compiler-debug* :
          Debugging level
          default: 0
        - *compiler-sharing-debug?* :
          Compiler self sharing debug
          default: #f
        - *csharp-suffix* :
          C# legal suffixes
          default: ("cs")
        - *debug* :
          The debugging level
          default: 0
        - *debug-module* :
          Module initilazation debugging
          default: 0
        - *default-lib-dir* :
          The default lib dir path (without version)
          default: "/users/serrano/prgm/project/bigloo/lib/2.6b"
        - *dest* :
          The target name
          default: #f
        - *dlopen-init* :
          Emit a standard Bigloo dynamic loading init entry point
          default: #f
        - *dotnet-clr* :
          CLR to be used to run .NET programs
          default: "ilrun"
        - *dotnet-clr-opt* :
          CLR extra options to be used to run .NET programs
          default: "-S 4096 -C 256"
        - *dotnet-clr-style* :
          CLR style to be used to run .NET programs
          default: "pnet"
        - *dotnet-dll-path* :
          Bigloo.dll path
          default: #f
        - *dotnet-external-asm* :
          Force using and external assembler for .NET code
          default: "ilasm"
        - *dotnet-external-asm-style* :
          Force using and external assembler for .NET code
          default: pnet
        - *dotnet-ld* :
          .NET object file linker
          default: "cscc"
        - *dotnet-ld-style* :
          .NET object file linker style
          default: "pnet"
        - *dotnet-shell* :
          .NET object file linker
          default: "sh"
        - *dotnet-use-external-asm* :
          Force using and external assembler for .NET code
          default: #t
        - *double-ld-libs?* :
          Do we include twice the additional user libraries
          default: #t
        - *eval-options* :
          A user variable to store dynamic command line options
          default: ()
        - *extend-entry* :
          Extend entry
          default: #f
        - *garbage-collector* :
          The garbage collector
          default: boehm
        - *gc-custom?* :
          Are we using a custom GC library?
          default: #t
        - *gc-lib* :
          The Gc library
          default: ("bigloogc" . "2.6b")
        - *heap-base-name* :
          The Bigloo heap base name
          default: "bigloo"
        - *heap-debug* :
          Heap debugging mode
          default: 0
        - *heap-debug-copt* :
          Heap debugging C flags
          default: "-DKEEP_BACK_PTRS"
        - *heap-dump-names* :
          The name of the heap to be dumped
          default: ()
        - *heap-jvm-name* :
          The Bigloo heap file name for the JVM backend
          default: "bigloo.jheap"
        - *heap-name* :
          The Bigloo heap file name
          default: "bigloo.heap"
        - *hello* :
          Say hello (when verbose)
          default: #t
        - *include-foreign* :
          The C included files
          default: ("bigloo.h")
        - *include-multiple* :
          Enable/disable multiple inclusion of same file
          default: #f
        - *indent* :
          The name of the C beautifier
          default: ""
        - *init-mode* :
          Module initialization mode
          default: read
        - *inlining-kfactor* :
          Inlining growth factor
          default: #<procedure:8052274.1>
        - *inlining-reduce-kfactor* :
          Inlinine growth factor reductor
          default: #<procedure:80521a4.1>
        - *inlining?* :
          Inlining optimization
          default: #t
        - *interpreter* :
          Shall we interprete the source file?
          default: #f
        - *jvm-bigloo-classpath* :
          JVM Bigloo classpath
          default: #f
        - *jvm-catch* :
          Catch internal errors
          default: #t
        - *jvm-classpath* :
          JVM classpath
          default: "."
        - *jvm-debug* :
          JVM debugging mode?
          default: #f
        - *jvm-directory* :
          JVM object directory
          default: #f
        - *jvm-env* :
          List of environment variables to be available in the compiled code
          default: ()
        - *jvm-foreign-class-id* :
          The identifier of the Jlib foreign class
          default: foreign
        - *jvm-foreign-class-name* :
          The name of the Jlib foreign class
          default: "bigloo.foreign"
        - *jvm-jar?* :
          Enable/disable a JAR file production for the JVM back-end
          default: #f
        - *jvm-jarpath* :
          JVM jarpath
          default: #f
        - *jvm-java* :
          JVM to be used to run Java programs
          default: "java"
        - *jvm-mainclass* :
          JVM main class
          default: #f
        - *jvm-options* :
          JVM options
          default: ""
        - *jvm-path-separator* :
          JVM classpath
          default: #f
        - *jvm-purify* :
          Produce byte code verifier compliant JVM code
          default: #f
        - *jvm-shell* :
          Shell to be used when producing JVM run scripts
          default: "sh"
        - *ld-debug-option* :
          The C linker debugging option
          default: "-g "
        - *ld-library-dir* :
          The ld lib dir path (without version)
          default: "/users/serrano/prgm/project/bigloo/lib"
        - *ld-o-option* :
          The C linker -o option
          default: "-o "
        - *ld-optim-flags* :
          The C linker optimization flags
          default: ""
        - *ld-options* :
          ld options
          default: ""
        - *ld-post-options* :
          ld post options
          default: ""
        - *ld-relative* :
          Relative or absolute path names for libraries
          default: #t
        - *ld-style* :
          ld style
          default: "gcc"
        - *lib-dir* :
          The lib dir path
          default: ("." "/users/serrano/prgm/project/bigloo/lib/2.6b")
        - *lib-mode* :
          Lib-mode compilation?
          default: #f
        - *lib-src-dir* :
          The lib dir path
          default: "./runtime"
        - *load-path* :
          The load path
          default: ("." "/users/serrano/prgm/project/bigloo/lib/2.6b")
        - *max-c-foreign-arity* :
          Max C function arity
          default: 16
        - *max-c-token-length* :
          Max C token length
          default: 1024
        - *mco-include-path* :
          Module checksum C include path
          default: (".")
        - *mco-suffix* :
          Module checksum object legal suffixes
          default: ("mco")
        - *module-checksum-object?* :
          Produce a module checksum object (.mco)
          default: #f
        - *multi-threaded-gc?* :
          Are we using a multi-threaded GC?
          default: #f
        - *o-files* :
          The additional obect files
          default: ()
        - *obj-suffix* :
          Object legal suffixes
          default: ("o" "a" "so")
        - *optim* :
          Optimization level
          default: 0
        - *optim-O-macro?* :
          Enable optimization by macro-expansion
          default: #f
        - *optim-cfa-arithmetic?* :
          Enable refined arithmetic specialization
          default: #f
        - *optim-dataflow?* :
          Enable simple dataflow optimization
          default: #f
        - *optim-integrate?* :
          Enable function integration (closure analysis)
          default: #t
        - *optim-jvm* :
          Enable optimization by inlining jvm code
          default: 0
        - *optim-jvm-branch* :
          Enable JVM branch tensioning
          default: 0
        - *optim-jvm-constructor-inlining* :
          Enable JVM inlining for constructors
          default: 0
        - *optim-jvm-fasteq* :
          EQ? no longer works on integers (use =FX instead)
          default: #f
        - *optim-jvm-inlining* :
          Enable JVM inlining
          default: 0
        - *optim-jvm-peephole* :
          Enable JVM peephole optimization
          default: 0
        - *optim-loop-inlining?* :
          Loop inlining optimization
          default: #t
        - *optim-reduce-beta?* :
          Enable simple beta reduction
          default: #f
        - *optim-unroll-loop?* :
          Loop unrolling optimization
          default: #unspecified
        - *pass* :
          Stop after the pass
          default: ld
        - *prof-table-name* :
          Bprof translation table file name
          default: "bmon.out"
        - *profile-library* :
          Use the profiled library version
          default: #f
        - *profile-mode* :
          Bigloo profile mode
          default: 0
        - *qualified-type-file* :
          The qualifed-type association file name
          default: #f
        - *qualified-type-file-default* :
          The qualifed-type association file name
          default: ".jfile"
        - *reader* :
          The way the reader reads input file ('plain or 'intern)
          default: plain
        - *reflection?* :
          Shall we produce refection code for classes
          default: #t
        - *rm-tmp-files* :
          Shall the .c and .il produced files be removed?
          default: #t
        - *saw* :
          Do we go to the saw-mill?
          default: #f
        - *shared-cnst?* :
          Shared constant compilation?
          default: #t
        - *shell* :
          The shell to exec C compilations
          default: "/bin/sh"
        - *src-files* :
          The sources files
          default: ()
        - *src-suffix* :
          Scheme legal suffixes
          default: ("scm" "bgl")
        - *startup-file* :
          A startup file for the interpreter
          default: #f
        - *static-bigloo?* :
          Do we use the static Bigloo library
          default: #f
        - *stdc* :
          Shall we produced ISO C?
          default: #f
        - *strip* :
          Shall we strip the executable?
          default: #t
        - *target-language* :
          The target language (either C, JVM, or .NET)
          default: native
        - *trace-name* :
          Trace file name
          default: "trace"
        - *trace-write-length* :
          Trace dumping max level
          default: 80
        - *unsafe-arity* :
          Runtime type arity safety
          default: #f
        - *unsafe-library* :
          Use the unsafe library version
          default: #f
        - *unsafe-range* :
          Runtime range safety
          default: #f
        - *unsafe-struct* :
          Runtime struct range safety
          default: #f
        - *unsafe-type* :
          Runtime type safety
          default: #f
        - *unsafe-version* :
          Module version safety
          default: #f
        - *use-private?* :
          Use private construction instead of pragma
          default: #f
        - *user-heap-size* :
          Heap size (in MegaByte) or #f for default value
          default: #f
        - *user-inlining?* :
          User inlining optimization
          default: #t
        - *user-pass* :
          The user specific compilation pass
          default: #unspecified
        - *verbose* :
          The verbosity level
          default: 0
        - *warning* :
          The warning level
          default: #t
        - *warning-overriden-slots* :
          Set to #t to warn about virtual slot overriding
          default: #t
        - *with-files* :
          The additional modules
          default: ()


File: bigloo.info,  Node: User Extensions,  Next: Bee,  Prev: Compiler Description,  Up: Top

User Extensions
***************

  The extension package system allows the language compiled by Bigloo
to be extended and this is achieved by associating an _extension file_
with a suffix. The _extension file_ is loaded at the beginning of a
compilation and it can do three things: call extern programs (unix
programs); define macros; modify the values of some of the compiler's
variables (for example, the list of the libraries to be linked with).
The Bigloo's initializing procedure is the following:

   * If it exists, Bigloo loads the runtime-command file, see Section
     *Note Compiler Description::.

   * It then parses the command line to find the source file to compile.

   * It extracts the source file suffix and looks it up in its
     `*auto-mode*' variable.

   * If the suffix is found, the associated file is loaded. This file
     could contain a function named `*extend-entry*' which must accept
     a list as argument. It is invoked with the Bigloo's unparsed
     arguments.

   * The result of the `*extend-entry*' application has to be a regular
     list of arguments and these are parsed by Bigloo.

  For now, two extension packages exist: the Meroon package which is a
native version of the Christian Queinnec object language; the Camloo
[SerranoWeis94] package which is a front end compiler for the Caml
language [Caml-light]

  Furthermore, Bigloo supports the `-extend' option which forces the
usage of an extension file. When Bigloo encounters this option, it
immediately loads the extension file, invoking the function
`*extend-entry*' with the list of arguments which have not been parsed
yet.

  The extension files are always sought in the directory containing the
Bigloo's libraries.

User pass
=========

  Bigloo allows the user to add a special pass to the regular
compilation, this pass taking place _before_ macro expansion. There are
two ways to add a user pass.

   * Add a compiled pass: The module `user_user' (in the
     "comptime/User/user.scm" file) is the user entry pass point.  To
     add a compiled pass, put the code of the pass in this directory,
     import your new modules in `user_user' and modify the `user-walk'
     function.

   * Add an interpreted pass: Set the value of `*user-pass*', which has
     to be a unary function, in your `.bigloorc' file and Bigloo will
     invoke it with the code as argument.

