NAME

       ml-nlffigen - SML No Longer Foreign Function Interface tool

SYNOPSIS

       ml-nlffigen [option] -- file

DESCRIPTION

       This  manual page documents briefly the ml-nlffigen command.  This manual page was written
       for the Debian distribution because the original program does not have a manual page.

       ml-nlffigen, a glue-code generator for the new  NLFFI  foreign  function  interface.   The
       generator reads C source code and emits ML code along with a description file for CM.

OPTIONS

       A summary of options is included below.

       -dir dir
       -d d
           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).  default: off.

       -width w
       -w w
           Sets output line width (just a guess) to w.  default: 75.

       -smloption x
           Instructs ml-nlffigen to include x into the list of options to annotate  .sml  entries
           in the generated .cm file with.  default: noguid.

       -guid
           Removes  the  default  -noguid  from the list of sml options.  (This 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.)

       -lambdasplit x
       -ls x
           Instructs ml-nlffigen to generate "lambdasplit" options  for  all  ML  files  (see  CM
           manual  for  what  this  means; it does not currently work anyway because cross-module
           inlining is broken).  default: nothing.

       -target t
       -t t
           Sets the target to t (which must be one of "sparc-unix","x86-unix",  or  "x86-win32").
           default: current architecture.

       -light
       -l  Suppress  "heavy"  versions  of function wrappers and field accessors; also resets any
           earlier -heavy to default.  default: not suppressed.

       -heavy
       -h  suppress "light" versions of function wrappers and field accessors;  also  resets  any
           earlier -light to default.  default: not suppressed

       -namedargs
       -na Instruct  ml-nlffigen  to  generated  function  wrappers  that use named arguments (ML
           records) instead of tuples if there is enough information for this in  the  C  source;
           (this is not always very useful).  default: off.

       -nocollect
           Do not do the following: 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 ML-side  representative  will  be  a  structure
           named E_'.

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

       -libhandle h
       -lh h
           Use  the  variable  h  to refer to the handle to the shared library object.  Given the
           constraints  of  CM,  h  must  have  the  form  of  a  long   ML   identifier,   e.g.,
           MyLibrary.libhandle.default:Library.libh.

       -include f
       -add f
           Mention  file f 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 f is relative, then
           it must be relative to the directory specified in the -dir dir option.

       -cmfile f
       -cm f
           Specify name of the generated .cm file, relative to the  directory  specified  by  the
           -dir dir option.  default: nlffi-generated.cm.

       -cppopt o
           The  string  o  gets  added  to  the  list  of  options  to  be  passed  to cpp (the C
           preprocessor).  The list of options gets substituted for %o in the  cpp  command  line
           template.

       -U x
           The string -Ux gets added to the list of cpp options.

       -D x
           The string -Dx gets added to the list of cpp options.

       -I x
           The string -Ix gets added to the list of cpp options.

       -version
           Just write the version number of ml-nlffigen to standard output and then quit.

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

       -prefix p
       -p p
           Generated ML structure names will all have prefix p (in addition to the usual "S_"  or
           "U_" or "F_" ...)

       -gensym g

       -g g
           Names  "gensym-ed"  by  ml-nlffigen  (for  anonymous  struct/union/ enums) will get an
           additional suffix _g.  (This 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.

SEE ALSO

       sml(1), ml-build(1).
       This  program  described  in  more detail in No-Longer-Foreign: Teaching an ML compiler to
       speak   C   ,    Matthias    Blume,    which    is    available    via    <http://cm.bell-
       labs.com/who/blume/papers/nlffi.pdf>.

AUTHOR

       This  manual  page  was  written  by  Aaron  Matthew Read <amread@nyx.net>, for the Debian
       GNU/Linux system (but may be used by others).

                                          April 25, 2003                           ml-nlffigen(1)