.TH ic 3erl "ic 4.4.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ic \- The Erlang IDL Compiler
.SH DESCRIPTION
.LP
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\&.
.LP
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\&.
.SH EXPORTS
.LP
.B
ic:gen(FileName) -> Result
.br
.B
ic:gen(FileName, [Option]) -> Result
.br
.RS
.LP
Types:

.RS 3
Result = ok | error | {ok, [Warning]} | {error, [Warning], [Error]}
.br

.br
Option = [ GeneralOption | CodeOption | WarningOption | BackendOption]
.br

.br
GeneralOption = 
.br
{outdir, String()} | {cfgfile, String()} | {use_preproc, bool()} |
.br
{preproc_cmd, String()} | {preproc_flags, String()}
.br

.br
CodeOption =
.br
{gen_hrl, bool()} | {serv_last_call, exception | exit} | {{impl, String()}, String()} | {light_ifr, bool()}
.br
this | {this, String()} | {{this, String()}, bool()} |
.br
from | {from, String()} | {{from, String()}, bool()} |
.br
handle_info | {handle_info, String()} | {{handle_info, String()}, bool()} |
.br
timeout | {timeout, String()} | {{timeout, String()}, bool()} |
.br
{scoped_op_calls, bool()} | {scl, bool()} |
.br
{user_protocol, Prefix} |
.br
{c_timeout, {SendTimeout, RecvTimeout}} |
.br
{c_report, bool()} |
.br
{precond, {atom(), atom()}} | {{precond, String()} {atom(), atom()}} |
.br
{postcond, {atom(), atom()}} | {{postcond, String()} {atom(), atom()}}
.br

.br
WarningOption =
.br
{\&'Wall\&', bool()} | {maxerrs, int() | infinity} |
.br
{maxwarns, int() | infinity} | {nowarn, bool()} |
.br
{warn_name_shadow, bool()} | {pedantic, bool()} |
.br
{silent, bool()}
.br

.br
BackendOption = {be, Backend}
.br

.br
Backend = erl_corba | erl_template | erl_plain | erl_genserv | c_client | c_server | java
.br

.br
DirNAme = string() | atom()
.br
FileName = string() | atom()
.br
.RE
.RE
.RS
.LP
The tuple \fI{Option, true}\fR\& can be replaced by \fIOption\fR\& for boolean values\&.
.LP
The \fIic:gen/2\fR\& function can be called from the command line as follows:
.LP
\fIerlc "+Option" \&.\&.\&. File\&.idl\fR\&
.LP
Example:
.LP
\fIerlc "+{be,c_client}" \&'+{outdir, "\&.\&./out"}\&' File\&.idl\fR\&
.RE

.SH "GENERAL OPTIONS"

.RS 2
.TP 2
.B
\fIoutdir\fR\&:
Places all output files in the directory given by the option\&. The directory will be created if it does not already exist\&.
.RS 2
.LP
Example option: \fI{outdir, "output/generated"}\fR\&\&.
.RE

.TP 2
.B
\fIcfgfile\fR\&:
Uses \fIFileName\fR\& as configuration file\&. Options will override compiler defaults but can be overridden by command line options\&. Default value is \fI"\&.ic_config"\fR\&\&.
.RS 2
.LP
Example option: \fI{cfgfile, "special\&.cfg"}\fR\&\&.
.RE

.TP 2
.B
\fIuse_preproc\fR\&:
Uses a preprocessor\&. Default value is true\&.
.TP 2
.B
\fIpreproc_cmd\fR\&:
Command string to invoke the preprocessor\&. The actual command will be built as \fIpreproc_cmd++preproc_flags++FileName\fR\&
.RS 2
.LP
Example option: \fI{preproc_cmd, "erl"})\fR\&\&.
.RE

.RS 2
.LP
Example option: \fI{preproc_cmd, "gcc -x c++ -E"}\fR\&\&.
.RE

.TP 2
.B
\fIpreproc_flags\fR\&:
Flags given to the preprocessor\&.
.RS 2
.LP
Example option: \fI{preproc_flags, "-I\&.\&./include"}\fR\&\&.
.RE

.RE
.SH "CODE OPTIONS"

.RS 2
.TP 2
.B
\fIlight_ifr\fR\&:
Currently, the default setting is \fIfalse\fR\&\&. 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\&.
.RS 2
.LP
Example option: \fI{light_ifr, true}\fR\&\&.
.RE

.TP 2
.B
\fIgen_hrl\fR\&:
Generate header files\&. Default is true\&.
.TP 2
.B
\fIserv_last_call\fR\&:
Makes the last \fIgen_server handle_call\fR\& either raise a CORBA exception or just exit plainly\&. Default is the exception\&.
.TP 2
.B
\fI{{impl, IntfName}, ModName}\fR\&:
Assumes that the interface with name \fIIntfName\fR\& is implemented by the module with name \fIModName\fR\& and will generate calls to the \fIModName\fR\& module in the server behavior\&. Note that the \fIIntfName\fR\& must be a fully scoped name as in \fI"M1::I1"\fR\&\&.
.RS 2
.LP

.RE

.TP 2
.B
\fIthis\fR\&:
Adds the object reference as the first parameter to the object implementation functions\&. This makes the implementation aware of its own object reference\&. 
.br
The option comes in three varieties: \fIthis\fR\& which activates the parameter for all interfaces in the source file, \fI{this, IntfName}\fR\& which activates the parameter for a specified interface and \fI{{this, IntfName}, false}\fR\& which deactivates the parameter for a specified interface\&.
.RS 2
.LP
Example option: \fIthis)\fR\& activates the parameter for all interfaces\&.
.RE

.RS 2
.LP
Example option: \fI{this, "M1::I1"}\fR\& activates the parameter for all functions of \fIM1::I1\fR\&\&.
.RE

.RS 2
.LP
Example options: \fI[this, {{this, "M1::I2"}, false}]\fR\& activates the parameter for all interfaces except \fIM1::I2\fR\&\&.
.RE

.TP 2
.B
\fIfrom\fR\&:
Adds the invokers reference as the first parameter to the object implementation two-way functions\&. If both \fIfrom\fR\& and \fIthis\fR\& 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 \fIgen_server\fR\& and \fIOrber\fR\& documentation how this option may be used\&. 
.br
The option comes in three varieties: \fIfrom\fR\& which activates the parameter for all interfaces in the source file, \fI{from, IntfName}\fR\& which activates the parameter for a specified interface and \fI{{from, IntfName}, false}\fR\& which deactivates the parameter for a specified interface\&.
.RS 2
.LP
Example option: \fIfrom)\fR\& activates the parameter for all interfaces\&.
.RE

.RS 2
.LP
Example options: \fI[{from, "M1::I1"}]\fR\& activates the parameter for all functions of \fIM1::I1\fR\&\&.
.RE

.RS 2
.LP
Example options: \fI[from, {{from, "M1::I2"}, false}]\fR\& activates the parameter for all interfaces except \fIM1::I2\fR\&\&.
.RE

.TP 2
.B
\fIhandle_info\fR\&:
Makes the object server call a function \fIhandle_info\fR\& in the object implementation module on all unexpected messages\&. Useful if the object implementation need to trap exits\&.
.RS 2
.LP
Example option: \fIhandle_info\fR\& will activates module implementation \fIhandle_info\fR\& for all interfaces in the source file\&.
.RE

.RS 2
.LP
Example option: \fI{{handle_info, "M1::I1"}, true}\fR\& will activates module implementation \fIhandle_info\fR\& for the specified interface\&.
.RE

.RS 2
.LP
Example options: \fI[handle_info, {{handle_info, "M1::I1"}, false}]\fR\& will generate the \fIhandle_info\fR\& call for all interfaces except \fIM1::I1\fR\&\&.
.RE

.TP 2
.B
\fItimeout\fR\&:
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\&.
.RS 2
.LP
Example option: \fI{timeout,"M::I"})\fR\& produces server stub which will has an extra timeout parameter in the initialization function for that interface\&.
.RE

.RS 2
.LP
Example option: \fItimeout\fR\& produces server stub which will has an extra timeout parameter in the initialization function for all interfaces in the source file\&.
.RE

.RS 2
.LP
Example options: \fI[timeout, {{timeout,"M::I"}, false}]\fR\& produces server stub which will has an extra timeout parameter in the initialization function for all interfaces except \fIM1::I1\fR\&\&.
.RE

.TP 2
.B
\fIscoped_op_calls\fR\&:
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\&. \fIAll\fR\& of the parts generated by ic have to agree in the use of this option\&. Default is \fIfalse\fR\&\&.
.RS 2
.LP
Example options: \fI[{be,c_genserv},{scoped_op_calls,true}])\fR\& produces client stubs which sends "scoped" requests to a gen_server or a c-server\&.
.RE

.TP 2
.B
\fIuser_protocol\fR\&:
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 \fBIC C protocol\fR\&\&.
.RS 2
.LP
Example options: \fI[{be,c_client},{user_protocol, "my_special"}])\fR\& produces client stubs which use C protocol functions with the prefix "my_special"\&.
.RE

.TP 2
.B
\fIc_timeout\fR\&:
Makes sends and receives to have timeouts (C back-ends only)\&. These timeouts are specified in milliseconds\&.
.RS 2
.LP
Example options: \fI[{be,c_client},{c_timeout, {10000, 20000}}])\fR\& produces client stubs which use a 10 seconds send timeout, and a 20 seconds receive timeout\&.
.RE

.TP 2
.B
\fIc_report\fR\&:
Generates code for writing encode/decode errors to \fIstderr\fR\& (C back-ends only)\&. timeouts are specified in milliseconds\&.
.RS 2
.LP
Example options: \fI[{be,c_client}, c_report])\fR\&\&.
.RE

.TP 2
.B
\fIscl\fR\&:
Used for compatibility with previous compiler versions up to \fI3\&.3\fR\&\&. 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 \fIfalse\fR\&\&.
.RS 2
.LP
Example option: \fI{scl,true}\fR\&
.RE

.TP 2
.B
\fIprecond\fR\&:
Adds a precondition call before the call to the operation implementation on the server side\&.
.RS 2
.LP
The option comes in three varieties: \fI{precond, {M, F}}\fR\& which activates the call for operations in all interfaces in the source file, \fI{{precond, IntfName}, {M, F}}\fR\& which activates the call for all operations in a specific interface and \fI{{precond, OpName}, {M, F}}\fR\& which activates the call for a specific operation\&.
.RE

.RS 2
.LP
The precondition function has the following signature \fIm:f(Module, Function, Args)\fR\&\&.
.RE

.RS 2
.LP
Example option: \fI{precond, {mod, fun}}\fR\& adds the call of m:f for all operations in the idl file\&.
.RE

.RS 2
.LP
Example options: \fI[{{precond, "M1::I"}, {mod, fun}}]\fR\& adds the call of \fIm:f\fR\& for all operations in the interface \fIM1::I1\fR\&\&.
.RE

.RS 2
.LP
Example options: \fI[{{precond, "M1::I::Op"}, {mod, fun}}]\fR\& adds the call of \fIm:f\fR\& for the operation \fIM1::I::Op\fR\&\&.
.RE

.TP 2
.B
\fIpostcond\fR\&:
Adds a postcondition call after the call to the operation implementation on the server side\&.
.RS 2
.LP
The option comes in three varieties: \fI{postcond, {M, F}}\fR\& which activates the call for operations in all interfaces in the source file, \fI{{postcond, IntfName}, {M, F}}\fR\& which activates the call for all operations in a specific interface and \fI{{postcond, OpName}, {M, F}}\fR\& which activates the call for a specific operation\&.
.RE

.RS 2
.LP
The postcondition function has the following signature \fIm:f(Module, Function, Args, Result)\fR\&\&.
.RE

.RS 2
.LP
Example option: \fI{postcond, {mod, fun}}\fR\& adds the call of m:f for all operations in the idl file\&.
.RE

.RS 2
.LP
Example options: \fI[{{postcond, "M1::I"}, {mod, fun}}]\fR\& adds the call of \fIm:f\fR\& for all operations in the interface \fIM1::I1\fR\&\&.
.RE

.RS 2
.LP
Example options: \fI[{{postcond, "M1::I::Op"}, {mod, fun}}]\fR\& adds the call of \fIm:f\fR\& for the operation \fIM1::I::Op\fR\&\&.
.RE

.RE
.SH "WARNING OPTIONS"

.RS 2
.TP 2
.B
\fI\&'Wall\&'\fR\&:
The option activates all reasonable warning messages in analogy with the gcc -Wall option\&. Default value is true\&.
.TP 2
.B
\fImaxerrs\fR\&:
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 \fIinfinity\fR\&\&. Default number is 10\&.
.TP 2
.B
\fImaxwarns\fR\&:
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 \fIinfinity\fR\&\&. Default value is infinity\&.
.TP 2
.B
\fInowarn\fR\&:
Suppresses all warnings\&. Default value is false\&.
.TP 2
.B
\fIwarn_name_shadow\fR\&:
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\&.
.TP 2
.B
\fIpedantic\fR\&:
Activates all warning options\&. Default value is false\&.
.TP 2
.B
\fIsilent\fR\&:
Suppresses compiler printed output\&. Default value is false\&.
.RE
.SH "BACK-END OPTIONS"

.LP
Which back-end IC will generate code for is determined by the supplied \fI{be,atom()}\fR\& option\&. If left out, \fIerl_corba\fR\& is used\&. Currently, IC support the following back-ends:
.RS 2
.TP 2
.B
\fIerl_corba\fR\&:
This option switches to the IDL generation for CORBA\&.
.TP 2
.B
\fIerl_template\fR\&:
Generate CORBA call-back module templates for each interface in the target IDL file\&. Note, will overwrite existing files\&.
.TP 2
.B
\fIerl_plain\fR\&:
Will produce plain Erlang modules which contain functions that map to the corresponding interface functions on the input file\&.
.TP 2
.B
\fIerl_genserv\fR\&:
This is an IDL to Erlang generic server generation option\&.
.TP 2
.B
\fIc_client\fR\&:
Will produce a C client to the generic Erlang server\&.
.TP 2
.B
\fIc_server\fR\&:
Will produce a C server switch with functionality of a generic Erlang server\&.
.TP 2
.B
\fIjava\fR\&:
Will produce Java client stubs and server skeletons with functionality of a generic Erlang server\&.
.TP 2
.B
\fIc_genserv\fR\&:
Deprecated\&. Use \fIc_client\fR\& instead\&.
.RE
.SH "PREPROCESSOR"

.LP
The IDL compiler allows several preprocessors to be used, the \fIErlang IDL preprocessor\fR\& or other standard \fIC\fR\& 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 \fIgcc\fR\& is adequate\&.
.LP
The preprocessor command is formed by appending the prepoc_cmd to the preproc_flags option and then appending the input IDL file name\&.
.SH "CONFIGURATION"

.LP
The compiler can be configured in two ways:
.RS 2
.TP 2
*
Configuration file
.LP
.TP 2
*
Command line options
.LP
.RE

.LP
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 \fIfile:consult\fR\&\&.
.LP
An example of a configuration file, note the "\&." after each line\&.
.LP
.nf

{outdir, gen_dir}.
{{impl, "M1::M2::object"}, "obj"}.
    
.fi
.SH "OUTPUT FILES"

.LP
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 (\fI\&.hrl\fR\&/ \fI\&.h\fR\&) and one or more Erlang/C files (\fI\&.erl\fR\&/\fI\&.c\fR\&)\&. Please look at the language mapping for each back-end for details\&.
.LP
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\&.