ml-nlffigen1

Usage

Overview

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.

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.