%%% -*-latex-*-
%%%
%%% Description of the internal class structure and protocol
%%%
%%% (c) 2009 Straylight/Edgeware
%%%

%%%----- Licensing notice ---------------------------------------------------
%%%
%%% This file is part of the Simple Object Definition system.
%%%
%%% SOD 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.
%%%
%%% SOD 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 SOD; if not, write to the Free Software Foundation,
%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

\chapter{Invoking the Sod translator}

%%%--------------------------------------------------------------------------
\section{Basic principles}

The Sod translator reads a number of source modules named on its command
line (together with other modules directly or indirectly imported by these),
and generates output files of the requested types.

%%%--------------------------------------------------------------------------
\section{Command-line syntax}

The translator is named @|sod|, and is invoked as
\begin{prog}
  sod @[@-Mp@] @[@--backtrace@] @[@--builtins@]
        @[@-I @<dir>@] @[@-d @<dir>@]
        @[@-e @<lisp>@] @[@-l @<file>@]
        @[@-t @<out-type>@]
        @<source> \ldots
\end{prog}

Options follow the standard POSIX/GNU conventions:
\begin{itemize}

\item Single-letter options without arguments can be grouped together, so
  @|@-Mp| means the same as @|@-M @-p|.

\item The argument for a single-letter option can be given either in the
  following argument word, or, if it is nonempty, in the same argument word
  immediately following the option letter.  The argument for a GNU-style long
  option can be given either in the following argument word, or in the same
  argument word following a @|=|.

\item If the environment variable @|POSIXLY_CORRECT| is set (to any value),
  then option processing will stop as soon as the first non-option is found.
  Otherwise, options may be mixed together with positional arguments, and all
  argument words beginning with @|@-| (other than @|@-| and @|@--|) which
  aren't option arguments are interpreted as options.

\item The words @|@-| and @|@--| are not options.  The former is treated like
  any other non-option word.  The latter is a special marker indicating that
  option processing should stop here: all subsequent argument words are
  treated as positional arguments regardless of any leading @|@-| characters.

\end{itemize}

Options are processed left-to-right.

\begin{description}

\item[@|@-h|, @|@--help|] Write commad-line help to standard output, and exit
  successfully.
\item[@|@-V|, @|@--version|] Write the Sod translator's version number to
  standard output, and exit successfully.
\item[@|@-u|, @|@--usage|] Write a (very) brief usage summary to standard
  output, and exit successfully.

\item[@|@--backtrace|] Report errors through the host Lisp's usual
  error-handling system, which will typically involve printing a stack
  backtrace.  By default, the translator prints a short error message and
  exits, in the manner common to Unix programs.  You may find this option
  useful for debugging.

\item[@|@-e|, @|@--eval=|@<lisp>] Evaluate the Lisp form(s) in @<lisp>, in
  order.  Nothing is printed: if you want output, write Lisp to print it.
  Forms are evaluated in the @|SOD-USER| package.
\item[@|@-l|, @|@--load=|@<file>] Load and evaluate Lisp code from @<file>.
  The file is loaded into the @|SOD-USER| package (though obviously
  @|in-package| forms in the file will be respected).

\item[@|@--builtins|] Generate output for the built-in module, which defines
  the @|SodObject| and @|SodClass| classes.  The built-in module is named
  @|sod-base|.  This option is used to build Sod's runtime library, and is
  probably not useful otherwise.

\item[@|@-I|, @|@--include=|@<dir>] Look for imported modules in @<dir>.
  This option may be repeated: directories are searched in the order they
  were named.

\item[@|@-M|, @|@--track-dependencies|] Write a Makefie fragment capturing
  the dependencies of each emitted output file.

  The details are delegated to output type handlers, but the default file
  name is the same as the main output, with @`@-dep' appended.

  This option does nothing if @|@-p| is in force.

\item[@|@-d|, @|@--directory=|@<dir>] Write output files to the directory
  @<dir>, instead of the current directory.  The names of the output files
  are determined by the names of the input modules and the requested output
  types.

\item[@|@-p|, @|@--stdout|] Write the generated output to standard output,
  rather than to files.

\item[@|@-t|, @|@--type=|@<out-type>] Produce output of type @<out-type>.
  This option can be repeated to generate several output files from the same
  modules.  The built-in output types are described below.

  More output types can be defined by extensions.  Each @<out-type> is
  converted into a Lisp keyword @<reason>, by uppercasing it and interning it
  in the @|keyword| package.  Each requested module is loaded, and then, for
  each requested @<reason>, an output filename is determined (by calling
  \descref{gf}{module-output-file}, unless @|@-p| is in force); the output
  file is generated (using \descref{fun}{output-module}), and, if @|@-M| is
  in force, a Makefile fragment is written (using
  \descref{gf}{write-dependency-file}).

\end{description}

%%%--------------------------------------------------------------------------
\section{Built-in output types}

The following output types are implemented by the base translator.
Additional types can be provided by extensions.

\begin{description}

\item[@|c|] Write C source, suitable for standalone compilation, defining the
  necessary direct and effective method functions and static tables for the
  classes defined in the module.  The output file for a module called @<name>
  will be @|@<dir>/@<name>.c|, and the dependency file will be
  @|@<dir>/@<name>.c-dep|.

\item[@|h|] Write a C header file, suitable for inclusion using @|\#include|,
  declaraing the necessary data structures and functions for the classes
  defined in the module.  The output file for a module called @<name> will be
  @|@<dir>/@<name>.h|, and the dependency file will be
  @|@<dir>/@<name>.h-dep|.

\end{description}

%%%----- That's all, folks --------------------------------------------------

%%% Local variables:
%%% mode: LaTeX
%%% TeX-master: "sod.tex"
%%% TeX-PDF-mode: t
%%% End:
