--- /dev/null
+.TH ml-nlffigen 1 "April 25, 2003"
+.SH NAME
+ml-nlffigen \- SML No Longer Foreign Function Interface tool
+.SH SYNOPSIS
+.B ml-nlffigen
+.RI [ option ]
+--
+.I file
+.br
+.SH DESCRIPTION
+This manual page documents briefly the
+.B ml-nlffigen
+command.
+This manual page was written for the Debian distribution
+because the original program does not have a manual page.
+.PP
+.BR ml-nlffigen ,
+a glue-code generator for
+the new
+.SM NLFFI
+foreign function interface. The generator reads
+C source code and emits ML code along with a description file for CM.
+.SH OPTIONS
+A summary of options is included below.
+.IP "\fB-dir \fIdir" 4
+.PD 0
+.IP "\fB-d \fId" 4
+.PD
+Output directory where all generated files are placed.
+.BR default :
+.IR NLFFI-Generated .
+.IP "\fB-allSU"
+.PD
+Instructs
+.B ml-nlffigen
+to include all structs and unions,
+even those that are defined in included files (as opposed
+to files explicitly listed as arguments).
+.BR default :
+.IR off .
+.IP "\fB-width \fIw"
+.PD 0
+.IP "\fB-w \fIw"
+.PD
+Sets output line width (just a guess) to
+.IR w .
+.BR default :
+.IR 75 .
+.IP "\fB-smloption \fIx"
+.PD
+Instructs
+.B ml-nlffigen
+to include
+.I x
+into the list
+of options to annotate .sml entries in the generated .cm
+file with.
+.BR default :
+.IR noguid .
+.IP "\fB-guid"
+.PD
+Removes the default
+.B -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.)
+.IP "\fB-lambdasplit \fIx"
+.PD 0
+.IP "\fB-ls \fIx"
+.PD
+Instructs
+.B 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).
+.BR default :
+nothing.
+.IP "\fB-target \fIt"
+.PD 0
+.IP "\fB-t \fIt"
+.PD
+Sets the target to
+.I t
+(which must be one of "sparc-unix","x86-unix", or "x86-win32").
+.BR default :
+current architecture.
+.IP "\fB-light"
+.PD 0
+.IP "\fB-l"
+.PD
+Suppress "heavy" versions of function wrappers and
+field accessors; also resets any earlier
+.B -heavy
+to default.
+.BR default ": not suppressed."
+.IP "\fB-heavy"
+.PD 0
+.IP "\fB-h"
+.PD
+suppress "light" versions of function wrappers and
+field accessors; also resets any earlier
+.B -light
+to default.
+.BR default ": not suppressed"
+.IP "\fB-namedargs"
+.PD 0
+.IP "\fB-na"
+.PD
+Instruct
+.B 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).
+.BR default ": off."
+.IP "\fB-nocollect"
+.PD
+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_'.
+.IP "\fB-enum-constructors"
+.PD 0
+.IP "\fB-ec"
+.PD
+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
+.BR MLRep.Signed.int .
+.IP "\fB-libhandle \fIh"
+.PD 0
+.IP "\fB-lh \fIh"
+.PD
+Use the variable
+.I h
+to refer to the handle to the
+shared library object. Given the constraints of CM,
+.I h
+must have the form of a long ML identifier, e.g.,
+.BR MyLibrary.libhandle . default : Library.libh .
+.IP "\fB-include \fIf"
+.PD 0
+.IP "\fB-add \fIf"
+.PD
+Mention file
+.I 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
+.I f
+is relative, then it must be relative to the directory
+specified in the
+.BI -dir " dir"
+option.
+.IP "\fB-cmfile \fIf"
+.PD 0
+.IP "\fB-cm \fIf"
+.PD
+Specify name of the generated .cm file, relative to
+the directory specified by the
+.BI -dir " dir"
+option.
+.BR default :
+.IR nlffi-generated.cm .
+.IP "\fB-cppopt \fIo"
+.PD
+The string
+.I o
+gets added to the list of options to be
+passed to cpp (the C preprocessor). The list of options
+gets substituted for
+.I %o
+in the cpp command line template.
+.IP "\fB-U \fIx"
+.PD
+The string
+.BI -U x
+gets added to the list of cpp options.
+.IP "\fB-D \fIx"
+.PD
+The string
+.BI -D x
+gets added to the list of cpp options.
+.IP "\fB-I \fIx"
+.PD
+The string
+.BI -I x
+gets added to the list of cpp options.
+.IP "\fB-version"
+.PD
+Just write the version number of
+.B ml-nlffigen
+to standard
+output and then quit.
+.IP "\fB-match \fIr"
+.PD 0
+.IP "\fB-m \fIr"
+.PD
+Normally
+.B 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
+.BI -match r
+,
+.B ml-nlffigen
+will also include
+definitions that occur in recursively #include-d files
+for which the
+.BR awk -style
+regular expression
+.I r
+matches their names.
+.IP "\fB-prefix \fIp"
+.PD 0
+.IP "\fB-p \fIp"
+.PD
+Generated ML structure names will all have prefix
+.I p
+(in addition to the usual "S_" or "U_" or "F_" ...)
+.IP "\fB-gensym \fIg"
+.IP "\fB-g \fIg"
+Names "gensym-ed" by
+.B ml-nlffigen
+(for anonymous struct/union/
+enums) will get an additional suffix
+.RI _ g.
+(This should
+be used if output from several indepdendent runs of
+.B ml-nlffigen
+are to coexist in the same ML program.)
+.IP "\fB--"
+Terminate processing of options, remaining arguments are
+taken to be C sources.
+.SH SEE ALSO
+.BR sml (1),
+.BR ml-build (1).
+.br
+This program described in more detail in
+.I No-Longer-Foreign: Teaching an ML compiler to speak C \"natively\"
+, Matthias Blume,
+which is available via <http://cm.bell-labs.com/who/blume/papers/nlffi.pdf>.
+.SH 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).
HCoop / hcoop / zz_old / debian / smlnj.git / blobdiff