+%%% -*-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:
~mdw / sod / commitdiff