%% -*- mode: LaTeX -*-
%%
%% Copyright (c) 1997, 1998, 1999 The University of Utah and the Computer
%% Systems Laboratory at the University of Utah (CSL).
%%
%% This file is part of Flick, the Flexible IDL Compiler Kit.
%%
%% Flick 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.
%%
%% Flick 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
%% Flick; see the file COPYING.  If not, write to the Free Software Foundation,
%% 59 Temple Place #330, Boston, MA 02111, USA.
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Introduction}
\label{sec:Introduction}

Flick works in three phases, each implemented as a separate program: the front
end, the presentation generator, and the back end.  A Flick front end is simply
a parser that translates some IDL input into an intermediate representation
called an AOI (Abstract Object Interface, `\filename{.aoi}') file.  Next, a
``presentation generator'' determines how the constructs in the AOI file (the
parsed IDL file) are to be mapped onto type and function definitions in the C
or C++ programming language.  In other words, the presentation generator
determines how the generated stubs will appear --- e.g., the stubs' function
prototypes --- and how they will interact with user code --- e.g., the stubs'
parameter passing conventions.  This information about the stubs is written
into a PRES\_C (Presentation in C/C++, `\filename{.prc}') file.  The final
phase of compilation, the back end, reads a PRES\_C file and produces the C or
C++ code for the optimized stubs, written to use a particular transport system
(e.g., TCP) and message format.

Flick has multiple implementations of each of the three phases described above.
Flick has three separate front ends: one to parse CORBA IDL files, one to parse
ONC~RPC (Sun) IDL files, and one to parse MIG IDL files.  There are five
different presentation generators, implementing the CORBA (C and C++), ONC~RPC,
MIG, and Fluke\footnote{Fluke is the operating system being developed by the
Flux Project at the University of Utah.  Flick produces all of the stub code
for Fluke.  For more information, refer to \flukeurl{}.} mappings of IDL
constructs onto C or C++\@.  Finally, there are seven separate back ends for
producing stubs that use IIOP (C and C++), ONC/TCP, Mach messages,
Trapeze,\footnote{Trapeze is the fast Myrinet-based networking system from Duke
University.  For more information, see \trapezeurl{}.}  Khazana-style
messages,\footnote{Khazana is distributed global memory service in development
at the University of Utah.  For more information, see \khazanaurl{}.}  and
Fluke IPC\@.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Flick Programs}
\label{subsec:Flick Programs}

Every compiler pass is implemented as a separate program.  Once Flick has been
built, links to these programs will be located in the \filename{bin}
subdirectory of your Flick build tree:

\subsubsection{Front Ends}
\begin{commandlist}
  \item[flick-fe-newcorba] The CORBA front end.  Parses a CORBA IDL
  (`\filename{.idl}') file and outputs an AOI file (`\filename{.aoi}') to be
  read by the \program{flick-c-pfe-corba}, \program{flick-c-pfe-corbaxx}, or
  \program{flick-c-pfe-fluke} presentation
  generators.\footnote{Section~\ref{subsec:PG:Additional Comments} describes
  the dependencies between different front ends and presentation generators.}

  \item[flick-fe-sun] The ONC~RPC front end.  Parses an ONC~RPC IDL
  (`\filename{.x}') file and outputs an AOI file to be read by the
  \program{flick-c-pfe-sun} presentation generator.

  \item[flick-c-fe-mig] The MIG front end/presentation generator.  Parses a MIG
  IDL (`\filename{.defs}') file and outputs a PRES\_C file to be read by any
  back end.  Note that \program{flick-c-fe-mig} is unique because it implements
  both the front end and presentation generation passes.  These passes are
  combined because MIG IDL allows users to specify presentation attributes in
  addition to simply defining interfaces.
\end{commandlist}

\subsubsection{Presentation Generators}
\begin{commandlist}
  \item[flick-c-pfe-corba] The CORBA C language presentation generator.  Reads
  an AOI file generated by the CORBA front end and outputs a PRES\_C
  (`\filename{.prc}') file describing C stubs to be read by any C language back
  end (i.e., any back end except \program{flick-c-pbe-iiopxx}).

  \item[flick-c-pfe-corbaxx] The CORBA C++ presentation generator.  Reads an
  AOI file generated by the CORBA front end and outputs a PRES\_C
  (`\filename{.prc}') file describing C++ stubs to be read by any C++ language
  back end (as of this writing, only \program{flick-c-pbe-iiopxx}).

  \item[flick-c-pfe-sun] The ONC~RPC presentation generator.  Reads an AOI file
  generated by the ONC~RPC front end and outputs a PRES\_C file describing C
  stubs to be read by any C language back end.

  \item[flick-c-pfe-fluke] The Fluke presentation generator, used with the
  Fluke operating system.  Reads an AOI file generated by the CORBA front end
  and outputs a PRES\_C file describing C stubs to be read by any C language
  back end.
\end{commandlist}

\subsubsection{Back Ends}
\begin{commandlist}
  \item[flick-c-pbe-iiop] The IIOP back end for C code.  Reads a PRES\_C file
  and outputs either client stubs or server skeletons for use with Flick's IIOP
  runtime.  The generated stubs use the IIOP transport and CDR data encoding.

  \item[flick-c-pbe-iiopxx] The IIOP back end for C++ stubs.  Reads a PRES\_C
  file and outputs either client stubs or server skeletons for use with TAO\@.
  The generated stubs use the IIOP transport and CDR data encoding.

  \item[flick-c-pbe-sun] The ONC/TCP back end for C stubs.  Reads a PRES\_C
  file and outputs either client stubs or server skeletons for use with Flick's
  ONC/TCP runtime.  The generated stubs use the ONC/TCP transport and XDR data
  encoding.

  \item[flick-c-pbe-mach3mig] The Mach~3/MIG back end for C stubs.  Reads a
  PRES\_C file and outputs either client stubs or server skeletons for use with
  Mach.  The generated stubs use Mach IPC and MIG-style typed data encoding.

  \item[flick-c-pbe-trapeze] The Trapeze back end for C stubs.  Reads a PRES\_C
  file and outputs either client stubs or server skeletons for use with
  Trapeze.  The generated stubs use Trapeze messages and either CDR or XDR data
  encoding, depending on where the PRES\_C file originated.  (XDR is used for
  Sun-style stubs; CDR is used for CORBA and other stub styles.)

  \item[flick-c-pbe-khazana] The Khazana back end for C stubs.  Reads a PRES\_C
  file and outputs either client stubs or server skeletons for use within
  Khazana.  The generated stubs use TCP and a CDR-like data encoding.

  \item[flick-c-pbe-fluke] The Fluke back end for C stubs.  Reads a PRES\_C
  file and outputs either client stubs or server skeletons for use with Fluke.
  The generated stubs use Fluke IPC and a CDR-like data encoding.
\end{commandlist}

\subsubsection{Other Tools}
\begin{optionlist}
  \item[flick-aoid] The AOI dump utility.  Reads an AOI file and outputs a
  human-readable dump of the parse tree (an `\filename{.aod}' file).
  \emph{This program is used primarily to debug Flick.}

  \item[flick-c-presd] The PRES\_C dump utility.  Reads a PRES\_C file and
  outputs a human-readable dump of the interface presentation (a
  `\filename{.prd}' file).  \emph{This program is used primarily to debug
  Flick.}

% \item[flick-c-pdl] The Presentation Definition Language interpreter.
\end{optionlist}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Common Command Line Options}
\label{subsec:Common Command Line Options}

All Flick programs support these command line arguments and options:

\begin{optionlist}
  \item[\optionarg{input}]
  Read from the named \optionarg{input} file.  Every Flick program expects to
  receive the name of its input file on the command line.  If no input file is
  specified, input is taken from \filename{stdin}.

  \item[-o~\optionarg{filename} \oroption{} --output~\optionarg{filename}]
  Write output to the specified file.  If no output file is specified, the name
  of the output file will be constructed by concatenating the base name of the
  input file with a new, appropriate extension; e.g., if a presentation
  generator was told to read ``\filename{foo.aoi}'', the name of the output
  file would be ``\filename{foo.prc}''.  If no input file is specified on the
  command line, output will be written to \filename{stdout}.

  \item[-u \oroption{} --usage \oroption{}\\ -?\ \oroption{} --help]
  Print a synopsis of all available flags and quit.
  \optionpad{}

  \item[-v \oroption{} --version]
  Print the version of the program and quit.
\end{optionlist}

\textbf{Warning:} Flick's AOI and PRES\_C file formats are binary file formats,
not text file formats.  Windows~NT and Windows~95 distinguish binary streams
from text streams, and set \filename{stdin} and \filename{stdout} to be text
streams.  Thus, under Windows, it is not possible to pipe AOI and PRES\_C data
between Flick compiler passes.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% End of file.

