<!--
  - Author:
  -   Leif Kornstaedt <kornstae@ps.uni-sb.de>
  -
  - Copyright:
  -   Leif Kornstaedt, 1998
  -
  - Last change:
  -   $Date$ by $Author$
  -   $Revision$
  -
  - This file is part of Mozart, an implementation of Oz 3:
  -   http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -   http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<Appendix id="appendix.switches">
  <Title/Compiler Switches/
  <P>
    This appendix describes the available boolean switches, giving their
    name, their default setting, and their effects on the compilation
    process if they are set.
  <Section class=unnumbered>
    <Title/Global Configuration/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/compilerpasses</Code>
	  (default: <<false>>)
	<Item>
	  Output tracing information about the different phases the execution
	  of each query proceeds through.
	<Entry><Code><Span class=ignore/\switch +/showinsert</Code>
	  (default: <<false>>)
	<Item>
	  Show the names of files as they get inserted by the <<\insert>>
	  macro directive, after their name has been resolved by means
	  of the environment variable <Var type=env/OZPATH/ (see <Ptr
	  to="section.directives.macro">).
	<Entry><Code><Span class=ignore/\switch +/echoqueries</Code>
	  (default: <<true>>)
	<Item>
	  Output each (compilation) query verbatim.
	<Entry><Code><Span class=ignore/\switch +/showdeclares</Code>
	  (default: <<true>>)
	<Item>
	  Summarize the variables declared by each query and thus added
	  to the environment (provided the compilation succeeds and the
	  compiled code is actually executed).
	<Entry><Code><Span class=ignore/\switch +/watchdog</Code>
	  (default: <<true>>)
	<Item>
	  Terminate the current compilation if one of the compiler's threads
	  blocks unexpectedly.  This is useful for debugging the compiler.
      </List>
  <Section class=unnumbered>
    <Title/Warnings/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/warnredecl</Code>
	  (default: <<false>>)
	<Item>
	  Output warnings about redeclarations of top-level variables,
	  either by <<declare>> or locally.
	<Entry><Code><Span class=ignore/\switch +/warnshadow</Code>
	  (default: <<false>>)
	<Item>
	  Output warnings about redeclarations of all variables,
	  either by <<declare>> or locally (subsumes
          <Code><Span class=ignore/\switch +/warnredecl</Code>).
	<Entry><Code><Span class=ignore/\switch +/warnunused</Code>
	  (default: <<true>>)
	<Item>
	  Output warnings about local variables never used or used only
	  once (that is, initialized but never used again).
	<Entry><Code><Span class=ignore/\switch +/warnunusedformals</Code>
	  (default: <<false>>)
	<Item>
	  Output the above warnings also for formal parameters.
	  If <Code><Span class=ignore/\switch +/warnunused</Code> is not set,
	  this switch is ignored.
	<Entry><Code><Span class=ignore/\switch +/warnforward</Code>
	  (default: <<false>>)
	<Item>
	  Warn about uses of features, attributes, or methods which are not
	  known to be declared in the enclosing class.
	<Entry><Code><Span class=ignore/\switch +/warnopt</Code>
	  (default: <<false>>)
	<Item>
	  Warn if a <<case>> conditional cannot be translated into optimized
	  code.  Also warn if a <<cond>> or disjunction's guard is translated
	  with an explicit thread creation.
      </List>
  <Section class=unnumbered>
    <Title/I&dot; Parsing and Expanding/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/unnest</Code>
	  (default: <<true>>)
	<Item>
	  Enable unnesting.  If unnesting is disabled, none of the following
	  passes are executed either.
	<Entry><Code><Span class=ignore/\switch +/expression</Code>
	  (default: <<false>>)
	<Item>
	  Compile expressions, not statements.  The result of an evaluated
	  expression can be obtained through an output argument of the
	  enqueued query (see <Ptr to="section.api.engines">) or the variable
	  ?_{`result`}.
	<Entry><Code><Span class=ignore/\switch +/allowdeprecated</Code>
	  (default: <<true>>)
	<Item>
	  Allow the use of deprecated syntax, &ie;, allow to use <<case>>
	  for boolean conditionals and to mix <<if>> with <<elsecase>> and
	  <<case>> with <<elseif>>.
	<Entry><Code><Span class=ignore/\switch +/gump</Code>
	  (default: <<false>>)
	<Item>
	  Allow Gump definitions.  If this switch is off, Gump keywords are
	  parsed as ordinary atoms.
      </List>
      The remaining Gump-related switches are described in <Ptr.Extern
      to="ozdoc:gump">.
  <Section class=unnumbered>
    <Title/II&dot; Static Analysis/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/staticanalysis</Code>
	  (default: <<true>>)
	<Item>
	  Perform static analysis.  Switching this off has severe impacts
	  on optimization and error reporting.
      </List>
  <Section class=unnumbered>
    <Title/III&dot; Core Output/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/core</Code>
	  (default: <<false>>)
	<Item>
	  Output the result of the core expansion of a query.
	<Entry><Code><Span class=ignore/\switch +/realcore</Code>
	  (default: <<false>>)
	<Item>
	  Output the core expansion as it really is (and not beautified
	  by, &eg;, the use of operator symbols).
	<Entry><Code><Span class=ignore/\switch +/debugvalue</Code>
	  (default: <<false>>)
	<Item>
	  Include annotations about the values propagated by static analysis.
	<Entry><Code><Span class=ignore/\switch +/debugtype</Code>
	  (default: <<false>>)
	<Item>
	  Include annotations about the types inferred by static analysis.
      </List>
  <Section class=unnumbered>
    <Title/IV&dot; Code Generation/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/codegen</Code>
	  (default: <<true>>)
	<Item>
	  Generate code.
	<Entry><Code><Span class=ignore/\switch +/outputcode</Code>
	  (default: <<false>>)
	<Item>
	  Output the generated code as human-readable assembly code.
	<Entry><Code><Span class=ignore/\switch +/recordhoist</Code>
	  (default: <<true>>)
	<Item>
	  Perform the record hoisting optimization.
      </List>
  <Section class=unnumbered>
    <Title/V&dot; Feeding to the Emulator/
    <P>
      <List>
	<Entry><Code><Span class=ignore/\switch +/feedtoemulator</Code>
	  (default: <<true>>)
	<Item>
	  Load the generated code into the emulator and execute it.
	<Entry><Code><Span class=ignore/\switch +/threadedqueries</Code>
	  (default: <<true>>)
	<Item>
	  Execute each piece of generated code in a separate thread without
	  waiting for it to terminate before proceeding to the next query.
	<Entry><Code><Span class=ignore/\switch +/profile</Code>
	  (default: <<false>>)
	<Item>
	  Include profiling information in the generated code.
      </List>
  <Section class=unnumbered>
    <Title/VI&dot; Debugging/
    <P>
      Most of these switches are used by the source level debugger,
      described in <Ptr.Extern to="ozdoc:ozcar">.
      <List>
	<Entry><Code><Span class=ignore/\switch +/runwithdebugger</Code>
	  (default: <<false>>)
	<Item>
	  Place a static breakpoint on the first statement of each
	  compiled query.
      </List>
      Note that the following switches severely impact code size and
      run-time efficiency of the generated code.
      <List>
	<Entry><Code><Span class=ignore/\switch +/controlflowinfo</Code>
	  (default: <<false>>)
	<Item>
	  Include program flow information in the generated code.
	<Entry><Code><Span class=ignore/\switch +/staticvarnames</Code>
	  (default: <<false>>)
	<Item>
	  Include environment information in the generated code.
	<Entry><Code><Span class=ignore/\switch +/dynamicvarnames</Code>
	  (default: <<false>>)
	<Item>
	  All created local variables are annotated with their print name
	  at run time, such that <<System.printName>> applied to the
	  variable's value returns this name.
      </List>
</Appendix>
