chiark - git - mdw - sod/blob - src/sod.1.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" The Sod translator
   4 .\"
   5 .\" (c) 2015 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the Sensible Object Design, an object system for C.
  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 .\"--------------------------------------------------------------------------
  27 .so ../common/defs.man \" @@@PRE@@@
  28 .
  29 .\"--------------------------------------------------------------------------
  30 .TH sod 1 "11 October 2015" "Straylight/Edgeware" "Sensible Object Design"
  31 .
  32 .SH NAME
  33 sod \- Sensible Object Design translator
  34 .
  35 .\"--------------------------------------------------------------------------
  36 .SH SYNOPSIS
  37 .B sod
  38 .RB [ \-Mp ]
  39 .RB [ \-\-backtrace ]
  40 .RB [ \-\-builtins ]
  41 .RB [ \-I
  42 .IR dir ]
  43 .RB [ \-d
  44 .IR dir ]
  45 .if !t \{\
  46 .  br
  47         \c
  48 .\}
  49 .RB [ \-e
  50 .IR lisp ]
  51 .RB [ \-l
  52 .IR file ]
  53 .RB [ \-t
  54 .IR out-type ]
  55 .IR sources ...
  56 .
  57 .\"--------------------------------------------------------------------------
  58 .SH DESCRIPTION
  59 .
  60 The
  61 .B sod
  62 program reads input files describing Sod modules,
  63 containing class definitions and other items,
  64 and generates output files,
  65 such as C source and header files.
  66 .
  67 .SS Command line
  68 The following command-line options are recognized.
  69 .TP
  70 .B "\-h, \-\-help"
  71 Write command-line help text to standard output,
  72 and exit successfully.
  73 .TP
  74 .B "\-V, \-\-version"
  75 Write Sod's version number to standard output,
  76 and exit successfully.
  77 .TP
  78 .B "\-u, \-\-usage"
  79 Write a brief usage message to standard output,
  80 and exit successfully.
  81 .TP
  82 .B "\-\-backtrace"
  83 Generate a Lisp stack backtrace if an error is encountered.
  84 This is useful when debugging,
  85 if
  86 .B sod
  87 reports unusual errors, or
  88 is complaining unjustifiably about something.
  89 .TP
  90 .B "\-\-builtins"
  91 Generate output for to the built-in module,
  92 which defines the root classes
  93 .B SodObject
  94 and
  95 .BR SodClass .
  96 For the purpose of naming output files,
  97 the built-in module is named
  98 .BR sod-base .
  99 .TP
 100 .BI "\-I, \-\-include=" dir
 101 Look for imported modules and extension files in directory
 102 .IR dir .
 103 This option may be repeated:
 104 directories are searched in the order they were named.
 105 .TP
 106 .B "\-M, \-\-track-dependencies"
 107 For each output
 108 .I file
 109 produced,
 110 write a Makefile fragment listing the files it depends on
 111 to
 112 .IB file -dep \fR.
 113 Does nothing if
 114 .B \-p
 115 is in force.
 116 .TP
 117 .BI "\-d, \-\-directory=" dir
 118 Write output files to directory
 119 .IR dir ,
 120 instead of the current directory.
 121 .TP
 122 .B "\-e, \-\-eval=" lisp
 123 Evaluate the Lisp forms in
 124 .IR lisp ,
 125 in order.
 126 Nothing is printed:
 127 if you want output, write Lisp to print it.
 128 Forms are evaluated in the
 129 .B SOD-USER
 130 package.
 131 .TP
 132 .B "\-l, \-\-load=" file
 133 Load and evaluate Lisp code from
 134 .IR file .
 135 The file is loaded into the
 136 .B SOD-USER
 137 package.
 138 .TP
 139 .B "\-p, \-\-stdout"
 140 Write output to standard output,
 141 instead of to files.
 142 .TP
 143 .BI "\-t, \-\-type=" out-type
 144 Produce output of type
 145 .IR out-type .
 146 Output types can be defined by extensions.
 147 The built-in output types are described below.
 148 .PP
 149 Each
 150 .I source
 151 file named on the command-line
 152 is read and parsed as a Sod module:
 153 see
 154 .BR sod-module (5)
 155 for the built-in syntax.
 156 An output file is written for each module read,
 157 and the built-in module if the
 158 .B \-\-builtins
 159 option was given,
 160 and for each output type requested using the
 161 .B \-t
 162 option.
 163 At least one output type must be provided.
 164 .
 165 .SS Output types
 166 If a module is read from a file named
 167 .IB name . ext
 168 where
 169 .I ext
 170 doesn't contain a dot
 171 .RB (` . '),
 172 or if the file has a simple
 173 .I name
 174 which doesn't contain a dot
 175 (except possibly an initial one),
 176 then the module's name is
 177 .IR name .
 178 It is conventional for module files to be named
 179 .IB name .sod \fR.
 180 Output file names are determined by the module name,
 181 the output type,
 182 and the output directory
 183 .I dir
 184 specified by the
 185 .B \-d
 186 option.
 187 .PP
 188 The following output types are defined.
 189 .TP
 190 .B c
 191 Write C source,
 192 suitable for standalone compilation,
 193 defining the necessary direct and effective method functions
 194 and static tables
 195 for the classes defined in the module.
 196 The output file is named
 197 .IB dir / name .c \fR.
 198 .TP
 199 .B h
 200 Write a C header file,
 201 suitable for inclusion using
 202 .BR #include ,
 203 declaring the necessary data structures and functions
 204 for the classes defined in the module.
 205 The output file is named
 206 .IB dir / name .h \fR.
 207 .
 208 .\"--------------------------------------------------------------------------
 209 .SH SEE ALSO
 210 .BR sod (3),
 211 .BR sod-structs (3),
 212 .BR sod-module (5).
 213 .
 214 .\"--------------------------------------------------------------------------
 215 .SH AUTHOR
 216 Mark Wooding, <mdw@distorted.org.uk>
 217 .
 218 .\"----- That's all, folks --------------------------------------------------