NAME
ml-nlffigen - SML No Longer Foreign Function Interface tool
SYNOPSIS
ml-nlffigen [option] -- file
DESCRIPTION
This manual page documents briefly the ml-nlffigen command. This
manual page was written for the Debian distribution because the
original program does not have a manual page.
ml-nlffigen, a glue-code generator for the new NLFFI foreign function
interface. The generator reads C source code and emits ML code along
with a description file for CM.
OPTIONS
A summary of options is included below.
-dir dir
-d d
Output directory where all generated files are placed. default:
NLFFI-Generated.
-allSU
Instructs ml-nlffigen to include all structs and unions, even those
that are defined in included files (as opposed to files explicitly
listed as arguments). default: off.
-width w
-w w
Sets output line width (just a guess) to w. default: 75.
-smloption x
Instructs ml-nlffigen to include x into the list of options to
annotate .sml entries in the generated .cm file with. default:
noguid.
-guid
Removes the default -noguid from the list of sml options. (This
re-enables strict handling of type- and object-identity but can
have negative impact on CM cutoff recompilation performance if the
programmer routinely removes the entire tree of ml-nlffigen-
generated files during development.)
-lambdasplit x
-ls x
Instructs ml-nlffigen to generate "lambdasplit" options for all ML
files (see CM manual for what this means; it does not currently
work anyway because cross-module inlining is broken). default:
nothing.
-target t
-t t
Sets the target to t (which must be one of "sparc-unix","x86-unix",
or "x86-win32"). default: current architecture.
-light
-l Suppress "heavy" versions of function wrappers and field accessors;
also resets any earlier -heavy to default. default: not
suppressed.
-heavy
-h suppress "light" versions of function wrappers and field accessors;
also resets any earlier -light to default. default: not suppressed
-namedargs
-na Instruct ml-nlffigen to generated function wrappers that use named
arguments (ML records) instead of tuples if there is enough
information for this in the C source; (this is not always very
useful). default: off.
-nocollect
Do not do the following: Collect enum constants from truly unnamed
enumerations (those without tags that occur at toplevel or in an
unnamed context, i.e., not in a typedef or another named struct or
union) into a single artificial enumeration tagged by ’ (single
apostrohe). The corresponding ML-side representative will be a
structure named E_’.
-enum-constructors
-ec When possible (i.e., if all values of a given enumeration are
different from each other), make the ML representation type of the
enumeration a datatype. The default (and fallback) is to make that
type the same as MLRep.Signed.int.
-libhandle h
-lh h
Use the variable h to refer to the handle to the shared library
object. Given the constraints of CM, h must have the form of a
long ML identifier, e.g., MyLibrary.libhandle.default:Library.libh.
-include f
-add f
Mention file f in the generated .cm file. This option is necessary
at least once for providing the library handle. It can be used
arbitrarily many times, resulting in more than one such programmer-
supplied file to be mentioned. If f is relative, then it must be
relative to the directory specified in the -dir dir option.
-cmfile f
-cm f
Specify name of the generated .cm file, relative to the directory
specified by the -dir dir option. default: nlffi-generated.cm.
-cppopt o
The string o gets added to the list of options to be passed to cpp
(the C preprocessor). The list of options gets substituted for %o
in the cpp command line template.
-U x
The string -Ux gets added to the list of cpp options.
-D x
The string -Dx gets added to the list of cpp options.
-I x
The string -Ix gets added to the list of cpp options.
-version
Just write the version number of ml-nlffigen to standard output and
then quit.
-match r
-m r
Normally ml-nlffigen will include ML definitions for a C
declaration if the C declaration textually appears in one of the
files specified at the command line. Definitions in #include-d
files will normally not appear (unless their absence would lead to
inconsistencies). By specifying -matchr , ml-nlffigen will also
include definitions that occur in recursively #include-d files for
which the awk-style regular expression r matches their names.
-prefix p
-p p
Generated ML structure names will all have prefix p (in addition to
the usual "S_" or "U_" or "F_" ...)
-gensym g
-g g
Names "gensym-ed" by ml-nlffigen (for anonymous struct/union/
enums) will get an additional suffix _g. (This should be used if
output from several indepdendent runs of ml-nlffigen are to coexist
in the same ML program.)
-- Terminate processing of options, remaining arguments are taken to
be C sources.
SEE ALSO
sml(1), ml-build(1).
This program described in more detail in No-Longer-Foreign: Teaching an
ML compiler to speak C , Matthias Blume, which is available via
<http://cm.bell-labs.com/who/blume/papers/nlffi.pdf>.
AUTHOR
This manual page was written by Aaron Matthew Read <amread@nyx.net>,
for the Debian GNU/Linux system (but may be used by others).
April 25, 2003 ml-nlffigen(1)