home | help 
ML-NLFFIGEN(1)							  ML-NLFFIGEN(1)

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 (de-
	 fault 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 con-
	 sists 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	program-
	 mer  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 ar-
	 guments  (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 ap-
	 pear (unless their absence would lead to inconsistencies). By	specify-
	 ing  -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 tem-
     plate 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 PUR-
     POSE.

SML/NJ				   2024-10-25			  ML-NLFFIGEN(1)
home | help