debian/ml-nlffigen.1

   1 .TH ml-nlffigen 1 "April 25, 2003"
   2 .SH NAME
   3 ml-nlffigen \- SML No Longer Foreign Function Interface tool
   4 .SH SYNOPSIS
   5 .B ml-nlffigen
   6 .RI [ option ]
   7 --
   8 .I file
   9 .br
  10 .SH DESCRIPTION
  11 This manual page documents briefly the
  12 .B ml-nlffigen
  13 command.
  14 This manual page was written for the Debian distribution
  15 because the original program does not have a manual page.
  16 .PP
  17 .BR ml-nlffigen ,
  18 a glue-code generator for
  19 the new
  20 .SM NLFFI
  21 foreign function interface.  The generator reads
  22 C source code and emits ML code along with a description file for CM.
  23 .SH OPTIONS
  24 A summary of options is included below.
  25 .IP "\fB-dir \fIdir" 4
  26 .PD 0
  27 .IP "\fB-d \fId" 4
  28 .PD
  29 Output directory where all generated files are placed.
  30 .BR default :
  31 .IR NLFFI-Generated .
  32 .IP "\fB-allSU"
  33 .PD
  34 Instructs
  35 .B ml-nlffigen
  36 to include all structs and unions,
  37 even those that are defined in included files (as opposed
  38 to files explicitly listed as arguments).
  39 .BR default :
  40 .IR off .
  41 .IP "\fB-width \fIw"
  42 .PD 0
  43 .IP "\fB-w \fIw"
  44 .PD
  45 Sets output line width (just a guess) to
  46 .IR w .
  47 .BR default :
  48 .IR 75 .
  49 .IP "\fB-smloption \fIx"
  50 .PD
  51 Instructs
  52 .B ml-nlffigen
  53 to include
  54 .I x
  55 into the list
  56 of options to annotate .sml entries in the generated .cm
  57 file with.
  58 .BR default :
  59 .IR noguid .
  60 .IP "\fB-guid"
  61 .PD
  62 Removes the default
  63 .B -noguid
  64 from the list of sml options.
  65 (This re-enables strict handling of type- and object-identity
  66 but can have negative impact on CM cutoff recompilation
  67 performance if the programmer routinely removes the entire
  68 tree of ml-nlffigen-generated files during development.)
  69 .IP "\fB-lambdasplit \fIx"
  70 .PD 0
  71 .IP "\fB-ls \fIx"
  72 .PD
  73 Instructs
  74 .B ml-nlffigen
  75 to generate "lambdasplit"
  76 options for all ML files (see CM manual for what this means;
  77 it does not currently work anyway because cross-module
  78 inlining is broken).
  79 .BR default :
  80 nothing.
  81 .IP "\fB-target \fIt"
  82 .PD 0
  83 .IP "\fB-t \fIt"
  84 .PD
  85 Sets the target to
  86 .I t
  87 (which must be one of "sparc-unix","x86-unix", or "x86-win32").
  88 .BR default :
  89 current architecture.
  90 .IP "\fB-light"
  91 .PD 0
  92 .IP "\fB-l"
  93 .PD
  94 Suppress "heavy" versions of function wrappers and
  95 field accessors; also resets any earlier
  96 .B -heavy
  97 to default.
  98 .BR default ": not suppressed."
  99 .IP "\fB-heavy"
 100 .PD 0
 101 .IP "\fB-h"
 102 .PD
 103 suppress "light" versions of function wrappers and
 104 field accessors; also resets any earlier
 105 .B -light
 106 to default.
 107 .BR default ": not suppressed"
 108 .IP "\fB-namedargs"
 109 .PD 0
 110 .IP "\fB-na"
 111 .PD
 112 Instruct
 113 .B ml-nlffigen
 114 to generated function wrappers that
 115 use named arguments (ML records) instead of tuples if
 116 there is enough information for this in the C source;
 117 (this is not always very useful).
 118 .BR default ": off."
 119 .IP "\fB-nocollect"
 120 .PD
 121 Do not do the following:
 122 Collect enum constants from truly unnamed enumerations
 123 (those without tags that occur at toplevel or in an
 124 unnamed context, i.e., not in a typedef or another
 125 named struct or union) into a single artificial
 126 enumeration tagged by ' (single apostrohe).  The corresponding
 127 ML-side representative will be a structure named E_'.
 128 .IP "\fB-enum-constructors"
 129 .PD 0
 130 .IP "\fB-ec"
 131 .PD
 132 When possible (i.e., if all values of a given enumeration
 133 are different from each other), make the ML representation
 134 type of the enumeration a datatype.  The default (and
 135 fallback) is to make that type the same as
 136 .BR MLRep.Signed.int .
 137 .IP "\fB-libhandle \fIh"
 138 .PD 0
 139 .IP "\fB-lh \fIh"
 140 .PD
 141 Use the variable
 142 .I h
 143 to refer to the handle to the
 144 shared library object.  Given the constraints of CM,
 145 .I h
 146 must have the form of a long ML identifier, e.g.,
 147 .BR MyLibrary.libhandle . default : Library.libh .
 148 .IP "\fB-include \fIf"
 149 .PD 0
 150 .IP "\fB-add \fIf"
 151 .PD
 152 Mention file
 153 .I f
 154 in the generated .cm file.  This option
 155 is necessary at least once for providing the library handle.
 156 It can be used arbitrarily many times, resulting in more
 157 than one such programmer-supplied file to be mentioned.
 158 If
 159 .I f
 160 is relative, then it must be relative to the directory
 161 specified in the
 162 .BI -dir " dir"
 163 option.
 164 .IP "\fB-cmfile \fIf"
 165 .PD 0
 166 .IP "\fB-cm \fIf"
 167 .PD
 168 Specify name of the generated .cm file, relative to
 169 the directory specified by the
 170 .BI -dir " dir"
 171 option.
 172 .BR default :
 173 .IR nlffi-generated.cm .
 174 .IP "\fB-cppopt \fIo"
 175 .PD
 176 The string
 177 .I o
 178 gets added to the list of options to be
 179 passed to cpp (the C preprocessor).  The list of options
 180 gets substituted for
 181 .I %o
 182 in the cpp command line template.
 183 .IP "\fB-U \fIx"
 184 .PD
 185 The string
 186 .BI -U x
 187 gets added to the list of cpp options.
 188 .IP "\fB-D \fIx"
 189 .PD
 190 The string
 191 .BI -D x
 192 gets added to the list of cpp options.
 193 .IP "\fB-I \fIx"
 194 .PD
 195 The string
 196 .BI -I x
 197 gets added to the list of cpp options.
 198 .IP "\fB-version"
 199 .PD
 200 Just write the version number of
 201 .B ml-nlffigen
 202 to standard
 203 output and then quit.
 204 .IP "\fB-match \fIr"
 205 .PD 0
 206 .IP "\fB-m \fIr"
 207 .PD
 208 Normally
 209 .B ml-nlffigen
 210 will include ML definitions for a C
 211 declaration if the C declaration textually appears in
 212 one of the files specified at the command line.  Definitions
 213 in #include-d files will normally not appear (unless
 214 their absence would lead to inconsistencies).
 215 By specifying
 216 .BI -match r
 217 ,
 218 .B ml-nlffigen
 219 will also include
 220 definitions that occur in recursively #include-d files
 221 for which the
 222 .BR awk -style
 223 regular expression
 224 .I r
 225 matches their names.
 226 .IP "\fB-prefix \fIp"
 227 .PD 0
 228 .IP "\fB-p \fIp"
 229 .PD
 230 Generated ML structure names will all have prefix
 231 .I p
 232 (in addition to the usual "S_" or "U_" or "F_" ...)
 233 .IP "\fB-gensym \fIg"
 234 .IP "\fB-g \fIg"
 235 Names "gensym-ed" by
 236 .B ml-nlffigen
 237 (for anonymous struct/union/
 238 enums) will get an additional suffix
 239 .RI _ g.
 240 (This should
 241 be used if output from several indepdendent runs of
 242 .B ml-nlffigen
 243 are to coexist in the same ML program.)
 244 .IP "\fB--"
 245 Terminate processing of options, remaining arguments are
 246 taken to be C sources.
 247 .SH SEE ALSO
 248 .BR sml (1),
 249 .BR ml-build (1).
 250 .br
 251 This program described in more detail in
 252 .I No-Longer-Foreign: Teaching an ML compiler to speak C \"natively\"
 253 , Matthias Blume,
 254 which is available via <http://cm.bell-labs.com/who/blume/papers/nlffi.pdf>.
 255 .SH AUTHOR
 256 This manual page was written by Aaron Matthew Read <amread@nyx.net>,
 257 for the Debian GNU/Linux system (but may be used by others).