Admin Panel
### Help message and manual page ##############################################
__END__
=head1 NAME
sfdc - Compile SFD files into someting useful
=head1 SYNOPSIS
sfdc [options] file1.sfd [file2.sfd ...]
Options:
--addvectors=TYPE Add default functions
--gateprefix=PREFIX Prefix for gatestub functions
--help -h Show full help message and exit
--libarg=LOCATION Where to pass the libbase
--libprefix=PREFIX Prefix for library functions
--sdi SDI header compatibility mode
--man Show full manual page and exit
--mode=MODE What to do
--output=FILE -o FILE Where to store the output
--quiet -q Be quiet
--target=TARGET Specifies the machine target
--version -v Show version and exit
=head1 OPTIONS
=over 8
=item B<--addvectors>
This flag adds the standard library/device/BOOPSI functions to the
list of function entries to process. Possible values are B<none>,
B<library>, B<device> and B<boopsi>. The default is B<none>. Useful
when generating gate stub functions.
=item B<--gateprefix>
Sets a function name prefix for the gate stub functions when
generating gatestubs or gateproto files.
=item B<--help>
Show the full help message and exit.
=item B<--libarg>
Specifies where to place the library base argument when generating
gatestubs or gateproto and libproto files. Possible values are
B<none>, B<first> and B<last>. The default is B<none>.
=item B<--libprefix>
Sets a function name prefix for the local library functions when
generating gatestubs or libproto files.
=item B<--sdi>
Turns on the SDI header compatibility mode. This will make sure
that all header files (especially the gatestub and gateproto files
are generated to be used in a SDI compatible environment.
=item B<--man>
Show the complete manual page and exit.
=item B<--mode>
Instructs F<sfdc> what to do. F<sfdc> can handle the
following arguments:
=over 4
=item B<autoopen>
Generate C code for automatically opening the module. It is usually
placed in a link library together with C stub functions.
=item B<clib>
Generate C prototypes to be placed in F<Include/clib/>.
=item B<dump>
Dumps all information gathered from the SFD file.
=item B<fd>
Generate an old-style FD file.
=item B<functable>
Generate a list of function names suitable for inclusion in a library
function table. By defining the preprocessor symbol
B<__SFDC_FUNCTABLE_M68K__>, the list of functions will be modified so
it's suitable for AmigaOS 4's m68k function table.
=item B<gateproto>
Generate a prototype header file for library gate stubs. Useful for
library and device developers.
=item B<gatestubs>
Generate library gate stubs. Useful for library and device developers.
=item B<interface>
Generate a struct with function pointers, like that uses in AmigaOS 4.
=item B<libproto>
Generate a prototype header file for library functions. This is almost
like B<clib>, but for internal use by library and device developers.
=item B<lvo>
Generate an assembler LVO include file.
=item B<macros>
Generate a header file containing F<gcc> specific preprocessor macros,
similar to F<fd2inline>'s B<--new> switch. For AROS targets, it
generates a file suitable to be placed in the F<Include/defines/>
directory.
=item B<proto>
Generate header file to be placed in F<Include/proto/> that includes
the C prototypes as well as compiler-specific inlines or pragma files.
=item B<pragmas>
Generate a F<SAS/C>/F<LATTICE>/F<DICE> and F<Maxon C>/F<Storm
C>/F<Aztec C> pragma file.
=item B<stubs>
Generate C library stubs suitable to be compiled and archived into
F<libamiga.a>, F<libamigastubs.a> or
F<libI<E<lt>moduleE<gt>>.a>. Using the B<%f> escape sequence in the
B<--output> switch or a tool like F<splitasm.awk> strongly is
recommended.
=item B<verify>
Just loads and parses the SFD file. This is the default.
=back
=item B<--output>
Specifies where the result will be stored. The following escape
sequencies are allowed in the file name. If the sequence B<%f> is
present in the name, a new file will be created for each function
processed.
=over 4
=item B<%b>
The library base variable name (C<DOSBase>, for example).
=item B<%f>
The current funcion name (C<Open>, for example).
=item B<%l>
The name of the library or device (F<dos.library>, for example).
=item B<%n>
The base name of the library or device (C<dos>, for example).
=back
If omitted, the result will be sent to the standard output instead of
a file.
=item B<--quiet>
Be quiet.
=item B<--target>
Specifies the target when generating macros etc. The target names
follow the GNU autoconf standard. Some possible values are listed
below. The default is B<m68k-unknown-amigaos>.
=over 4
=item B<i?86-pc-aros>, B<i?86-linux-aros>, B<ppc-aros> ...
AROS. Anything goes, as long as it ends in C<-aros>.
=item B<i?86be-pc-amithlon>, B<i?86be-amithlon>
Amithlon/big endian IA32.
=item B<m68k-unknown-amigaos>, B<m68k-amigaos>
Traditional AmigaOS/m68k.
=item B<m68kvbcc-unknown-amigaos>, B<m68k-amigaos>
Traditional AmigaOS/m68k but with the VBCC compiler.
=item B<ppc-unknown-amigaos>, B<ppc-amigaos>
AmigaOS 4/PowerPC.
=item B<powerpc-unknown-morphos>, B<ppc-morphos>
MorphOS/PowerPC.
=back
=item B<--version>
Prints the version and exits.
=back
=head1 DESCRIPTION
F<sfdc> is an open source replacement for Amiga, Inc.'s F<sfd> tool,
distributed with B<NDK 3.9>. It is also an replacement for
F<fd2inline> from GeekGadgets and the MorphOS team, later improved to
death by Martin Blom. It's now a complete mess and needs a
replacement. SFD files and F<sfdc> might to be a good start.
For developers using F<gcc>, F<sfdc> aims to handle all your needs
when it comes to libraries, devices, datatypes, BOOPSI classes or
similar modules. F<sfdc> can also generate F<SAS/C>, F<DICE> and
F<Storm C> files for end users of such modules.
The basis for all work performed by F<sfdc> is the B<SFD> file, which
contains all required information about the module and the functions
provided. From this information, F<sfdc> can:
=over 4
=item *
Generate an old-style B<FD> file for futher processing with other tools.
=item *
Generate a B<C prototype file>, such as those normally found in the
F<Include/clib/> directory.
=item *
Generate F<gcc> B<inlines> (actually preprocessor macros) or
B<pragmas> for direct library function calls (without going via
library stubs).
=item *
Generate the F<Include/proto/> file, which includes the
F<Include/clib/> file and either the inlines or pragmas.
=item *
Generate an B<assembler LVO> file, which contains the library offset
of all functions in the library.
=item *
Generate B<C stubs>, which can be compiled and archived into a stub
library. It can also generate auto-open and auto-close code.
=item *
Generate library B<gateway stubs>, which can be used as part of your
module as glue between the module function table and your C functions.
=back
Additionally, F<sfdc> does all this for several Amiga-like operating
systems: traditional B<AmigaOS>, native B<Amithlon>, B<AROS> and
B<MorphOS>.
F<sfdc> uses F<autoconf> style identifies for the operating systems,
making it easy to generate the correct output. Just make sure
F<configure.in> contains the B<AC_CANONICAL_SYSTEM> command and use
B<@host@> in your F<Makefile.in>. Using F<autoconf> and F<sfdc>, it's
easy to make for example a library that can be compiled or
cross-compiiled for any of the mentioned architectures.
=head1 RETURN VALUE
Returns 0 on success and 10 on errors.
=head1 NOTES
Had I seen F<cvinclude.pl> before I started writing this program, I
might still have been using fd/clib files. Or maybe not.
=head1 AUTHOR
Martin Blom <martin@blom.org>
=head1 HISTORY
=over 4
=item *
B<1.0 (2003-07-27)>
Initial release.
=item *
B<1.1 (2003-12-22)>
Added workaround for workbench.library (base name is "wb").
Added AmigaOS 4 support.
Added the B<--addvectors> switch.
=item *
B<1.2 (2004-06-16)>
Generates files for mathieeedoub*, though probably broken. Well they
are the same as fd2inline generates at least.
=item *
B<1.2a (2004-06-20)>
Replace AROS_LP with AROS_LD. Because it is guaranteed to define the
function prototype. [verhaegs]
=item *
B<1.3 (2004-11-12)>
Correctly handle the argument C<type **arg>, where there is no
whitespace between the argument type and the argument name.
=item *
Correctly handle the prototype C<void function (void)>, were there is
a whitespace between the function name and the parenthesis and "void"
is used to indicate no arguments.
=item *
Replace C<-> with C<_> in base/library name.
=item *
New special keyword for register specification (in addition to B<sysv>
and B<base>): B<autoreg>, which automatically allocates m68k registers
for the arguments.
=item *
B<sysv> now works correctly with varargs functions. B<sysv> combined
with B<gatestubs> work for m68k and i386 only for now. For AROS
targets in B<macros>, the correct AROS macro is used to fetch the
function to be called.
=item *
New B<--mode>: B<functable>. For proper code generation in AROS, make
sure gateprotos are included before you include the functable.
=item *
B<proto> files now include F<Include/defines/> files when used in AROS.
=item *
B<1.4 (2005-09-23)>
Added AmigaOS 4-style interfaces (C++ only for non-OS4 targets, and
without implementation).
=item *
The library base in the B<proto> file is now defined for AmigaOS 4
too.
=item *
AmigaOS 4 B<clib> files now add B<__attribute__((linearvarargs))> to
varargs functions.
=item *
Added AmigaOS 4 support for B<stubs> files.
=item *
Added support for the 'iptr' gcc attribute.
=item *
Added B<__SFDC_FUNCTABLE_M68K__> check in the B<functable> mode.
=item *
Added m68k stub functions to AmigaOS 4's B<gatestubs> and
B<gateproto>.
=item *
Added the B<autoopen> mode.
=back