'\" t
.\"     Title: ml-nlffigen
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2023-07-31
.\"    Manual: \ \&
.\"    Source: SML/NJ
.\"  Language: English
.\"
.TH "ML\-NLFFIGEN" "1" "2023-07-31" "SML/NJ" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ml-nlffigen \- foreign function glue\-code generator for Standard ML
.SH "SYNOPSIS"
.sp
\fBml\-nlffigen\fP [\fIOPTIONS\fP] \fIfile\fP
.SH "DESCRIPTION"
.sp
\fBML\-Nlffigen\fP is a tool for generating glue code from \fBC\fP language
header files.  The generator reads \fBC\fP source code and emits \fBSML\fP
code along with a description file for the compilation manager (CM).
.SH "OPTIONS"
.sp
\fB\-d, \-dir\fP \fIDIR\fP
.RS 4
Specify the output directory where all generated files are
placed (default \f(CRNLFFI\-Generated\fP).
.RE
.sp
\fB\-allSU\fP
.RS 4
instructs \fBml\-nlffigen\fP to include all structs and unions,
even those that are defined in included files, as opposed
to files explicitly listed as arguments.
.RE
.sp
\fB\-width\fP \fIWID\fP
.RS 4
set output line width (just a guess) to \fIWID\fP (default \f(CR75\fP).
.RE
.sp
\fB\-smloption\fP \fIOPT\fP
.RS 4
instructs \fBml\-nlffigen\fP to add \fIOPT\fP to the list
of options to annotate \f(CR.sml\fP entries in the generated \f(CR.cm\fP
file with.  By default, the list consists just of "\f(CRnoguid\fP."
.RE
.sp
\fB\-guid\fP
.RS 4
Removes the default "noguid" from the list of sml options.
This option 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.
.RE
.sp
\fB\-t, \-target\fP \fITGT\fP
.RS 4
Sets the target to \fITGT\fP (which must be one of "sparc\-unix",
"x86\-unix", or "x86\-win32").  The default is the host architecture.
.RE
.sp
\fB\-l, \-light\fP
.RS 4
suppress "heavy" versions of function wrappers and
field accessors; also cancels any earlier \fB\-heavy\fP option.
.RE
.sp
\fB\-h, \-heavy\fP
.RS 4
suppress "light" versions of function wrappers and
field accessors; also cancels any earlier \fB\-light\fP option.
.RE
.sp
\fB\-na, \-namedargs\fP
.RS 4
instructs \fBml\-nlffigen\fP to generated function wrappers that
use named arguments (\fBSML\fP records) instead of tuples if
there is enough information for this in the \fBC\fP source.
.RE
.sp
\fB\-nocollect\fP
.RS 4
Do not collect enum constants from truly unnamed enumerations
(those without tags that occur at toplevel or in an unnamed
context; \fIi.e.\fP, not in a typedef or another named struct
or union) into a single artificial enumeration tagged by \f(CR\*(Aq\fP
(single apostrohe).  The corresponding SML\-side representative
will be a structure named \f(CRE_\*(Aq\fP.
.RE
.sp
\fB\-ec, \-enum\-constructors\fP
.RS 4
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.
.RE
.sp
\fB\-lh \-libhandle\fP \fIH\fP
.RS 4
Use the variable \fIH\fP to refer to the handle to the
shared library object.  Given the constraints of CM, the
argument \fIH\fP must have the form of a long SML identifier;
\fIe.g.\fP, \f(CRMyLibrary.libhandle\fP (default \f(CRLibrary.libh\fP).
.RE
.sp
\fB\-add, \-include\fP \fIfile\fP
.RS 4
Include \fIfile\fP in the generated \f(CR.cm\fP 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 \fIfile\fP is a relative path, then it must be relative to
the directory specified in the \fB\-dir\fP option.
.RE
.sp
\fB\-cm \-cmfile\fP \fIfile\fP
.RS 4
Specifies the name of the generated \f(CR.cm\fP file, relative to the directory
specified by the \fB\-dir\fP option (default \f(CRnlffi\-generated.cm\fP).
.RE
.sp
\fB\-cppopt\fP \fIopt\fP
.RS 4
The string \fIopt\fP gets added to the list of options to be
passed to the \fBC\fP preprocessor.  The list of options
gets substituted for \f(CR%o\fP in the cpp command line template.
.RE
.sp
\fB\-U\fP\fIx\fP
.RS 4
The option (\fIi.e.\fP, \fB\-U\fP\fIx\fP) is added to the list of cpp options.
.RE
.sp
\fB\-D\fP\fIx\fP
.RS 4
The option (\fIi.e.\fP, \fB\-D\fP\fIx\fP) is added to the list of cpp options.
.RE
.sp
\fB\-I\fP\fIx\fP
.RS 4
The option (\fIi.e.\fP, \fB\-I\fP\fIx\fP) is added to the list of cpp options.
.RE
.sp
\fB\-version\fP
.RS 4
Print the version number of \fBml\-nlffigen\fP to standard output and then quit.
.RE
.sp
\fB\-m, \-match\fP \fIRE\fP
.RS 4
Normally \fBml\-nlffigen\fP will include ML definitions for a \fBC\fP
declaration if the \fBC\fP declaration textually appears in
one of the files specified at the command line.  Definitions
in included files will normally not appear (unless
their absence would lead to inconsistencies).
By specifying \fB\-match\fP \fIRE\fP, \fBml\-nlffigen\fP will also include
definitions that occur in recursively included files
for which the AWK\-style regular expression \fIRE\fP matches
their names.
.RE
.sp
\fB\-p, \-prefix\fP \fIP\fP
.RS 4
Generated \fBSML\fP structure names will all have the prefix \fIP\fP
(in addition to the usual "\f(CRS_\fP" or "\f(CRU_\fP" or "\f(CRF_\fP").
.RE
.sp
\fB\-g, \-gensym\fP \fIG\fP
.RS 4
Names generated by \fBml\-nlffigen\fP (for anonymous struct/union/enums)
will get \f(CR_\fP\fIG\fP as an additional suffix.  This option should
be used if output from several indepdendent runs of
\fBml\-nlffigen\fP are to coexist in the same ML program.
.RE
.sp
\fB\-\-\fP
.RS 4
Terminate processing of options, remaining arguments are
taken to be \fBC\fP sources.
.RE
.SH "ENVIRONMENT"
.sp
\fBML\-Nlffigen\fP looks at the environment variable \f(CRFFIGEN_CPP\fP to obtain
the template string for the \fBC\fP\-Preprocessor command line.  If \f(CRFFIGEN_CPP\fP is not
set, the template defaults to "\f(CRgcc \-E \-U__GNUC__ %o %s > %t\fP."
The actual command line is obtained by substituting occurences of
\f(CR%s\fP with the name of the source, and \f(CR%t\fP with the name of a temporary
file holding the pre\-processed code.
.SH "AUTHOR"
.sp
\fBML\-Nlffigen\fP was written by Matthias Blume.
.SH "SEE\-ALSO"
.sp
sml(1)
.sp
\fINLFFI \(em A new SML/NJ Foreign\-Function Interface (User Manual)\fP (included in
the \fBSML/NJ\fP documentation).
.SH "BUGS"
.sp
\fBML\-Nlffigen\fP does not yet support 64\-bit platforms.
.SH "COPYING"
.sp
Copyright (\fBC\fP) 2020 The Fellowship of SML/NJ
.sp
This is free software; see the source for copying  conditions.   There  is  NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.