Commit | Line | Data |
---|---|---|
15ad30aa MW |
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: |