Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all 
NAME
ic - The Erlang IDL Compiler
DESCRIPTION
The ic module is an Erlang implementation of an OMG IDL compiler. Depending on the choice of back-end the
code will map to Erlang, C, or Java. The compiler generates client stubs and server skeletons.
Two kinds of files are generated for each scope: Ordinary code files and header files. The latter are
used for defining record definitions, while the ordinary files contain the object interface functions.
EXPORTS
ic:gen(FileName) -> Result
ic:gen(FileName, [Option]) -> Result
Types:
Result = ok | error | {ok, [Warning]} | {error, [Warning], [Error]}
Option = [ GeneralOption | CodeOption | WarningOption | BackendOption]
GeneralOption =
{outdir, String()} | {cfgfile, String()} | {use_preproc, bool()} |
{preproc_cmd, String()} | {preproc_flags, String()}
CodeOption =
{gen_hrl, bool()} | {serv_last_call, exception | exit} | {{impl, String()}, String()} |
{light_ifr, bool()}
this | {this, String()} | {{this, String()}, bool()} |
from | {from, String()} | {{from, String()}, bool()} |
handle_info | {handle_info, String()} | {{handle_info, String()}, bool()} |
timeout | {timeout, String()} | {{timeout, String()}, bool()} |
{scoped_op_calls, bool()} | {scl, bool()} |
{user_protocol, Prefix} |
{c_timeout, {SendTimeout, RecvTimeout}} |
{c_report, bool()} |
{precond, {atom(), atom()}} | {{precond, String()} {atom(), atom()}} |
{postcond, {atom(), atom()}} | {{postcond, String()} {atom(), atom()}}
WarningOption =
{'Wall', bool()} | {maxerrs, int() | infinity} |
{maxwarns, int() | infinity} | {nowarn, bool()} |
{warn_name_shadow, bool()} | {pedantic, bool()} |
{silent, bool()}
BackendOption = {be, Backend}
Backend = erl_corba | erl_template | erl_plain | erl_genserv | c_client | c_server | java
DirNAme = string() | atom()
FileName = string() | atom()
The tuple {Option, true} can be replaced by Option for boolean values.
The ic:gen/2 function can be called from the command line as follows:
erlc "+Option" ... File.idl
Example:
erlc "+{be,c_client}" '+{outdir, "../out"}' File.idl
GENERAL OPTIONS
outdir:
Places all output files in the directory given by the option. The directory will be created if it
does not already exist.
Example option: {outdir, "output/generated"}.
cfgfile:
Uses FileName as configuration file. Options will override compiler defaults but can be overridden by
command line options. Default value is ".ic_config".
Example option: {cfgfile, "special.cfg"}.
use_preproc:
Uses a preprocessor. Default value is true.
preproc_cmd:
Command string to invoke the preprocessor. The actual command will be built as
preproc_cmd++preproc_flags++FileName
Example option: {preproc_cmd, "erl"}).
Example option: {preproc_cmd, "gcc -x c++ -E"}.
preproc_flags:
Flags given to the preprocessor.
Example option: {preproc_flags, "-I../include"}.
CODE OPTIONS
light_ifr:
Currently, the default setting is false. To be able to use this option Orber must be configured to
use Light IFR (see Orber's User's Guide). When this options is used, the size of the generated files
used to register the API in the IFR DB are minimized.
Example option: {light_ifr, true}.
gen_hrl:
Generate header files. Default is true.
serv_last_call:
Makes the last gen_server handle_call either raise a CORBA exception or just exit plainly. Default is
the exception.
{{impl, IntfName}, ModName}:
Assumes that the interface with name IntfName is implemented by the module with name ModName and will
generate calls to the ModName module in the server behavior. Note that the IntfName must be a fully
scoped name as in "M1::I1".
this:
Adds the object reference as the first parameter to the object implementation functions. This makes
the implementation aware of its own object reference.
The option comes in three varieties: this which activates the parameter for all interfaces in the
source file, {this, IntfName} which activates the parameter for a specified interface and {{this,
IntfName}, false} which deactivates the parameter for a specified interface.
Example option: this) activates the parameter for all interfaces.
Example option: {this, "M1::I1"} activates the parameter for all functions of M1::I1.
Example options: [this, {{this, "M1::I2"}, false}] activates the parameter for all interfaces except
M1::I2.
from:
Adds the invokers reference as the first parameter to the object implementation two-way functions. If
both from and this options are used the invokers reference parameter will be passed as the second
parameter. This makes it possible for the implementation to respond to a request and continue
executing afterwards. Consult the gen_server and Orber documentation how this option may be used.
The option comes in three varieties: from which activates the parameter for all interfaces in the
source file, {from, IntfName} which activates the parameter for a specified interface and {{from,
IntfName}, false} which deactivates the parameter for a specified interface.
Example option: from) activates the parameter for all interfaces.
Example options: [{from, "M1::I1"}] activates the parameter for all functions of M1::I1.
Example options: [from, {{from, "M1::I2"}, false}] activates the parameter for all interfaces except
M1::I2.
handle_info:
Makes the object server call a function handle_info in the object implementation module on all
unexpected messages. Useful if the object implementation need to trap exits.
Example option: handle_info will activates module implementation handle_info for all interfaces in
the source file.
Example option: {{handle_info, "M1::I1"}, true} will activates module implementation handle_info for
the specified interface.
Example options: [handle_info, {{handle_info, "M1::I1"}, false}] will generate the handle_info call
for all interfaces except M1::I1.
timeout:
Used to allow a server response time limit to be set by the user. This should be a string that
represents the scope for the interface which should have an extra variable for wait time
initialization.
Example option: {timeout,"M::I"}) produces server stub which will has an extra timeout parameter in
the initialization function for that interface.
Example option: timeout produces server stub which will has an extra timeout parameter in the
initialization function for all interfaces in the source file.
Example options: [timeout, {{timeout,"M::I"}, false}] produces server stub which will has an extra
timeout parameter in the initialization function for all interfaces except M1::I1.
scoped_op_calls:
Used to produce more refined request calls to server. When this option is set to true, the operation
name which was mentioned in the call is scoped. This is essential to avoid name clashes when
communicating with c-servers. This option is available for the c-client, c-server and the Erlang
gen_server back ends. All of the parts generated by ic have to agree in the use of this option.
Default is false.
Example options: [{be,c_genserv},{scoped_op_calls,true}]) produces client stubs which sends "scoped"
requests to a gen_server or a c-server.
user_protocol:
Used to define a own protocol different from the default Erlang distribution + gen_server protocol.
Currently only valid for C back-ends. For further details see IC C protocol.
Example options: [{be,c_client},{user_protocol, "my_special"}]) produces client stubs which use C
protocol functions with the prefix "my_special".
c_timeout:
Makes sends and receives to have timeouts (C back-ends only). These timeouts are specified in
milliseconds.
Example options: [{be,c_client},{c_timeout, {10000, 20000}}]) produces client stubs which use a 10
seconds send timeout, and a 20 seconds receive timeout.
c_report:
Generates code for writing encode/decode errors to stderr (C back-ends only). timeouts are specified
in milliseconds.
Example options: [{be,c_client}, c_report]).
scl:
Used for compatibility with previous compiler versions up to 3.3. Due to better semantic checks on
enumerants, the compiler discovers name clashes between user defined types and enumerant values in
the same name space. By enabling this option the compiler turns off the extended semantic check on
enumerant values. Default is false.
Example option: {scl,true}
precond:
Adds a precondition call before the call to the operation implementation on the server side.
The option comes in three varieties: {precond, {M, F}} which activates the call for operations in all
interfaces in the source file, {{precond, IntfName}, {M, F}} which activates the call for all
operations in a specific interface and {{precond, OpName}, {M, F}} which activates the call for a
specific operation.
The precondition function has the following signature m:f(Module, Function, Args).
Example option: {precond, {mod, fun}} adds the call of m:f for all operations in the idl file.
Example options: [{{precond, "M1::I"}, {mod, fun}}] adds the call of m:f for all operations in the
interface M1::I1.
Example options: [{{precond, "M1::I::Op"}, {mod, fun}}] adds the call of m:f for the operation
M1::I::Op.
postcond:
Adds a postcondition call after the call to the operation implementation on the server side.
The option comes in three varieties: {postcond, {M, F}} which activates the call for operations in
all interfaces in the source file, {{postcond, IntfName}, {M, F}} which activates the call for all
operations in a specific interface and {{postcond, OpName}, {M, F}} which activates the call for a
specific operation.
The postcondition function has the following signature m:f(Module, Function, Args, Result).
Example option: {postcond, {mod, fun}} adds the call of m:f for all operations in the idl file.
Example options: [{{postcond, "M1::I"}, {mod, fun}}] adds the call of m:f for all operations in the
interface M1::I1.
Example options: [{{postcond, "M1::I::Op"}, {mod, fun}}] adds the call of m:f for the operation
M1::I::Op.
WARNING OPTIONS
'Wall':
The option activates all reasonable warning messages in analogy with the gcc -Wall option. Default
value is true.
maxerrs:
The maximum numbers of errors that can be detected before the compiler gives up. The option can
either have an integer value or the atom infinity. Default number is 10.
maxwarns:
The maximum numbers of warnings that can be detected before the compiler gives up. The option can
either have an integer value or the atom infinity. Default value is infinity.
nowarn:
Suppresses all warnings. Default value is false.
warn_name_shadow:
Warning appears whenever names are shadowed due to inheritance; for example, if a type name is
redefined from a base interface. Note that it is illegal to overload operation and attribute names as
this causes an error to be produced. Default value is true.
pedantic:
Activates all warning options. Default value is false.
silent:
Suppresses compiler printed output. Default value is false.
BACK-END OPTIONS
Which back-end IC will generate code for is determined by the supplied {be,atom()} option. If left out,
erl_corba is used. Currently, IC support the following back-ends:
erl_corba:
This option switches to the IDL generation for CORBA.
erl_template:
Generate CORBA call-back module templates for each interface in the target IDL file. Note, will
overwrite existing files.
erl_plain:
Will produce plain Erlang modules which contain functions that map to the corresponding interface
functions on the input file.
erl_genserv:
This is an IDL to Erlang generic server generation option.
c_client:
Will produce a C client to the generic Erlang server.
c_server:
Will produce a C server switch with functionality of a generic Erlang server.
java:
Will produce Java client stubs and server skeletons with functionality of a generic Erlang server.
c_genserv:
Deprecated. Use c_client instead.
PREPROCESSOR
The IDL compiler allows several preprocessors to be used, the Erlang IDL preprocessor or other standard C
preprocessors. Options can be used to provide extra flags such as include directories to the
preprocessor. The build in the Erlang IDL preprocessor is used by default, but any standard C
preprocessor such as gcc is adequate.
The preprocessor command is formed by appending the prepoc_cmd to the preproc_flags option and then
appending the input IDL file name.
CONFIGURATION
The compiler can be configured in two ways:
* Configuration file
* Command line options
The configuration file is optional and overrides the compiler defaults and is in turn overridden by the
command line options. The configuration file shall contain options in the form of Erlang terms. The
configuration file is read using file:consult.
An example of a configuration file, note the "." after each line.
{outdir, gen_dir}.
{{impl, "M1::M2::object"}, "obj"}.
OUTPUT FILES
The compiler will produce output in several files depending on scope declarations found in the IDL file.
At most three file types will be generated for each scope (including the top scope), depending on the
compiler back-end and the compiled interface. Generally, the output per interface will be a header file
(.hrl/ .h) and one or more Erlang/C files (.erl/.c). Please look at the language mapping for each back-
end for details.
There will be at least one set of files for an IDL file, for the file level scope. Modules and interfaces
also have their own set of generated files.