1ic(3)                      Erlang Module Definition                      ic(3)
2
3
4

NAME

6       ic - The Erlang IDL Compiler
7

DESCRIPTION

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
13       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

EXPORTS

18       ic:gen(FileName) -> Result
19       ic:gen(FileName, [Option]) -> Result
20
21              Types:
22
23                 Result  =  ok  | error | {ok, [Warning]} | {error, [Warning],
24                 [Error]}
25
26                 Option = [ GeneralOption | CodeOption | WarningOption | Back‐
27                 endOption]
28
29                 GeneralOption =
30                 {outdir,  String()}  |  {cfgfile,  String()}  | {use_preproc,
31                 bool()} |
32                 {preproc_cmd, String()} | {preproc_flags, String()}
33
34                 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
52                 WarningOption =
53                 {'Wall', bool()} | {maxerrs, int() | infinity} |
54                 {maxwarns, int() | infinity} | {nowarn, bool()} |
55                 {warn_name_shadow, bool()} | {pedantic, bool()} |
56                 {silent, bool()}
57
58                 BackendOption = {be, Backend}
59
60                 Backend  = erl_corba | erl_template | erl_plain | erl_genserv
61                 | c_client | c_server | java
62
63                 DirNAme = string() | atom()
64                 FileName = string() | atom()
65
66              The tuple {Option, true} can be replaced by Option  for  boolean
67              values.
68
69              The  ic:gen/2  function  can  be called from the command line as
70              follows:
71
72              erlc "+Option" ... File.idl
73
74              Example:
75
76              erlc "+{be,c_client}" '+{outdir, "../out"}' File.idl
77

GENERAL OPTIONS

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
83           Example option: {outdir, "output/generated"}.
84
85         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
90           Example option: {cfgfile, "special.cfg"}.
91
92         use_preproc:
93           Uses a preprocessor. Default value is true.
94
95         preproc_cmd:
96           Command  string to invoke the preprocessor. The actual command will
97           be built as preproc_cmd++preproc_flags++FileName
98
99           Example option: {preproc_cmd, "erl"}).
100
101           Example option: {preproc_cmd, "gcc -x c++ -E"}.
102
103         preproc_flags:
104           Flags given to the preprocessor.
105
106           Example option: {preproc_flags, "-I../include"}.
107

CODE OPTIONS

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
115           Example option: {light_ifr, true}.
116
117         gen_hrl:
118           Generate header files. Default is true.
119
120         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
124         {{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
130         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
140           Example option: this) activates the parameter for all interfaces.
141
142           Example  option:  {this,  "M1::I1"} activates the parameter for all
143           functions of M1::I1.
144
145           Example options: [this, {{this, "M1::I2"},  false}]  activates  the
146           parameter for all interfaces except M1::I2.
147
148         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
161           Example option: from) activates the parameter for all interfaces.
162
163           Example options: [{from, "M1::I1"}] activates the parameter for all
164           functions of M1::I1.
165
166           Example  options:  [from,  {{from, "M1::I2"}, false}] activates the
167           parameter for all interfaces except M1::I2.
168
169         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
174           Example option: handle_info will  activates  module  implementation
175           handle_info for all interfaces in the source file.
176
177           Example option: {{handle_info, "M1::I1"}, true} will activates mod‐
178           ule implementation handle_info for the specified interface.
179
180           Example options: [handle_info,  {{handle_info,  "M1::I1"},  false}]
181           will  generate  the  handle_info  call  for  all  interfaces except
182           M1::I1.
183
184         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
189           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
193           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
197           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
201         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
210           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
214         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
219           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
223         c_timeout:
224           Makes sends and receives to have timeouts (C back-ends only). These
225           timeouts are specified in milliseconds.
226
227           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
231         c_report:
232           Generates  code for writing encode/decode errors to stderr (C back-
233           ends only). timeouts are specified in milliseconds.
234
235           Example options: [{be,c_client}, c_report]).
236
237         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
244           Example option: {scl,true}
245
246         precond:
247           Adds a precondition call before the call to the operation implemen‐
248           tation on the server side.
249
250           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
256           The  precondition  function has the following signature m:f(Module,
257           Function, Args).
258
259           Example option: {precond, {mod, fun}} adds the call of m:f for  all
260           operations in the idl file.
261
262           Example  options:  [{{precond, "M1::I"}, {mod, fun}}] adds the call
263           of m:f for all operations in the interface M1::I1.
264
265           Example options: [{{precond, "M1::I::Op"}, {mod,  fun}}]  adds  the
266           call of m:f for the operation M1::I::Op.
267
268         postcond:
269           Adds a postcondition call after the call to the operation implemen‐
270           tation on the server side.
271
272           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
278           The postcondition function has the following signature  m:f(Module,
279           Function, Args, Result).
280
281           Example option: {postcond, {mod, fun}} adds the call of m:f for all
282           operations in the idl file.
283
284           Example options: [{{postcond, "M1::I"}, {mod, fun}}] adds the  call
285           of m:f for all operations in the interface M1::I1.
286
287           Example  options:  [{{postcond, "M1::I::Op"}, {mod, fun}}] adds the
288           call of m:f for the operation M1::I::Op.
289

WARNING OPTIONS

291         'Wall':
292           The option activates all reasonable  warning  messages  in  analogy
293           with the gcc -Wall option. Default value is true.
294
295         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
300         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
305         nowarn:
306           Suppresses all warnings. Default value is false.
307
308         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
314         pedantic:
315           Activates all warning options. Default value is false.
316
317         silent:
318           Suppresses compiler printed output. Default value is false.
319

BACK-END OPTIONS

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
325         erl_corba:
326           This option switches to the IDL generation for CORBA.
327
328         erl_template:
329           Generate CORBA call-back module templates for each interface in the
330           target IDL file. Note, will overwrite existing files.
331
332         erl_plain:
333           Will  produce plain Erlang modules which contain functions that map
334           to the corresponding interface functions on the input file.
335
336         erl_genserv:
337           This is an IDL to Erlang generic server generation option.
338
339         c_client:
340           Will produce a C client to the generic Erlang server.
341
342         c_server:
343           Will produce a C server switch with functionality of a generic  Er‐
344           lang server.
345
346         java:
347           Will  produce Java client stubs with functionality of a generic Er‐
348           lang server.
349
350         c_genserv:
351           Deprecated. Use c_client instead.
352

PREPROCESSOR

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
360       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

CONFIGURATION

364       The compiler can be configured in two ways:
365
366         * Configuration file
367
368         * Command line options
369
370       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
375       An example of a configuration file, note the "." after each line.
376
377       {outdir, gen_dir}.
378       {{impl, "M1::M2::object"}, "obj"}.
379
380

OUTPUT FILES

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
390       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.
393
394
395
396Ericsson AB                         ic 5.1                               ic(3)
Impressum