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

   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 .\" Highlight using terminal escapes, rather than overstriking.
  27 .\"\X'tty: sgr 1'
  28 .
  29 .\" String definitions and font selection.
  30 .ie t \{\
  31 .  ds o \(bu
  32 .  if \n(.g .fam P
  33 .\}
  34 .el \{\
  35 .  ds o o
  36 .\}
  37 .
  38 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
  39 .de hP
  40 .IP
  41 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
  42 ..
  43 .
  44 .\"--------------------------------------------------------------------------
  45 .TH sod 1 "11 October 2015" "Straylight/Edgeware" "Sensible Object Design"
  46 .
  47 .SH NAME
  48 sod \- Sensible Object Design translator
  49 .
  50 .\"--------------------------------------------------------------------------
  51 .SH SYNOPSIS
  52 .B sod
  53 .RB [ \-p ]
  54 .RB [ \-\-builtins ]
  55 .RB [ \-d
  56 .IR dir ]
  57 .RB [ \-I
  58 .IR dir ]
  59 .RB [ \-t
  60 .IR out-type ]
  61 .IR sources ...
  62 .
  63 .\"--------------------------------------------------------------------------
  64 .SH DESCRIPTION
  65 .
  66 The
  67 .B sod
  68 program reads input files describing Sod modules,
  69 containing class definitions and other items,
  70 and generates output files,
  71 such as C source and header files.
  72 .
  73 .SS Command line
  74 The following command-line options are recognized.
  75 .TP
  76 .B "\-h, \-\-help"
  77 Write command-line help text to standard output,
  78 and exit successfully.
  79 .TP
  80 .B "\-V, \-\-version"
  81 Write Sod's version number to standard output,
  82 and exit successfully.
  83 .TP
  84 .B "\-u, \-\-usage"
  85 Write a brief usage message to standard output,
  86 and exit successfully.
  87 .TP
  88 .B "\-\-backtrace"
  89 Generate a Lisp stack backtrace if an error is encountered.
  90 This is useful when debugging,
  91 if
  92 .B sod
  93 reports unusual errors, or
  94 is complaining unjustifiably about something.
  95 .TP
  96 .B "\-\-builtins"
  97 Generate output for to the built-in module,
  98 which defines the root classes
  99 .B SodObject
 100 and
 101 .BR SodClass .
 102 For the purpose of naming output files,
 103 the built-in module is named
 104 .BR sod-base .
 105 .TP
 106 .BI "\-I, \-\-include=" dir
 107 Look for imported modules and extension files in directory
 108 .IR dir .
 109 This option may be repeated:
 110 directories are searched in the order they were named.
 111 .TP
 112 .BI "\-d, \-\-directory=" dir
 113 Write output files to directory
 114 .IR dir ,
 115 instead of the current directory.
 116 .TP
 117 .B "\-p, \-\-stdout"
 118 Write output to standard output,
 119 instead of to files.
 120 .TP
 121 .BI "\-t, \-\-type=" out-type
 122 Produce output of type
 123 .IR out-type .
 124 Output types can be defined by extensions.
 125 The built-in output types are described below.
 126 .PP
 127 Each
 128 .I source
 129 file named on the command-line
 130 is read and parsed as a Sod module:
 131 see
 132 .BR sod-module (5)
 133 for the built-in syntax.
 134 An output file is written for each module read,
 135 and the built-in module if the
 136 .B \-\-builtins
 137 option was given,
 138 and for each output type requested using the
 139 .B \-t
 140 option.
 141 At least one output type must be provided.
 142 .
 143 .SS Output types
 144 If a module is read from a file named
 145 .IB name . ext
 146 where
 147 .I ext
 148 doesn't contain a dot
 149 .RB (` . '),
 150 or if the file has a simple
 151 .I name
 152 which doesn't contain a dot
 153 (except possibly an initial one),
 154 then the module's name is
 155 .IR name .
 156 It is conventional for module files to be named
 157 .IB name .sod \fR.
 158 Output file names are determined by the module name,
 159 the output type,
 160 and the output directory
 161 .I dir
 162 specified by the
 163 .B \-d
 164 option.
 165 .PP
 166 The following output types are defined.
 167 .TP
 168 .B c
 169 Write C source,
 170 suitable for standalone compilation,
 171 defining the necessary direct and effective method functions
 172 and static tables
 173 for the classes defined in the module.
 174 The output file is named
 175 .IB dir / name .c \fR.
 176 .TP
 177 .B h
 178 Write a C header file,
 179 suitable for inclusion using
 180 .BR #include ,
 181 declaring the necessary data structures and functions
 182 for the classes defined in the module.
 183 The output file is named
 184 .IB dir / name .h \fR.
 185 .
 186 .\"--------------------------------------------------------------------------
 187 .SH SEE ALSO
 188 .BR sod (3),
 189 .BR sod-structs (3),
 190 .BR sod-module (5).
 191 .
 192 .\"--------------------------------------------------------------------------
 193 .SH AUTHOR
 194 Mark Wooding, <mdw@distorted.org.uk>
 195 .
 196 .\"----- That's all, folks --------------------------------------------------