tools/sfdc/SFDCompile.pod

   1
   2 ### Help message and manual page ##############################################
   3
   4 __END__
   5
   6 =head1 NAME
   7
   8 sfdc - Compile SFD files into someting useful
   9
  10 =head1 SYNOPSIS
  11
  12 sfdc [options] file1.sfd [file2.sfd ...]
  13
  14   Options:
  15     --addvectors=TYPE       Add default functions
  16     --gateprefix=PREFIX     Prefix for gatestub functions
  17     --help -h               Show full help message and exit
  18     --libarg=LOCATION       Where to pass the libbase
  19     --libprefix=PREFIX      Prefix for library functions
  20     --man                   Show full manual page and exit
  21     --mode=MODE             What to do
  22     --output=FILE -o FILE   Where to store the output
  23     --quiet -q              Be quiet
  24     --target=TARGET         Specifies the machine target
  25     --version -v            Show version and exit
  26
  27 =head1 OPTIONS
  28
  29 =over 8
  30
  31
  32 =item B<--addvectors>
  33
  34 This flag adds the standard library/device/BOOPSI functions to the
  35 list of function entries to process. Possible values are B<none>,
  36 B<library>, B<device> and B<boopsi>. The default is B<none>. Useful
  37 when generating gate stub functions.
  38
  39
  40 =item B<--gateprefix>
  41
  42 Sets a function name prefix for the gate stub functions when
  43 generating gatestubs or gateproto files.
  44
  45
  46 =item B<--help>
  47
  48 Show the full help message and exit.
  49
  50
  51 =item B<--libarg>
  52
  53 Specifies where to place the library base argument when generating
  54 gatestubs or gateproto and libproto files. Possible values are
  55 B<none>, B<first> and B<last>. The default is B<none>.
  56
  57
  58 =item B<--libprefix>
  59
  60 Sets a function name prefix for the local library functions when
  61 generating gatestubs or libproto files.
  62
  63
  64 =item B<--man>
  65
  66 Show the complete manual page and exit.
  67
  68
  69 =item B<--mode>
  70
  71 Instructs F<sfdc> what to do. F<sfdc> can handle the
  72 following arguments:
  73
  74 =over 4
  75
  76 =item B<clib>
  77
  78 Generate C prototypes to be placed in F<Include/clib/>.
  79
  80
  81 =item B<dump>
  82
  83 Dumps all information gathered from the SFD file.
  84
  85
  86 =item B<fd>
  87
  88 Generate an old-style FD file.
  89
  90
  91 =item B<gateproto>
  92
  93 Generate a prototype header file for library gate stubs. Useful for
  94 library and device developers.
  95
  96
  97 =item B<gatestubs>
  98
  99 Generate library gate stubs. Useful for library and device developers.
 100
 101
 102 =item B<libproto>
 103
 104 Generate a prototype header file for library functions. This is almost
 105 like B<clib>, but for internal use by library and device developers.
 106
 107
 108 =item B<lvo>
 109
 110 Generate an assembler LVO include file.
 111
 112
 113 =item B<macros>
 114
 115 Generate a header file containing F<gcc> specific preprocessor macros,
 116 similar to F<fd2inline>'s B<--new> switch. For AROS targets, it
 117 generates a file suitable to be placed in the F<Include/defines/>
 118 directory.
 119
 120
 121 =item B<proto>
 122
 123 Generate header file to be placed in F<Include/proto/> that includes
 124 the C prototypes as well as compiler-specific inlines or pragma files.
 125
 126
 127 =item B<pragmas>
 128
 129 Generate a F<SAS/C>/F<LATTICE>/F<DICE> and F<Maxon C>/F<Storm
 130 C>/F<Aztec C> pragma file.
 131
 132
 133 =item B<stubs>
 134
 135 Generate C library stubs suitable to be compiled and archived into
 136 F<libamiga.a>, F<libamigastubs.a> or
 137 F<libI<E<lt>moduleE<gt>>.a>. Using the B<%f> escape sequence in the
 138 B<--output> switch or a tool like F<splitasm.awk> strongly is
 139 recommended.
 140
 141 =item B<verify>
 142
 143 Just loads and parses the SFD file. This is the default.
 144
 145 =back
 146
 147
 148 =item B<--output>
 149
 150 Specifies where the result will be stored. The following escape
 151 sequencies are allowed in the file name. If the sequence B<%f> is
 152 present in the name, a new file will be created for each function
 153 processed.
 154
 155 =over 4
 156
 157 =item B<%b>
 158
 159 The library base variable name (C<DOSBase>, for example).
 160
 161 =item B<%f>
 162
 163 The current funcion name (C<Open>, for example).
 164
 165 =item B<%l>
 166
 167 The name of the library or device (F<dos.library>, for example).
 168
 169 =item B<%n>
 170
 171 The base name of the library or device (C<dos>, for example).
 172
 173 =back
 174
 175 If omitted, the result will be sent to the standard output instead of
 176 a file.
 177
 178 =item B<--quiet>
 179
 180 Be quiet.
 181
 182
 183 =item B<--target>
 184
 185 Specifies the target when generating macros etc. The target names
 186 follow the GNU autoconf standard. Some possible values are listed
 187 below. The default is B<m68k-unknown-amigaos>.
 188
 189 =over 4
 190
 191 =item B<i?86-pc-aros>, B<i?86-linux-aros>, B<ppc-aros> ...
 192
 193 AROS. Anything goes, as long as it ends in C<-aros>.
 194
 195
 196 =item B<i?86be-pc-amithlon>, B<i?86be-amithlon>
 197
 198 Amithlon/big endian IA32.
 199
 200
 201 =item B<m68k-unknown-amigaos>, B<m68k-amigaos>
 202
 203 Traditional AmigaOS/m68k.
 204
 205
 206 =item B<powerpc-unknown-morphos>, B<ppc-morphos>
 207
 208 MorphOS/PowerPC.
 209
 210
 211 =back
 212
 213
 214
 215 =item B<--version>
 216
 217 Prints the version and exits.
 218
 219
 220 =back
 221
 222 =head1 DESCRIPTION
 223
 224 F<sfdc> is an open source replacement for Amiga, Inc.'s F<sfd> tool,
 225 distributed with B<NDK 3.9>. It is also an replacement for
 226 F<fd2inline> from GeekGadgets and the MorphOS team, later improved to
 227 death by Martin Blom. It's now a complete mess and needs a
 228 replacement. SFD files and F<sfdc> might to be a good start.
 229
 230 For developers using F<gcc>, F<sfdc> aims to handle all your needs
 231 when it comes to libraries, devices, datatypes, BOOPSI classes or
 232 similar modules. F<sfdc> can also generate F<SAS/C>, F<DICE> and
 233 F<Storm C> files for end users of such modules.
 234
 235 The basis for all work performed by F<sfdc> is the B<SFD> file, which
 236 contains all required information about the module and the functions
 237 provided. From this information, F<sfdc> can:
 238
 239 =over 4
 240
 241 =item *
 242
 243 Generate an old-style B<FD> file for futher processing with other tools.
 244
 245
 246 =item *
 247
 248 Generate a B<C prototype file>, such as those normally found in the
 249 F<Include/clib/> directory.
 250
 251
 252 =item *
 253
 254 Generate F<gcc> B<inlines> (actually preprocessor macros) or
 255 B<pragmas> for direct library function calls (without going via
 256 library stubs).
 257
 258
 259 =item *
 260
 261 Generate the F<Include/proto/> file, which includes the
 262 F<Include/clib/> file and either the inlines or pragmas.
 263
 264
 265 =item *
 266
 267 Generate an B<assembler LVO> file, which contains the library offset
 268 of all functions in the library.
 269
 270
 271 =item *
 272
 273 Generate B<C stubs>, which can be compiled and archived into a stub
 274 library.
 275
 276
 277 =item *
 278
 279 Generate library B<gateway stubs>, which can be used as part of your
 280 module as glue between the module function table and your C functions.
 281
 282
 283 =back
 284
 285
 286 Additionally, F<sfdc> does all this for several Amiga-like operating
 287 systems: traditional B<AmigaOS>, native B<Amithlon>, B<AROS> and
 288 B<MorphOS>.
 289
 290 F<sfdc> uses F<autoconf> style identifies for the operating systems,
 291 making it easy to generate the correct output. Just make sure
 292 F<configure.in> contains the B<AC_CANONICAL_SYSTEM> command and use
 293 B<@host@> in your F<Makefile.in>. Using F<autoconf> and F<sfdc>, it's
 294 easy to make for example a library that can be compiled or
 295 cross-compiiled for any of the mentioned architectures.
 296
 297
 298 =head1 RETURN VALUE
 299
 300 Returns 0 on success and 10 on errors.
 301
 302
 303 =head1 NOTES
 304
 305 Had I seen F<cvinclude.pl> before I started writing this program, I
 306 might still have been using fd/clib files. Or maybe not.
 307
 308 =head1 AUTHOR
 309
 310 Martin Blom <martin@blom.org>
 311
 312 =head1 HISTORY
 313
 314 =over 8
 315
 316 =item B<1.0 (2003-07-27)>
 317
 318 Initial release.
 319
 320
 321 =item B<1.1 (2003-12-22)>
 322
 323 Added workaround for workbench.library (base name is "wb").
 324 Added AmigaOS 4 support.
 325 Added the --addvectors switch.
 326
 327
 328 =item B<1.2 (2004-06-16)>
 329
 330 Generates files for mathieeedoub*, though probably broken. Well they
 331 are the same as fd2inline generates at least.
 332
 333
 334 =item B<1.2a (2004-06-20)>
 335
 336 Replace AROS_LP with AROS_LD. Because it is guaranteed to define the
 337 function prototype. [verhaegs]
 338
 339 =item B<1.3 (2004-11-12)>
 340
 341 Correctly handle the argument C<type **arg>, where there is no
 342 whitespace between the argument type and the argument name.
 343
 344 Correctly handle the prototype C<void function (void)>, were there is
 345 a whitespace between the function name and the parenthesis and "void"
 346 is used to indicate no arguments.
 347
 348 Replace C<-> with C<_> in base/library name.
 349
 350 New special keyword for register specification (in addition to B<sysv>
 351 and B<base>): B<autoreg>, which automatically allocates m68k registers
 352 for the arguments.
 353
 354 B<sysv> now works correctly with varargs functions. B<sysv> combined
 355 with B<gatestubs> work for m68k and i386 only for now. For AROS
 356 targets in B<macros>, the correct AROS macro is used to fetch the
 357 function to be called.
 358
 359 New B<--mode>: B<functable>. For proper code generation in AROS, make
 360 sure gateprotos are included before you include the functable.
 361
 362 B<proto> files now include F<Include/defines/> files when used in AROS.
 363
 364 =back