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).