chiark - git - mdw - sod/blob - doc/cmdline.tex

   1 %%% -*-latex-*-
   2 %%%
   3 %%% Description of the internal class structure and protocol
   4 %%%
   5 %%% (c) 2009 Straylight/Edgeware
   6 %%%
   7
   8 %%%----- Licensing notice ---------------------------------------------------
   9 %%%
  10 %%% This file is part of the Simple Object Definition system.
  11 %%%
  12 %%% SOD is free software; you can redistribute it and/or modify
  13 %%% it under the terms of the GNU General Public License as published by
  14 %%% the Free Software Foundation; either version 2 of the License, or
  15 %%% (at your option) any later version.
  16 %%%
  17 %%% SOD is distributed in the hope that it will be useful,
  18 %%% but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 %%% GNU General Public License for more details.
  21 %%%
  22 %%% You should have received a copy of the GNU General Public License
  23 %%% along with SOD; if not, write to the Free Software Foundation,
  24 %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25
  26 \chapter{Invoking the Sod translator}
  27
  28 %%%--------------------------------------------------------------------------
  29 \section{Basic principles}
  30
  31 The Sod translator reads a number of source modules named on its command
  32 line (together with other modules directly or indirectly imported by these),
  33 and generates output files of the requested types.
  34
  35 %%%--------------------------------------------------------------------------
  36 \section{Command-line syntax}
  37
  38 The translator is named @|sod|, and is invoked as
  39 \begin{prog}
  40   sod @[@-Mp@] @[@--backtrace@] @[@--builtins@]
  41         @[@-I @<dir>@] @[@-d @<dir>@]
  42         @[@-e @<lisp>@] @[@-l @<file>@]
  43         @[@-t @<out-type>@]
  44         @<source> \ldots
  45 \end{prog}
  46
  47 Options follow the standard POSIX/GNU conventions:
  48 \begin{itemize}
  49
  50 \item Single-letter options without arguments can be grouped together, so
  51   @|@-Mp| means the same as @|@-M @-p|.
  52
  53 \item The argument for a single-letter option can be given either in the
  54   following argument word, or, if it is nonempty, in the same argument word
  55   immediately following the option letter.  The argument for a GNU-style long
  56   option can be given either in the following argument word, or in the same
  57   argument word following a @|=|.
  58
  59 \item If the environment variable @|POSIXLY_CORRECT| is set (to any value),
  60   then option processing will stop as soon as the first non-option is found.
  61   Otherwise, options may be mixed together with positional arguments, and all
  62   argument words beginning with @|@-| (other than @|@-| and @|@--|) which
  63   aren't option arguments are interpreted as options.
  64
  65 \item The words @|@-| and @|@--| are not options.  The former is treated like
  66   any other non-option word.  The latter is a special marker indicating that
  67   option processing should stop here: all subsequent argument words are
  68   treated as positional arguments regardless of any leading @|@-| characters.
  69
  70 \end{itemize}
  71
  72 Options are processed left-to-right.
  73
  74 \begin{description}
  75
  76 \item[@|@-h|, @|@--help|] Write commad-line help to standard output, and exit
  77   successfully.
  78 \item[@|@-V|, @|@--version|] Write the Sod translator's version number to
  79   standard output, and exit successfully.
  80 \item[@|@-u|, @|@--usage|] Write a (very) brief usage summary to standard
  81   output, and exit successfully.
  82
  83 \item[@|@--backtrace|] Report errors through the host Lisp's usual
  84   error-handling system, which will typically involve printing a stack
  85   backtrace.  By default, the translator prints a short error message and
  86   exits, in the manner common to Unix programs.  You may find this option
  87   useful for debugging.
  88
  89 \item[@|@-e|, @|@--eval=|@<lisp>] Evaluate the Lisp form(s) in @<lisp>, in
  90   order.  Nothing is printed: if you want output, write Lisp to print it.
  91   Forms are evaluated in the @|SOD-USER| package.
  92 \item[@|@-l|, @|@--load=|@<file>] Load and evaluate Lisp code from @<file>.
  93   The file is loaded into the @|SOD-USER| package (though obviously
  94   @|in-package| forms in the file will be respected).
  95
  96 \item[@|@--builtins|] Generate output for the built-in module, which defines
  97   the @|SodObject| and @|SodClass| classes.  The built-in module is named
  98   @|sod-base|.  This option is used to build Sod's runtime library, and is
  99   probably not useful otherwise.
 100
 101 \item[@|@-I|, @|@--include=|@<dir>] Look for imported modules in @<dir>.
 102   This option may be repeated: directories are searched in the order they
 103   were named.
 104
 105 \item[@|@-M|, @|@--track-dependencies|] Write a Makefie fragment capturing
 106   the dependencies of each emitted output file.
 107
 108   The details are delegated to output type handlers, but the default file
 109   name is the same as the main output, with @`@-dep' appended.
 110
 111   This option does nothing if @|@-p| is in force.
 112
 113 \item[@|@-d|, @|@--directory=|@<dir>] Write output files to the directory
 114   @<dir>, instead of the current directory.  The names of the output files
 115   are determined by the names of the input modules and the requested output
 116   types.
 117
 118 \item[@|@-p|, @|@--stdout|] Write the generated output to standard output,
 119   rather than to files.
 120
 121 \item[@|@-t|, @|@--type=|@<out-type>] Produce output of type @<out-type>.
 122   This option can be repeated to generate several output files from the same
 123   modules.  The built-in output types are described below.
 124
 125   More output types can be defined by extensions.  Each @<out-type> is
 126   converted into a Lisp keyword @<reason>, by uppercasing it and interning it
 127   in the @|keyword| package.  Each requested module is loaded, and then, for
 128   each requested @<reason>, an output filename is determined (by calling
 129   \descref{gf}{module-output-file}, unless @|@-p| is in force); the output
 130   file is generated (using \descref{fun}{output-module}), and, if @|@-M| is
 131   in force, a Makefile fragment is written (using
 132   \descref{gf}{write-dependency-file}).
 133
 134 \end{description}
 135
 136 %%%--------------------------------------------------------------------------
 137 \section{Built-in output types}
 138
 139 The following output types are implemented by the base translator.
 140 Additional types can be provided by extensions.
 141
 142 \begin{description}
 143
 144 \item[@|c|] Write C source, suitable for standalone compilation, defining the
 145   necessary direct and effective method functions and static tables for the
 146   classes defined in the module.  The output file for a module called @<name>
 147   will be @|@<dir>/@<name>.c|, and the dependency file will be
 148   @|@<dir>/@<name>.c-dep|.
 149
 150 \item[@|h|] Write a C header file, suitable for inclusion using @|\#include|,
 151   declaraing the necessary data structures and functions for the classes
 152   defined in the module.  The output file for a module called @<name> will be
 153   @|@<dir>/@<name>.h|, and the dependency file will be
 154   @|@<dir>/@<name>.h-dep|.
 155
 156 \end{description}
 157
 158 %%%----- That's all, folks --------------------------------------------------
 159
 160 %%% Local variables:
 161 %%% mode: LaTeX
 162 %%% TeX-master: "sod.tex"
 163 %%% TeX-PDF-mode: t
 164 %%% End: