; Copyright 1998 Lars T Hansen.
;
; $Id: help-topics.txt 5870 2008-12-19 22:04:52Z will $
;
; Help topics for development environment's help system
; Entry format: 
;   <entry> ::= (<tag> <descriptor> <text> ...)
;   <tag> ::= <symbol>
;   <descriptor> ::= <string>
;   <text> ::= ((<selector> ...) <string>)
;   <selector> ::= <brevity> | <system>
;   <brevity>  ::= brief | full
;   <system>   ::= native | petit | common
;
; Every text should have both <brevity> and <system> selectors.
; If not, the current help system will never display the text.

(compiling 
"  compiling          Compiling and assembling Scheme programs."
((brief full native petit common)
"(compile-file <schemefile>)
(compile-file <schemefile> <outputfile>)
  Compile the Scheme source file and produce a .fasl file.
")

((full native)
"
(assemble-file <asm-file>)
(assemble-file <asm-file> <outputfile>)
  Assemble the .lap or .mal source file and produce a .fasl file.
")
((brief full petit common)
"(compile-files (<schemefile> ...) <outputfile>)
  Compile the Scheme source files and produce a .fasl file referencing
  a native shared object; when the .fasl file is loaded, the shared
  object is dynamically linked into Larceny.
")
((obsolete native petit)
"
(compile313 <schemefile> &opt <outputfile>)
  Compile the Scheme source file and produce a .lap file.

(assemble313 <lapfile> &opt <outputfile>)
  Assemble a .lap or .mal source file and produce a .lop file.
")

((obsolete native)
"
(make-fasl <lopfile> &opt <outputfile>)
  Create a fast-load file (.fasl) from the object file.
"))

(compiler-switches
"  compiler-switches  Info about a slew of compiler switches."
((brief full native petit common)
"
The command (compiler-switches) lists the current settings of all compiler
and assembler switches.  These switches are:

Debugging:
  issue-warnings             Display warning messages.
  include-procedure-names    Compiled code will contain the procedure name.
  include-variable-names     Compiled code will contain variable names.
  include-source-code        Compiled code will contain source code.
  single-stepping            Insert singlestepping support code.

Safety:
  avoid-space-leaks          Generate code to clear stale registers.
  write-barrier              Generate code for generational GC.
  runtime-safety-checking    Check for illegal arguments and other errors.
    catch-undefined-globals  Check references to global variables.

Speed:
  integrate-procedures       Generate in-line code for primitive procedures.
  faster-arithmetic          Omit some checking in fixnum/flonum arithmetic.
  control-optimization       Improve code for IF, AND, OR, COND, CASE.
  parallel-assignment-optimization    Choose a good order of evaluation.
  lambda-optimization        Improve code for known local procedures.
  benchmark-mode             Assume that self-recursive global procedures
                             will not be redefined.
  benchmark-block-mode       Assume that variables will not be assigned
                             outside of the file in which they are defined.
  global-optimization        Perform a flow analysis to support:
    interprocedural-inlining                of small known local procedures.
    interprocedural-constant-propagation    and constant folding.
    common-subexpression-elimination        of redundant expressions.
    representation-inference                to suppress redundant checking.
  local-optimization         Eliminate branches to branches and locally
                             redundant machine instructions.
  peephole-optimization      Improve common sequences of machine code.
  inline-allocation          Generate in-line code for CONS, et cetera.
  fill-delay-slots           Fill SPARC branch delay slots.
")
((obsolete native petit common)
"
Internal (development) switches:
  listify?                   Produce listing of MAL code.  (NOTE: a variable)
")
((brief full petit native)
"
The command (compiler-switches <flag>) sets groups of switches depending
on the value of the symbol <flag>.  The flags are:
  slow          Turn off all optimizations.
  standard      Enable all semantics-preserving optimizations.
  fast-safe     Enable all optimizations (except benchmark-block-mode)
                but generate code to perform all run-time type and range
                checks that are needed for safety.
  fast-unsafe   Enable all optimizations (except benchmark-block-mode)
                and disable type and range checking.
  default       Set switches to their default (factory) settings.

All switches can be set to #t to enable the effect explained above, or
to #f to disable the effect.  For example, (benchmark-mode #f) disables
benchmark mode.
"))

(disassembling
"  disassembling      Disassembling compiled code."
((brief full native)
"(disassemble <procedure>)
  Disassemble the code vector of the procedure, printing the instructions
  to the current output port.

(disassemble-file <inputfile>)
(disassemble-file <inputfile> <outputfile>)
  Disassemble all code and constant vectors of the <inputfile>, which
  must be a .fasl or .lop format file, and print the disassembly listing
  on the current output port or to the given <outputfile>.
")
((brief full petit)
"There are no disassembly operations in Petit Larceny.
"))

  
(general
"  general            General information about file types etc."
((brief full petit native common)
"R5RS Scheme source files usually have names ending in .sch or
.scm; these extensions are treated specially by the compiler.
You may compile source files with extensions other than these,
but the compiler will not replace them with an object file
extension, only append the object file extension to the file
name.

ERR5RS/R6RS library files have names ending in .sls (for source
code) or .slfasl (for compiled libraries).  These extensions are
treated specially by Larceny's load-on-import feature.

Loadable files that contain fast-loading machine code (or
references to machine code in other files) have extension .fasl
(R5RS) or .slfasl (ERR5RS/R6RS).  These files begin with special
syntax that allows them to be recognized and loaded like source
files; apart from special handling of .slfasl files by Larceny's
load-on-import feature, there is nothing magic about the .fasl
or .slfasl extensions.

Files that have been compiled but not assembled have extension
.lap, for \"Lisp Assembly Program\".

Files that contain hand-written MacScheme assembly language code
have extension .mal (for \"MacScheme Assembly Language\").

Files that contain non-loadable segments of machine code have
extension .lop (for \"Lisp Object Program\").  Heap images are
produced by linking .lop files.

Files that contain a heap image usually have extension .heap.
"))

(heaps
"  heaps              Dumping heap images."
((brief full native petit common)
"A bootstrap heap image is created using the setup procedure,
which is defined in setup.sch.  For details, see doc/HOWTO-BUILD.
")
((obsolete native)
"A bootstrap heap image is created with the dump-heap procedure:

  (build-heap-image <heapname> <object-file-list>)

This creates a bootstrap heap image containing all the given objects.
However, it is not usually called directly; the following procedure
is typically more convenient:

  (make-sparc-heap)
    Create a bootstrap heap image for generational collectors,
    using the default makefile. The heap is named \"sparc.heap\".

Beware that neither of these commands cleans up .lop files compiled
for a different collector type; you should first 'make lopclean' from
the Unix shell if you are building a heap of a kind different from the
one you built last.  And if you have changed compiler switches, you
should 'make libclean' from the Unix shell to remove both LAP and LOP
files.

For details, see the file Lib/makefile.sch.
")
((obsolete petit)
"A bootstrap heap image is created with the BUILD-HEAP procedure:

  (build-heap)

This creates \"libpetit.a\" (or a similar library) in the current
directory as well as the heap file, called \"petit.heap\".  The
library must then be linked into an application using the
BUILD-RUNTIME and BUILD-PETIT procedures:

  (build-runtime)
  (build-petit)

resulting in an executable file called \"petit\" which is able to run
the heap image in petit.heap.
" ))

; eof
