1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
30
<date>2004-01-08</date>
34
<modulesummary>The Erlang IDL Compiler</modulesummary>
36
<p>The ic module is an Erlang implementation of an OMG IDL
37
compiler. Depending on the choice of back-end the code will map
38
to Erlang, C, or Java. The compiler generates client stubs and
40
<p>Two kinds of files are generated for each scope: Ordinary code
41
files and header files. The latter are used for defining record
42
definitions, while the ordinary files contain the object
43
interface functions.</p>
47
<name>ic:gen(FileName) -> Result</name>
48
<name>ic:gen(FileName, [Option]) -> Result</name>
49
<fsummary>Generate stub and server code according to the OMG CORBA standard.</fsummary>
51
<v>Result = ok | error | {ok, [Warning]} | {error, [Warning], [Error]}</v>
53
<v>Option = [ GeneralOption | CodeOption | WarningOption | BackendOption]</v>
55
<v>GeneralOption = </v>
56
<v>{outdir, String()} | {cfgfile, String()} | {use_preproc, bool()} |</v>
57
<v>{preproc_cmd, String()} | {preproc_flags, String()}</v>
60
<v>{gen_hrl, bool()} | {serv_last_call, exception | exit} | {{impl, String()}, String()} | {light_ifr, bool()}</v>
61
<v>this | {this, String()} | {{this, String()}, bool()} |</v>
62
<v>from | {from, String()} | {{from, String()}, bool()} |</v>
63
<v>handle_info | {handle_info, String()} | {{handle_info, String()}, bool()} |</v>
64
<v>timeout | {timeout, String()} | {{timeout, String()}, bool()} |</v>
65
<v>{scoped_op_calls, bool()} | {scl, bool()} |</v>
66
<v>{user_protocol, Prefix} |</v>
67
<v>{c_timeout, SendTimeout, RecvTimeout} |</v>
68
<v>{c_report, bool()} |</v>
69
<v>{precond, {atom(), atom()}} | {{precond, String()} {atom(), atom()}} |</v>
70
<v>{postcond, {atom(), atom()}} | {{postcond, String()} {atom(), atom()}}</v>
72
<v>WarningOption =</v>
73
<v>{'Wall', bool()} | {maxerrs, int() | infinity} |</v>
74
<v>{maxwarns, int() | infinity} | {nowarn, bool()} |</v>
75
<v>{warn_name_shadow, bool()} | {pedantic, bool()} |</v>
76
<v>{silent, bool()}</v>
78
<v>BackendOption = {be, Backend}</v>
80
<v>Backend = erl_corba | erl_template | erl_plain | erl_genserv | c_client | c_server | java</v>
82
<v>DirNAme = string() | atom()</v>
83
<v>FileName = string() | atom()</v>
86
<p>The tuple <c>{Option, true}</c> can be replaced by
87
<c>Option</c> for boolean values.</p>
88
<p>The <c>ic:gen/2</c> function can be called from the command
90
<p><c>erlc "+Option" ... File.idl</c></p>
92
<p><c>erlc "+{be,c_client}" '+{outdir, "../out"}' File.idl</c></p>
98
<title>General options</title>
100
<tag><em>outdir</em></tag>
102
<p>Places all output files in the directory given by the option.
103
The directory will be created if it does not already exist.</p>
104
<p>Example option: <c>{outdir, "output/generated"}</c>.</p>
106
<tag><em>cfgfile</em></tag>
108
<p>Uses <em>FileName</em> as configuration file. Options will
109
override compiler defaults but can be overridden by command line
110
options. Default value is <c>".ic_config"</c>.</p>
111
<p>Example option: <c>{cfgfile, "special.cfg"}</c>.</p>
113
<tag><em>use_preproc</em></tag>
115
<p>Uses a preprocessor. Default value is true.</p>
117
<tag><em>preproc_cmd</em></tag>
119
<p>Command string to invoke the preprocessor. The actual
120
command will be built as
121
<c>preproc_cmd++preproc_flags++FileName</c></p>
122
<p>Example option: <c>{preproc_cmd, "erl"})</c>.</p>
123
<p>Example option: <c>{preproc_cmd, "gcc -x c++ -E"}</c>.</p>
125
<tag><em>preproc_flags</em></tag>
127
<p>Flags given to the preprocessor.</p>
128
<p>Example option: <c>{preproc_flags, "-I../include"}</c>.</p>
134
<title>Code options</title>
136
<tag><em>light_ifr</em></tag>
138
<p>Currently, the default setting is <c>false</c>. To be able to
139
use this option Orber must be configured to use Light IFR (see
140
Orber's User's Guide). When this options is used, the size of the
141
generated files used to register the API in the IFR DB are minimized.</p>
142
<p>Example option: <c>{light_ifr, true}</c>.</p>
144
<tag><em>gen_hrl</em></tag>
146
<p>Generate header files. Default is true.</p>
148
<tag><em>serv_last_call</em></tag>
150
<p>Makes the last <c>gen_server handle_call</c> either raise a
151
CORBA exception or just exit plainly. Default is the exception.
154
<tag><em>{{impl, IntfName}, ModName}</em></tag>
156
<p>Assumes that the interface with name <em>IntfName</em> is
157
implemented by the module with name <em>ModName</em> and
158
will generate calls to the <em>ModName</em> module in the
159
server behavior. Note that the <em>IntfName</em> must be a
160
fully scoped name as in <c>"M1::I1"</c>.</p>
163
<tag><em>this</em></tag>
165
<p>Adds the object reference as the first parameter to the
166
object implementation functions. This makes the
167
implementation aware of its own object reference.
170
comes in three varieties: <c>this</c> which activates the
171
parameter for all interfaces in the source file, <c>{this, IntfName}</c> which activates the parameter for a specified
172
interface and <c>{{this, IntfName}, false}</c> which
173
deactivates the parameter for a specified
175
<p>Example option: <c>this)</c> activates the parameter for
177
<p>Example option: <c>{this, "M1::I1"}</c> activates the
178
parameter for all functions of <c>M1::I1</c>.</p>
179
<p>Example options: <c>[this, {{this, "M1::I2"}, false}]</c>
180
activates the parameter for all interfaces except
183
<tag><em>from</em></tag>
185
<p>Adds the invokers reference as the first parameter to the
186
object implementation two-way functions. If both
187
<c>from</c> and <c>this</c> options are used the invokers
188
reference parameter will be passed as the second
189
parameter. This makes it possible for the implementation to
190
respond to a request and continue executing
191
afterwards. Consult the <c>gen_server</c> and <c>Orber</c>
192
documentation how this option may be used. <br></br>
194
comes in three varieties: <c>from</c> which activates the
195
parameter for all interfaces in the source file, <c>{from, IntfName}</c> which activates the parameter for a specified
196
interface and <c>{{from, IntfName}, false}</c> which
197
deactivates the parameter for a specified interface.</p>
198
<p>Example option: <c>from)</c> activates the parameter for
200
<p>Example options: <c>[{from, "M1::I1"}]</c> activates the
201
parameter for all functions of <c>M1::I1</c>.</p>
202
<p>Example options: <c>[from, {{from, "M1::I2"}, false}]</c>
203
activates the parameter for all interfaces except
206
<tag><em>handle_info</em></tag>
208
<p>Makes the object server call a function <c>handle_info</c>
209
in the object implementation module on all unexpected
210
messages. Useful if the object implementation need to trap
212
<p>Example option: <c>handle_info</c> will activates module
213
implementation <c>handle_info</c> for all interfaces in the
215
<p>Example option: <c>{{handle_info, "M1::I1"}, true}</c>
216
will activates module implementation <c>handle_info</c> for
217
the specified interface.</p>
218
<p>Example options: <c>[handle_info, {{handle_info, "M1::I1"}, false}]</c> will generate the <c>handle_info</c>
219
call for all interfaces except <c>M1::I1</c>.</p>
221
<tag><em>timeout</em></tag>
223
<p>Used to allow a server response time limit to be set by the user.
224
This should be a string that represents the scope for the interface
225
which should have an extra variable for wait time initialization.</p>
226
<p>Example option: <c>{timeout,"M::I"})</c> produces server
227
stub which will has an extra timeout parameter in the initialization
228
function for that interface.</p>
229
<p>Example option: <c>timeout</c> produces server
230
stub which will has an extra timeout parameter in the initialization
231
function for all interfaces in the source file.</p>
232
<p>Example options: <c>[timeout, {{timeout,"M::I"}, false}]</c>
233
produces server stub which will has an extra timeout
234
parameter in the initialization function for all interfaces
235
except <c>M1::I1</c>.</p>
237
<tag><em>scoped_op_calls</em></tag>
239
<p>Used to produce more refined request calls to server. When
240
this option is set to true, the operation name which was
241
mentioned in the call is scoped. This is essential to avoid
242
name clashes when communicating with c-servers. This option
243
is available for the c-client, c-server and the Erlang
244
gen_server back ends. <c>All</c> of the parts generated by ic
245
have to agree in the use of this option. Default is
248
<c>[{be,c_genserv},{scoped_op_calls,true}])</c> produces
249
client stubs which sends "scoped" requests to a gen_server
252
<tag><em>user_protocol</em></tag>
254
<p>Used to define a own protocol different from the default
255
Erlang distribution + gen_server protocol. Currently only
256
valid for C back-ends. For further details see <seealso marker="ic_c_protocol">IC C protocol</seealso>.</p>
258
<c>[{be,c_client},{user_protocol, "my_special"}])</c> produces
259
client stubs which use C protocol functions with the prefix
262
<tag><em>c_timeout</em></tag>
264
<p>Makes sends and receives to have timeouts (C back-ends only). These
265
timeouts are specified in milliseconds. </p>
267
<c>[{be,c_client},{c_timeout, 10000, 20000}])</c> produces
268
client stubs which use a 10 seconds send timeout, and a
269
20 seconds receive timeout.</p>
271
<tag><em>c_report</em></tag>
273
<p>Generates code for writing encode/decode errors to <c>stderr</c> (C back-ends only).
274
timeouts are specified in milliseconds. </p>
276
<c>[{be,c_client}, c_report])</c>.</p>
278
<tag><em>scl</em></tag>
280
<p>Used for compatibility with previous compiler versions up
281
to <c>3.3</c>. Due to better semantic checks on enumerants,
282
the compiler discovers name clashes between user defined
283
types and enumerant values in the same name space. By
284
enabling this option the compiler turns off the extended
285
semantic check on enumerant values. Default is
287
<p>Example option: <c>{scl,true}</c></p>
289
<tag><em>precond</em></tag>
291
<p>Adds a precondition call before the call to the operation
292
implementation on the server side.</p>
293
<p>The option comes in three varieties: <c>{precond, {M, F}}</c> which activates the call for operations in all
294
interfaces in the source file, <c>{{precond, IntfName}, {M, F}}</c> which activates the call for all operations in a
295
specific interface and <c>{{precond, OpName}, {M, F}}</c>
296
which activates the call for a specific operation.</p>
297
<p>The precondition function has the following signature
298
<c>m:f(Module, Function, Args)</c>.</p>
299
<p>Example option: <c>{precond, {mod, fun}}</c> adds the call
300
of m:f for all operations in the idl file.</p>
301
<p>Example options: <c>[{{precond, "M1::I"}, {mod, fun}}]</c>
302
adds the call of <c>m:f</c> for all operations in the
303
interface <c>M1::I1</c>.</p>
304
<p>Example options: <c>[{{precond, "M1::I::Op"}, {mod, fun}}]</c> adds the call of <c>m:f</c> for the operation
305
<c>M1::I::Op</c>.</p>
307
<tag><em>postcond</em></tag>
309
<p>Adds a postcondition call after the call to the operation
310
implementation on the server side. </p>
311
<p>The option comes in three varieties: <c>{postcond, {M, F}}</c> which activates the call for operations in all
312
interfaces in the source file, <c>{{postcond, IntfName}, {M, F}}</c> which activates the call for all operations in a
313
specific interface and <c>{{postcond, OpName}, {M, F}}</c>
314
which activates the call for a specific operation.</p>
315
<p>The postcondition function has the following signature
316
<c>m:f(Module, Function, Args, Result)</c>.</p>
317
<p>Example option: <c>{postcond, {mod, fun}}</c> adds the call
318
of m:f for all operations in the idl file.</p>
319
<p>Example options: <c>[{{postcond, "M1::I"}, {mod, fun}}]</c>
320
adds the call of <c>m:f</c> for all operations in the
321
interface <c>M1::I1</c>.</p>
322
<p>Example options: <c>[{{postcond, "M1::I::Op"}, {mod, fun}}]</c> adds the call of <c>m:f</c> for the operation
323
<c>M1::I::Op</c>.</p>
329
<title>Warning options</title>
331
<tag><em>'Wall'</em></tag>
333
<p>The option activates all reasonable warning messages in
334
analogy with the gcc -Wall option. Default value is true.</p>
336
<tag><em>maxerrs</em></tag>
338
<p>The maximum numbers of errors that can be detected before
339
the compiler gives up. The option can either have an integer
340
value or the atom <c>infinity</c>. Default number is 10.</p>
342
<tag><em>maxwarns</em></tag>
344
<p>The maximum numbers of warnings that can be detected before
345
the compiler gives up. The option can either have an integer
346
value or the atom <c>infinity</c>. Default value is
349
<tag><em>nowarn</em></tag>
351
<p>Suppresses all warnings. Default value is false.</p>
353
<tag><em>warn_name_shadow</em></tag>
355
<p>Warning appears whenever names are shadowed due to
356
inheritance; for example, if a type name is redefined from a
357
base interface. Note that it is illegal to overload
358
operation and attribute names as this causes an error to be
359
produced. Default value is true. </p>
361
<tag><em>pedantic</em></tag>
363
<p>Activates all warning options. Default value is false.</p>
365
<tag><em>silent</em></tag>
367
<p>Suppresses compiler printed output. Default value is false.</p>
373
<title>Back-End options</title>
374
<p>Which back-end IC will generate code for is determined by the supplied
375
<c>{be,atom()}</c> option. If left out, <c>erl_corba</c> is used.
376
Currently, IC support the following back-ends:</p>
378
<tag><em>erl_corba</em></tag>
380
<p>This option switches to the IDL generation for CORBA.</p>
382
<tag><em>erl_template</em></tag>
384
<p>Generate CORBA call-back module templates for each interface in the target
385
IDL file. Note, will overwrite existing files.</p>
387
<tag><em>erl_plain</em></tag>
389
<p>Will produce plain Erlang modules which contain functions that
390
map to the corresponding interface functions on the input file.</p>
392
<tag><em>erl_genserv</em></tag>
394
<p>This is an IDL to Erlang generic server generation option.</p>
396
<tag><em>c_client</em></tag>
398
<p>Will produce a C client to the generic Erlang server.</p>
400
<tag><em>c_server</em></tag>
402
<p>Will produce a C server switch with functionality of a
403
generic Erlang server.</p>
405
<tag><em>java</em></tag>
407
<p>Will produce Java client stubs and server skeletons with
408
functionality of a generic Erlang server.</p>
410
<tag><em>c_genserv</em></tag>
412
<p>Deprecated. Use <c>c_client</c> instead.</p>
418
<title>Preprocessor</title>
419
<p>The IDL compiler allows several preprocessors to be used, the
420
<c>Erlang IDL preprocessor</c> or other standard <c>C</c> preprocessors.
421
Options can be used to provide extra flags such as include
422
directories to the preprocessor. The build in the Erlang IDL
423
preprocessor is used by default, but any standard C preprocessor
424
such as <c>gcc</c> is adequate.</p>
425
<p>The preprocessor command is formed by appending the prepoc_cmd
426
to the preproc_flags option and then appending the input IDL
431
<title>Configuration</title>
432
<p>The compiler can be configured in two ways:</p>
433
<list type="ordered">
435
<p>Configuration file</p>
438
<p>Command line options</p>
441
<p>The configuration file is optional and overrides the compiler
442
defaults and is in turn overridden by the command line options.
443
The configuration file shall contain options in the form of
444
Erlang terms. The configuration file is read using
445
<c>file:consult</c>.</p>
446
<p>An example of a configuration file, note the "." after each
450
{{impl, "M1::M2::object"}, "obj"}.
455
<title>Output files</title>
456
<p>The compiler will produce output in several files depending on
457
scope declarations found in the IDL file. At most
458
three file types will be generated for each scope (including the top scope),
459
depending on the compiler back-end and the compiled interface.
460
Generally, the output per interface will be a header file (<c>.hrl</c>/
461
<c>.h</c>) and one or more Erlang/C files (<c>.erl</c>/<c>.c</c>).
462
Please look at the language mapping for each back-end for details.</p>
463
<p>There will be at least one set of files for an IDL file, for the
464
file level scope. Modules and interfaces also have their own set
465
of generated files.</p>
added
removed
lib/ic/doc/src/ic.xml
