ML-NLFFIGEN(1)

# ML-NLFFIGEN(1) Manual Page

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

-Ux

  The option (i.e., -Ux) is added to the list of cpp options.

-Dx

  The option (i.e., -Dx) is added to the list of cpp options.

-Ix

  The option (i.e., -Ix) 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.