# ic

### MODULE

ic

### MODULE SUMMARY

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 or C. The compiler generates client stub code and server behaviors.

Two kinds of files are generated for each scope, Erlang/C files and Erlang/C header files. Headers are used to store record definitions, while usual Erlang/C files contain the object interface functions, the object server or access functions for records defined in interfaces.

### EXPORTS

`ic:gen(FileName) -> Result`
`ic:gen(FileName, [Option]) -> Result`

Types:

`Result = ok | error | {ok, [Warning}} | {error, [Warning], [Error]}`
``
`Option = [ GeneralOption | CodeOption | WarningOption | SingleBackendOption | MultipleBackendOption ]`
``
`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()} | {{this, String()}, bool()} |`
`{{handle_info, String()}, bool()} | {timeout, String()} |`
`{scoped_op_calls, bool()} | {scl, 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()}`
``
`SingleBackendOption = {be, Backend}`
``
`MultipleBackendOption = {multiple_be, [ Backend ]}`
``
`Backend =`
`erl_corba | erl_plain | erl_genserv | c_genserv | c_client | c_server | java`
``
`DirNAme = string() | atom()`
``
`FileName = string() | atom()`

The tuple {`Option`, true} can be replaced with `Option` for boolean values.

### 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: ic:gen(x, [{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: ic:gen(x, [{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`
  `Example1: ic:gen(x, [{preproc_cmd, "erl"}])`
  `Example2: ic:gen(x, [{preproc_cmd, "gcc -x c++ -E"}])`
preproc_flags
  Flags given to the preprocessor.
  `Example: ic:gen(x, [{preproc_flags, "-I../include"`

### Code options

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: ic:gen(x, [this])` activates the parameter for all interfaces.
  `Example: ic:gen(x, [{this, "M1::I1"}])` activates the parameter for all functions of `M1::I1`.
  `Example: ic:gen(x, [this, {{this, "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: ic:gen(x, [handle_info])` will activates module implementation `handle_info` for all interfaces in the source file.
  `Example: ic:gen(x, [{{handle_info, "M1::I1"}, true}` will activates module implementation `handle_info` for the specified interface.
  `Example: ic:gen(x, [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: ic:gen(x, [{time_out,"M::I"}])` produces server stub which will has an extra timeout parameter in the initialization function for that interface.
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 coalition 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: ic:gen(x, [{be, c_genserv},{scoped_op_calls,true}])` produces client stub which sends "scoped" requests to the a gen_server or a c-server.
scl
  Used for compatibility with previous compiler versions up to `3.3`. Due to better semantic checks on enumerants, the compiler discovers name coalitions 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: ic:gen(x, [{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: ic:gen(x, [{precond, {mod, fun}}])` adds the call of m:f for all operations in the idl file.
  `Example: ic:gen(x, [{{precond, "M1::I"}, {mod, fun}}])` adds the call of `m:f` for all operations in the interface `M1::I1`.
  `Example: ic:gen(x, [{{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: ic:gen(x, [{postcond, {mod, fun}}])` adds the call of m:f for all operations in the idl file.
  `Example: ic:gen(x, [{{postcond, "M1::I"}, {mod, fun}}])` adds the call of `m:f` for all operations in the interface `M1::I1`.
  `Example: ic:gen(x, [{{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.

### Singe and Multiple Back-End options

- Single back-end options are declared as a tuple `{be,atom()}`, where the atom is one of back-end specific option.
  `Example: ic:gen(x, [{be, [c_client]}])`
- Multiple back-end options are declared as a tuple `{multiple_be, list()}`, where list is one or more back-end specific options.
  `Example: ic:gen(x, [{multiple_be, [erl_genserv,java]}])`

Default back-end is the single `erl_corba` backend as if it were used : `ic:gen(x, [{be, erl_corba]}])`

### Back-End specific options

Used both for single and multiple back-end generation the following atoms are back-end specific options:

erl_corba
  This option switches to the IDL generation for CORBA.
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_genserv
  Will produce a C client to the generic Erlang server.
c_client
  Will produce a C client to the generic Erlang server.
  Please note that this option have the same action as the c_genserv option. It is supposed to gradually replace the c_genserv option. For a limited period of time both options will be supported.
c_server
  Will produce a C server switch with functionality of a generic Erlang server.
java
  Will produce Java client stubs and server sceleton with functionality of a generic Erlang server.

### 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:

1. Configuration file
2. 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.

### AUTHORS

Peter Lundell - support@erlang.ericsson.se
Lars Thorsén - support@erlang.ericsson.se
Babbis Xagorarakis - support@erlang.ericsson.se

ic 4.1.2
Copyright © 1991-2002 Ericsson Utvecklings AB