ML-NLFFIGEN(1)
==============
:doctype:	manpage
:man source:	SML/NJ
:man version:	{version}

NAME
----
ml-nlffigen - foreign function glue-code generator for Standard ML

SYNOPSIS
--------
*ml-nlffigen* ['OPTIONS'] 'file'

DESCRIPTION
-----------

*ML-Nlffigen* is a tool for generating glue code from **C** language
header files.  The generator reads **C** source code and emits *SML*
code along with a description file for the compilation manager (CM).

OPTIONS
-------

*-d, -dir* 'DIR'::
  Specify the 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.

*-width* 'WID'::
  set output line width (just a guess) to 'WID' (default `75`).

*-smloption* 'OPT'::
  instructs *ml-nlffigen* to add 'OPT' to the list
  of options to annotate `.sml` entries in the generated `.cm`
  file with.  By default, the list consists just of "`noguid`."

*-guid*::
  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.

*-t, -target* 'TGT'::
  Sets the target to 'TGT' (which must be one of "sparc-unix",
  "x86-unix", or "x86-win32").  The default is the host architecture.

*-l, -light*::
  suppress "heavy" versions of function wrappers and
  field accessors; also cancels any earlier *-heavy* option.

*-h, -heavy*::
  suppress "light" versions of function wrappers and
  field accessors; also cancels any earlier *-light* option.

*-na, -namedargs*::
  instructs *ml-nlffigen* to generated function wrappers that
  use named arguments (*SML* records) instead of tuples if
  there is enough information for this in the **C** source.

*-nocollect*::
  Do not 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 SML-side representative
  will be a structure named `E_'`.

*-ec, -enum-constructors*::
  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.

*-lh -libhandle* 'H'::
  Use the variable 'H' to refer to the handle to the
  shared library object.  Given the constraints of CM, the
  argument 'H' must have the form of a long SML identifier;
  _e.g._, `MyLibrary.libhandle` (default `Library.libh`).

*-add, -include* 'file'::
  Include 'file' 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 'file' is a relative path, then it must be relative to
  the directory specified in the *-dir* option.

*-cm -cmfile* 'file'::
  Specifies the name of the generated `.cm` file, relative to the directory
  specified by the *-dir* option (default `nlffi-generated.cm`).

*-cppopt* 'opt'::
  The string 'opt' gets added to the list of options to be
  passed to the *C* preprocessor.  The list of options
  gets substituted for `%o` in the cpp command line template.

*-U*'x'::
  The option (_i.e._, *-U*'x') is added to the list of cpp options.

*-D*'x'::
  The option (_i.e._, *-D*'x') is added to the list of cpp options.

*-I*'x'::
  The option (_i.e._, *-I*'x') is added to the list of cpp options.

*-version*::
  Print the version number of *ml-nlffigen* to standard output and then quit.

*-m, -match* 'RE'::
  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 included files will normally not appear (unless
  their absence would lead to inconsistencies).
  By specifying *-match* 'RE', *ml-nlffigen* will also include
  definitions that occur in recursively included files
  for which the AWK-style regular expression 'RE' matches
  their names.

*-p, -prefix* 'P'::
  Generated *SML* structure names will all have the prefix 'P'
  (in addition to the usual "`S_`" or "`U_`" or "`F_`").

*-g, -gensym* 'G'::
  Names generated by *ml-nlffigen* (for anonymous struct/union/enums)
  will get `_`'G' as an additional suffix.  This option 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.

ENVIRONMENT
-----------
*ML-Nlffigen* looks at the environment variable `FFIGEN_CPP` to obtain
the template string for the *C*-Preprocessor command line.  If `FFIGEN_CPP` is not
set, the template defaults to "`gcc -E -U__GNUC__ %o %s > %t`."
The actual command line is obtained by substituting occurences of
`%s` with the name of the source, and `%t` with the name of a temporary
file holding the pre-processed code.

AUTHOR
------
*ML-Nlffigen* was written by Matthias Blume.

SEE-ALSO
--------
sml(1)

__NLFFI -- A new SML/NJ Foreign-Function Interface (User Manual)__ (included in
the *SML/NJ* documentation).

BUGS
----
*ML-Nlffigen* does not yet support 64-bit platforms.

COPYING
-------
Copyright (*C*) 2020 The Fellowship of SML/NJ

This is free software; see the source for copying  conditions.   There  is  NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
