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 "\-\-builtins"
  89 Generate output for to the built-in module,
  90 which defines the root classes
  91 .B SodObject
  92 and
  93 .BR SodClass .
  94 For the purpose of naming output files,
  95 the built-in module is named
  96 .BR sod-base .
  97 .TP
  98 .BI "\-I, \-\-include=" dir
  99 Look for imported modules and extension files in directory
 100 .IR dir .
 101 This option may be repeated:
 102 directories are searched in the order they were named.
 103 .TP
 104 .BI "\-d, \-\-directory=" dir
 105 Write output files to directory
 106 .IR dir ,
 107 instead of the current directory.
 108 .TP
 109 .B "\-p, \-\-stdout"
 110 Write output to standard output,
 111 instead of to files.
 112 .TP
 113 .BI "\-t, \-\-type=" out-type
 114 Produce output of type
 115 .IR out-type .
 116 Output types can be defined by extensions.
 117 The built-in output types are described below.
 118 .PP
 119 Each
 120 .I source
 121 file named on the command-line
 122 is read and parsed as a Sod module:
 123 see
 124 .BR sod-module (5)
 125 for the built-in syntax.
 126 An output file is written for each module read,
 127 and the built-in module if the
 128 .B \-\-builtins
 129 option was given,
 130 and for each output type requested using the
 131 .B \-t
 132 option.
 133 At least one output type must be provided.
 134 .
 135 .SS Output types
 136 If a module is read from a file named
 137 .IB name . ext
 138 where
 139 .I ext
 140 doesn't contain a dot
 141 .RB (` . '),
 142 or if the file has a simple
 143 .I name
 144 which doesn't contain a dot
 145 (except possibly an initial one),
 146 then the module's name is
 147 .IR name .
 148 It is conventional for module files to be named
 149 .IB name .sod \fR.
 150 Output file names are determined by the module name,
 151 the output type,
 152 and the output directory
 153 .I dir
 154 specified by the
 155 .B \-d
 156 option.
 157 .PP
 158 The following output types are defined.
 159 .TP
 160 .B c
 161 Write C source,
 162 suitable for standalone compilation,
 163 defining the necessary direct and effective method functions
 164 and static tables
 165 for the classes defined in the module.
 166 The output file is named
 167 .IB dir / name .c \fR.
 168 .TP
 169 .B h
 170 Write a C header file,
 171 suitable for inclusion using
 172 .BR #include ,
 173 declaring the necessary data structures and functions
 174 for the classes defined in the module.
 175 The output file is named
 176 .IB dir / name .h \fR.
 177 .
 178 .\"--------------------------------------------------------------------------
 179 .SH SEE ALSO
 180 .BR sod (3),
 181 .BR sod-structs (3),
 182 .BR sod-module (5).
 183 .
 184 .\"--------------------------------------------------------------------------
 185 .SH AUTHOR
 186 Mark Wooding, <mdw@distorted.org.uk>
 187 .
 188 .\"----- That's all, folks --------------------------------------------------