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