HCoop backport of SML/NJ for ml-nlffigen

[hcoop/zz_old/debian/smlnj.git] / debian / ml-nlffigen.1

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