<!--
  - Author:
  -   Leif Kornstaedt <kornstae@ps.uni-sb.de>
  -
  - Copyright:
  -   Leif Kornstaedt, 2001
  -
  - 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.
  -
  -->

<Chapter id="chapter.applications">
  <Title/Standard Applications/
  <P>
    This chapter defines the standard applications of the compiler available
    with the Mozart system: the batch compiler, the compiler panel, and its
    relation to the OPI.
  <Section>
    <Title/The Batch Compiler/
    <P>
      The batch compiler <Code proglang=sh/ozc/ provides a command line
      interface to the compiler for batch compilation.  Batch compilation
      means that expressions (typically functor definitions) are compiled
      and evaluated, and the resulting value is pickled.
    <Para class=apropos><Title/Parameterization/
      The command line options of <Code proglang=sh/ozc/ allow to customize
      the state of the compiler to use for compilation.  Options allow
      for configuration of the set of defined macro names, to set all
      compiler switches, and to configure the compilation environment.
      Pickling can be parameterized to using compression or headers that
      make the resulting pickle executable.  Further options influence the
      compilation mode:  The default, evaluating an expression and pickling
      the result, can be replaced by evaluation of a statement, or
      intermediate results of compilation can be dumped.  Finally, a
      special mode allows to compute dependencies (in the form of
      included source files).
    <Para class=apropos><Title/Reference/
      The exact specification of command line options can be found in
      <Ptr.Extern to="ozdoc:tools" key="chapter.compiler">.
  <Section>
    <Title/The Compiler Panel/
    <P>
      The Compiler Panel is another application of the compiler.  The
      compiler defines the notion of a <Def/compiler interface/ to
      communicate with the outside world.  The compiler panel is one
      such interface.
    <Para class=apropos><Title/Interfaces/
      A compiler interface received notification about the state of the
      compiler.  This includes its compilation state, but also its state
      of execution (how it manages its query queue, what errors it reports,
      and whether a compilation succeeds).  <Ptr to="chapter.api"> describes
      how the API allows to define interfaces.
    <Para class=apropos><Title/The Panel/
      The compiler panel is a compiler interface that provides a
      graphical display of the compiler's state.  Its toplevel window
      has a menu that allows to enqueue further compilation tasks and
      to configure how the the compiler's state is displayed.  Furthermore,
      it features a set of notebook tabs for the different parts of its
      state.
    <Para class=apropos><Title/Tabs/
      The <Samp/Messages/ tab provides access to a text display of
      compilation phase tracking, and the warnings and errors reported.
      The <Samp/Environment/ tab displays all variables in the compilation
      environment.  Each identifier can be clicked to execute an action
      on its value; for instance, values can be shown or inspected.
      The set of actions is configurable.  The <Samp/Switches/ tab
      displays the settings of every compiler switch and option.  Finally,
      the <Samp/Query Queue/ tab displays the list of queries the
      compiler currently executes.
    <SubSection class=unnumbered>
      <Title/The Compiler Panel API/
      <P>
	Like all tools, the compiler panel has an API to enable
	applications to control it.  The module <<CompilerPanel>>,
	located at <File>x-oz://system/CompilerPanel</File>, exports
	a class <<CompilerPanel.'class'>> implementing the <<Listener>>
	interface, with the following methods.
	<List>
	  <Entry><<init>>
	    <Index class=module/CompilerPanel<And>'class'<And>init/
	  <Synopsis><<init(?+{CompilerObject} ?+{IconifiedB} <= false)>>
	  <Item>
	    initializes a new instance of a compiler panel, associated
	    with the compiler ?_{CompilerObject}.  If ?_{IconifiedB} is
	    <<true>>, it is started with its toplevel window retracted.
	  <Entry><<close>>
	    <Index class=module/CompilerPanel<And>'class'<And>close/
	  <Synopsis><<close()>>
	  <Item>
	    closes a compiler panel instance, also closing its window.
	  <Entry><<enqueue>>
	    <Index class=module/CompilerPanel<And>'class'<And>enqueue/
	  <Synopsis><<enqueue(?+{Message})>>
	  <Item>
	    enqueues a query to the compiler associated with the
	    compiler panel instance.  See <Ptr to="chapter.api">
	    for a specification of the values ?_{Message} can take.
	  <Entry><<addAction>>
	    <Index class=module/CompilerPanel<And>'class'<And>addAction/
	  <Synopsis><<addAction(?+{NameV} ?+{ActionP})>>
	  <Item>
	    adds an action to the menu of actions that can be performed
	    on values in the environment.  ?_{NameV} is the name of the
	    action as displayed in the menu while ?_{ActionP} is a
	    unary procedure which will be passed the value when invoked.
	</List>
    <Section>
      <Title/The Oz Programming Interface/
      <P>
	The OPI (see <Ptr.Extern to="ozdoc:opi">) runs a dedicated compiler
	instance which receives all queries generated by feeding code
	in the OPI by default.  It is available as <<OPI.compiler>>.
</Chapter>
