Commit | Line | Data |
---|---|---|
4dd335d4 JM |
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). |