--- name: "ml-nlffigen" section: "1" platform: "linux" package: "smlnj" version: "110.99.9-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/ml-nlffigen" --- # ml-nlffigen(1) foreign function glue-code generator for Standard ML ## 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)](/sml/1.md) *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.