1ic(3) Erlang Module Definition ic(3)
2
6 ic - The Erlang IDL Compiler
7
9 The ic module is an Erlang implementation of an OMG IDL compiler. De‐
10 pending on the choice of back-end the code will map to Erlang, C, or
11 Java. The compiler generates client stubs and server skeletons.
12 Two kinds of files are generated for each scope: Ordinary code files
14 and header files. The latter are used for defining record definitions,
15 while the ordinary files contain the object interface functions.
16
18 ic:gen(FileName) -> Result
19 ic:gen(FileName, [Option]) -> Result
20 Types:
22 Result = ok | error | {ok, [Warning]} | {error, [Warning],
24 [Error]}
25 Option = [ GeneralOption | CodeOption | WarningOption | Back‐
27 endOption]
28 GeneralOption =
30 {outdir, String()} | {cfgfile, String()} | {use_preproc,
31 bool()} |
32 {preproc_cmd, String()} | {preproc_flags, String()}
33 CodeOption =
35 {gen_hrl, bool()} | {serv_last_call, exception | exit} |
36 {{impl, String()}, String()} | {light_ifr, bool()}
37 this | {this, String()} | {{this, String()}, bool()} |
38 from | {from, String()} | {{from, String()}, bool()} |
39 handle_info | {handle_info, String()} | {{handle_info,
40 String()}, bool()} |
41 timeout | {timeout, String()} | {{timeout, String()}, bool()}
42 |
43 {scoped_op_calls, bool()} | {scl, bool()} |
44 {user_protocol, Prefix} |
45 {c_timeout, {SendTimeout, RecvTimeout}} |
46 {c_report, bool()} |
47 {precond, {atom(), atom()}} | {{precond, String()} {atom(),
48 atom()}} |
49 {postcond, {atom(), atom()}} | {{postcond, String()} {atom(),
50 atom()}}
51 WarningOption =
53 {'Wall', bool()} | {maxerrs, int() | infinity} |
54 {maxwarns, int() | infinity} | {nowarn, bool()} |
55 {warn_name_shadow, bool()} | {pedantic, bool()} |
56 {silent, bool()}
57 BackendOption = {be, Backend}
59 Backend = erl_corba | erl_template | erl_plain | erl_genserv
61 | c_client | c_server | java
62 DirNAme = string() | atom()
64 FileName = string() | atom()
65 The tuple {Option, true} can be replaced by Option for boolean
67 values.
68 The ic:gen/2 function can be called from the command line as
70 follows:
71 erlc "+Option" ... File.idl
73 Example:
75 erlc "+{be,c_client}" '+{outdir, "../out"}' File.idl
77
79 outdir:
80 Places all output files in the directory given by the option. The
81 directory will be created if it does not already exist.
82 Example option: {outdir, "output/generated"}.
84 cfgfile:
86 Uses FileName as configuration file. Options will override compiler
87 defaults but can be overridden by command line options. Default
88 value is ".ic_config".
89 Example option: {cfgfile, "special.cfg"}.
91 use_preproc:
93 Uses a preprocessor. Default value is true.
94 preproc_cmd:
96 Command string to invoke the preprocessor. The actual command will
97 be built as preproc_cmd++preproc_flags++FileName
98 Example option: {preproc_cmd, "erl"}).
100 Example option: {preproc_cmd, "gcc -x c++ -E"}.
102 preproc_flags:
104 Flags given to the preprocessor.
105 Example option: {preproc_flags, "-I../include"}.
107
109 light_ifr:
110 Currently, the default setting is false. To be able to use this op‐
111 tion Orber must be configured to use Light IFR (see Orber's User's
112 Guide). When this options is used, the size of the generated files
113 used to register the API in the IFR DB are minimized.
114 Example option: {light_ifr, true}.
116 gen_hrl:
118 Generate header files. Default is true.
119 serv_last_call:
121 Makes the last gen_server handle_call either raise a CORBA excep‐
122 tion or just exit plainly. Default is the exception.
123 {{impl, IntfName}, ModName}:
125 Assumes that the interface with name IntfName is implemented by the
126 module with name ModName and will generate calls to the ModName
127 module in the server behavior. Note that the IntfName must be a
128 fully scoped name as in "M1::I1".
129 this:
131 Adds the object reference as the first parameter to the object im‐
132 plementation functions. This makes the implementation aware of its
133 own object reference.
134 The option comes in three varieties: this which activates the pa‐
135 rameter for all interfaces in the source file, {this, IntfName}
136 which activates the parameter for a specified interface and {{this,
137 IntfName}, false} which deactivates the parameter for a specified
138 interface.
139 Example option: this) activates the parameter for all interfaces.
141 Example option: {this, "M1::I1"} activates the parameter for all
143 functions of M1::I1.
144 Example options: [this, {{this, "M1::I2"}, false}] activates the
146 parameter for all interfaces except M1::I2.
147 from:
149 Adds the invokers reference as the first parameter to the object
150 implementation two-way functions. If both from and this options are
151 used the invokers reference parameter will be passed as the second
152 parameter. This makes it possible for the implementation to respond
153 to a request and continue executing afterwards. Consult the
154 gen_server and Orber documentation how this option may be used.
155 The option comes in three varieties: from which activates the pa‐
156 rameter for all interfaces in the source file, {from, IntfName}
157 which activates the parameter for a specified interface and {{from,
158 IntfName}, false} which deactivates the parameter for a specified
159 interface.
160 Example option: from) activates the parameter for all interfaces.
162 Example options: [{from, "M1::I1"}] activates the parameter for all
164 functions of M1::I1.
165 Example options: [from, {{from, "M1::I2"}, false}] activates the
167 parameter for all interfaces except M1::I2.
168 handle_info:
170 Makes the object server call a function handle_info in the object
171 implementation module on all unexpected messages. Useful if the ob‐
172 ject implementation need to trap exits.
173 Example option: handle_info will activates module implementation
175 handle_info for all interfaces in the source file.
176 Example option: {{handle_info, "M1::I1"}, true} will activates mod‐
178 ule implementation handle_info for the specified interface.
179 Example options: [handle_info, {{handle_info, "M1::I1"}, false}]
181 will generate the handle_info call for all interfaces except
182 M1::I1.
183 timeout:
185 Used to allow a server response time limit to be set by the user.
186 This should be a string that represents the scope for the interface
187 which should have an extra variable for wait time initialization.
188 Example option: {timeout,"M::I"}) produces server stub which will
190 has an extra timeout parameter in the initialization function for
191 that interface.
192 Example option: timeout produces server stub which will has an ex‐
194 tra timeout parameter in the initialization function for all inter‐
195 faces in the source file.
196 Example options: [timeout, {{timeout,"M::I"}, false}] produces
198 server stub which will has an extra timeout parameter in the ini‐
199 tialization function for all interfaces except M1::I1.
200 scoped_op_calls:
202 Used to produce more refined request calls to server. When this op‐
203 tion is set to true, the operation name which was mentioned in the
204 call is scoped. This is essential to avoid name clashes when commu‐
205 nicating with c-servers. This option is available for the c-client,
206 c-server and the Erlang gen_server back ends. All of the parts gen‐
207 erated by ic have to agree in the use of this option. Default is
208 false.
209 Example options: [{be,c_genserv},{scoped_op_calls,true}]) produces
211 client stubs which sends "scoped" requests to a gen_server or a c-
212 server.
213 user_protocol:
215 Used to define a own protocol different from the default Erlang
216 distribution + gen_server protocol. Currently only valid for C
217 back-ends. For further details see IC C protocol.
218 Example options: [{be,c_client},{user_protocol, "my_special"}])
220 produces client stubs which use C protocol functions with the pre‐
221 fix "my_special".
222 c_timeout:
224 Makes sends and receives to have timeouts (C back-ends only). These
225 timeouts are specified in milliseconds.
226 Example options: [{be,c_client},{c_timeout, {10000, 20000}}]) pro‐
228 duces client stubs which use a 10 seconds send timeout, and a 20
229 seconds receive timeout.
230 c_report:
232 Generates code for writing encode/decode errors to stderr (C back-
233 ends only). timeouts are specified in milliseconds.
234 Example options: [{be,c_client}, c_report]).
236 scl:
238 Used for compatibility with previous compiler versions up to 3.3.
239 Due to better semantic checks on enumerants, the compiler discovers
240 name clashes between user defined types and enumerant values in the
241 same name space. By enabling this option the compiler turns off the
242 extended semantic check on enumerant values. Default is false.
243 Example option: {scl,true}
245 precond:
247 Adds a precondition call before the call to the operation implemen‐
248 tation on the server side.
249 The option comes in three varieties: {precond, {M, F}} which acti‐
251 vates the call for operations in all interfaces in the source file,
252 {{precond, IntfName}, {M, F}} which activates the call for all op‐
253 erations in a specific interface and {{precond, OpName}, {M, F}}
254 which activates the call for a specific operation.
255 The precondition function has the following signature m:f(Module,
257 Function, Args).
258 Example option: {precond, {mod, fun}} adds the call of m:f for all
260 operations in the idl file.
261 Example options: [{{precond, "M1::I"}, {mod, fun}}] adds the call
263 of m:f for all operations in the interface M1::I1.
264 Example options: [{{precond, "M1::I::Op"}, {mod, fun}}] adds the
266 call of m:f for the operation M1::I::Op.
267 postcond:
269 Adds a postcondition call after the call to the operation implemen‐
270 tation on the server side.
271 The option comes in three varieties: {postcond, {M, F}} which acti‐
273 vates the call for operations in all interfaces in the source file,
274 {{postcond, IntfName}, {M, F}} which activates the call for all op‐
275 erations in a specific interface and {{postcond, OpName}, {M, F}}
276 which activates the call for a specific operation.
277 The postcondition function has the following signature m:f(Module,
279 Function, Args, Result).
280 Example option: {postcond, {mod, fun}} adds the call of m:f for all
282 operations in the idl file.
283 Example options: [{{postcond, "M1::I"}, {mod, fun}}] adds the call
285 of m:f for all operations in the interface M1::I1.
286 Example options: [{{postcond, "M1::I::Op"}, {mod, fun}}] adds the
288 call of m:f for the operation M1::I::Op.
289
291 'Wall':
292 The option activates all reasonable warning messages in analogy
293 with the gcc -Wall option. Default value is true.
294 maxerrs:
296 The maximum numbers of errors that can be detected before the com‐
297 piler gives up. The option can either have an integer value or the
298 atom infinity. Default number is 10.
299 maxwarns:
301 The maximum numbers of warnings that can be detected before the
302 compiler gives up. The option can either have an integer value or
303 the atom infinity. Default value is infinity.
304 nowarn:
306 Suppresses all warnings. Default value is false.
307 warn_name_shadow:
309 Warning appears whenever names are shadowed due to inheritance; for
310 example, if a type name is redefined from a base interface. Note
311 that it is illegal to overload operation and attribute names as
312 this causes an error to be produced. Default value is true.
313 pedantic:
315 Activates all warning options. Default value is false.
316 silent:
318 Suppresses compiler printed output. Default value is false.
319
321 Which back-end IC will generate code for is determined by the supplied
322 {be,atom()} option. If left out, erl_corba is used. Currently, IC sup‐
323 port the following back-ends:
324 erl_corba:
326 This option switches to the IDL generation for CORBA.
327 erl_template:
329 Generate CORBA call-back module templates for each interface in the
330 target IDL file. Note, will overwrite existing files.
331 erl_plain:
333 Will produce plain Erlang modules which contain functions that map
334 to the corresponding interface functions on the input file.
335 erl_genserv:
337 This is an IDL to Erlang generic server generation option.
338 c_client:
340 Will produce a C client to the generic Erlang server.
341 c_server:
343 Will produce a C server switch with functionality of a generic Er‐
344 lang server.
345 java:
347 Will produce Java client stubs with functionality of a generic Er‐
348 lang server.
349 c_genserv:
351 Deprecated. Use c_client instead.
352
354 The IDL compiler allows several preprocessors to be used, the Erlang
355 IDL preprocessor or other standard C preprocessors. Options can be used
356 to provide extra flags such as include directories to the preprocessor.
357 The build in the Erlang IDL preprocessor is used by default, but any
358 standard C preprocessor such as gcc is adequate.
359 The preprocessor command is formed by appending the prepoc_cmd to the
361 preproc_flags option and then appending the input IDL file name.
362
364 The compiler can be configured in two ways:
365 * Configuration file
367 * Command line options
369 The configuration file is optional and overrides the compiler defaults
371 and is in turn overridden by the command line options. The configura‐
372 tion file shall contain options in the form of Erlang terms. The con‐
373 figuration file is read using file:consult.
374 An example of a configuration file, note the "." after each line.
376 {outdir, gen_dir}.
378 {{impl, "M1::M2::object"}, "obj"}.
379
382 The compiler will produce output in several files depending on scope
383 declarations found in the IDL file. At most three file types will be
384 generated for each scope (including the top scope), depending on the
385 compiler back-end and the compiled interface. Generally, the output per
386 interface will be a header file (.hrl/ .h) and one or more Erlang/C
387 files (.erl/.c). Please look at the language mapping for each back-end
388 for details.
389 There will be at least one set of files for an IDL file, for the file
391 level scope. Modules and interfaces also have their own set of gener‐
392 ated files.
393Ericsson AB ic 5.1 ic(3)