Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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.