path: root/lib/ic/doc/src/ic.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1997</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>ic</title>
    <prepared></prepared>
    <docno></docno>
    <checked></checked>
    <date>2004-01-08</date>
    <rev>B</rev>
  </header>
  <module>ic</module>
  <modulesummary>The Erlang IDL Compiler</modulesummary>
  <description>
    <p>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.</p>
    <p>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.</p>
  </description>
  <funcs>
    <func>
      <name>ic:gen(FileName) -> Result</name>
      <name>ic:gen(FileName, [Option]) -> Result</name>
      <fsummary>Generate stub and server code according to the OMG CORBA standard.</fsummary>
      <type>
        <v>Result = ok | error | {ok, [Warning]} | {error, [Warning], [Error]}</v>
        <v></v>
        <v>Option = [ GeneralOption | CodeOption | WarningOption | BackendOption]</v>
        <v></v>
        <v>GeneralOption = </v>
        <v>{outdir, String()} | {cfgfile, String()} | {use_preproc, bool()} |</v>
        <v>{preproc_cmd, String()} | {preproc_flags, String()}</v>
        <v></v>
        <v>CodeOption =</v>
        <v>{gen_hrl, bool()} | {serv_last_call, exception | exit} | {{impl, String()}, String()} | {light_ifr, bool()}</v>
        <v>this | {this, String()} | {{this, String()}, bool()} |</v>
        <v>from | {from, String()} | {{from, String()}, bool()} |</v>
        <v>handle_info | {handle_info, String()} | {{handle_info, String()}, bool()} |</v>
        <v>timeout | {timeout, String()} | {{timeout, String()}, bool()} |</v>
        <v>{scoped_op_calls, bool()} | {scl, bool()} |</v>
        <v>{user_protocol, Prefix} |</v>
        <v>{c_timeout, {SendTimeout, RecvTimeout}} |</v>
        <v>{c_report, bool()} |</v>
        <v>{precond, {atom(), atom()}} | {{precond, String()} {atom(), atom()}} |</v>
        <v>{postcond, {atom(), atom()}} | {{postcond, String()} {atom(), atom()}}</v>
        <v></v>
        <v>WarningOption =</v>
        <v>{'Wall', bool()} | {maxerrs, int() | infinity} |</v>
        <v>{maxwarns, int() | infinity} | {nowarn, bool()} |</v>
        <v>{warn_name_shadow, bool()} | {pedantic, bool()} |</v>
        <v>{silent, bool()}</v>
        <v></v>
        <v>BackendOption = {be, Backend}</v>
        <v></v>
        <v>Backend = erl_corba | erl_template | erl_plain | erl_genserv | c_client | c_server | java</v>
        <v></v>
        <v>DirNAme = string() | atom()</v>
        <v>FileName = string() | atom()</v>
      </type>
      <desc>
        <p>The tuple <c>{Option, true}</c> can be replaced by
          <c>Option</c> for boolean values.</p>
        <p>The <c>ic:gen/2</c> function can be called from the command 
          line as follows:</p>
        <p><c>erlc "+Option" ... File.idl</c></p>
        <p>Example:</p>
        <p><c>erlc "+{be,c_client}"  '+{outdir, "../out"}' File.idl</c></p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>General options</title>
    <taglist>
      <tag><em>outdir</em></tag>
      <item>
        <p>Places all output files in the directory given by the option.
          The directory will be created if it does not already exist.</p>
        <p>Example option: <c>{outdir, "output/generated"}</c>.</p>
      </item>
      <tag><em>cfgfile</em></tag>
      <item>
        <p>Uses <em>FileName</em> as configuration file. Options will
          override compiler defaults but can be overridden by command line
          options. Default value is <c>".ic_config"</c>.</p>
        <p>Example option: <c>{cfgfile, "special.cfg"}</c>.</p>
      </item>
      <tag><em>use_preproc</em></tag>
      <item>
        <p>Uses a preprocessor. Default value is true.</p>
      </item>
      <tag><em>preproc_cmd</em></tag>
      <item>
        <p>Command string to invoke the preprocessor. The actual
          command will be built as
          <c>preproc_cmd++preproc_flags++FileName</c></p>
        <p>Example option: <c>{preproc_cmd, "erl"})</c>.</p>
        <p>Example option: <c>{preproc_cmd, "gcc -x c++ -E"}</c>.</p>
      </item>
      <tag><em>preproc_flags</em></tag>
      <item>
        <p>Flags given to the preprocessor.</p>
        <p>Example option: <c>{preproc_flags, "-I../include"}</c>.</p>
      </item>
    </taglist>
  </section>

  <section>
    <title>Code options</title>
    <taglist>
      <tag><em>light_ifr</em></tag>
      <item>
        <p>Currently, the default setting is <c>false</c>. 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.</p>
        <p>Example option: <c>{light_ifr, true}</c>.</p>
      </item>
      <tag><em>gen_hrl</em></tag>
      <item>
        <p>Generate header files. Default is true.</p>
      </item>
      <tag><em>serv_last_call</em></tag>
      <item>
        <p>Makes the last <c>gen_server handle_call</c> either raise a
          CORBA exception or just  exit plainly. Default is the exception.
          </p>
      </item>
      <tag><em>{{impl, IntfName}, ModName}</em></tag>
      <item>
        <p>Assumes that the interface with name <em>IntfName</em> is
          implemented by the module with name <em>ModName</em> and
          will generate calls to the <em>ModName</em> module in the
          server behavior.  Note that the <em>IntfName</em> must be a
          fully scoped name as in <c>"M1::I1"</c>.</p>
        <p></p>
      </item>
      <tag><em>this</em></tag>
      <item>
        <p>Adds the object reference as the first parameter to the
          object implementation functions. This makes the
          implementation aware of its own object reference. 
                    <br></br>
The option
          comes in three varieties: <c>this</c> which activates the
          parameter for all interfaces in the source file, <c>{this, IntfName}</c> which activates the parameter for a specified
          interface and <c>{{this, IntfName}, false}</c> which
          deactivates the parameter for a specified
          interface.</p>
        <p>Example option: <c>this)</c> activates the parameter for
          all interfaces.</p>
        <p>Example option: <c>{this, "M1::I1"}</c> activates the
          parameter for all functions of <c>M1::I1</c>.</p>
        <p>Example options: <c>[this, {{this, "M1::I2"}, false}]</c>
          activates the parameter for all interfaces except
          <c>M1::I2</c>.</p>
      </item>
      <tag><em>from</em></tag>
      <item>
        <p>Adds the invokers reference as the first parameter to the
          object implementation two-way functions. If both
          <c>from</c> and <c>this</c> 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 <c>gen_server</c> and <c>Orber</c>
          documentation how this option may be used.            <br></br>
The option
          comes in three varieties: <c>from</c> which activates the
          parameter for all interfaces in the source file, <c>{from, IntfName}</c> which activates the parameter for a specified
          interface and <c>{{from, IntfName}, false}</c> which
          deactivates the parameter for a specified interface.</p>
        <p>Example option: <c>from)</c> activates the parameter for
          all interfaces.</p>
        <p>Example options: <c>[{from, "M1::I1"}]</c> activates the
          parameter for all functions of <c>M1::I1</c>.</p>
        <p>Example options: <c>[from, {{from, "M1::I2"}, false}]</c>
          activates the parameter for all interfaces except
          <c>M1::I2</c>.</p>
      </item>
      <tag><em>handle_info</em></tag>
      <item>
        <p>Makes the object server call a function <c>handle_info</c>
          in the object implementation module on all unexpected
          messages. Useful if the object implementation need to trap
          exits.</p>
        <p>Example option: <c>handle_info</c> will activates module
          implementation <c>handle_info</c> for all interfaces in the
          source file.</p>
        <p>Example option: <c>{{handle_info, "M1::I1"}, true}</c>
          will activates module implementation <c>handle_info</c> for
          the specified interface.</p>
        <p>Example options: <c>[handle_info, {{handle_info, "M1::I1"}, false}]</c> will generate the <c>handle_info</c>
          call for all interfaces except <c>M1::I1</c>.</p>
      </item>
      <tag><em>timeout</em></tag>
      <item>
        <p>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.</p>
        <p>Example option: <c>{timeout,"M::I"})</c> produces server
          stub which will has an extra timeout parameter in the initialization 
          function for that interface.</p>
        <p>Example option: <c>timeout</c> produces server
          stub which will has an extra timeout parameter in the initialization 
          function for all interfaces in the source file.</p>
        <p>Example options: <c>[timeout, {{timeout,"M::I"}, false}]</c>
          produces server stub which will has an extra timeout
          parameter in the initialization function for all interfaces
          except <c>M1::I1</c>.</p>
      </item>
      <tag><em>scoped_op_calls</em></tag>
      <item>
        <p>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. <c>All</c> of the parts generated by ic
          have to agree in the use of this option. Default is
          <c>false</c>.  </p>
        <p>Example options:
          <c>[{be,c_genserv},{scoped_op_calls,true}])</c> produces
          client stubs which sends "scoped" requests to a gen_server
          or a c-server.</p>
      </item>
      <tag><em>user_protocol</em></tag>
      <item>
        <p>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 <seealso marker="ic_c_protocol">IC C protocol</seealso>.</p>
        <p>Example options:
          <c>[{be,c_client},{user_protocol, "my_special"}])</c> produces
          client stubs which use C protocol functions with the prefix 
          "my_special".</p>
      </item>
      <tag><em>c_timeout</em></tag>
      <item>
        <p>Makes sends and receives to have timeouts (C back-ends only).  These
          timeouts are specified in milliseconds. </p>
        <p>Example options:
          <c>[{be,c_client},{c_timeout, {10000, 20000}}])</c> produces
          client stubs which use a 10 seconds send timeout, and a
          20 seconds receive timeout.</p>
      </item>
      <tag><em>c_report</em></tag>
      <item>
        <p>Generates code for writing encode/decode errors to <c>stderr</c> (C back-ends only).
          timeouts are specified in milliseconds. </p>
        <p>Example options:
          <c>[{be,c_client}, c_report])</c>.</p>
      </item>
      <tag><em>scl</em></tag>
      <item>
        <p>Used for compatibility with previous compiler versions up
          to <c>3.3</c>.  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
          <c>false</c>.  </p>
        <p>Example option: <c>{scl,true}</c></p>
      </item>
      <tag><em>precond</em></tag>
      <item>
        <p>Adds a precondition call before the call to the operation
          implementation on the server side.</p>
        <p>The option comes in three varieties: <c>{precond, {M, F}}</c> which activates the call for operations in all
          interfaces in the source file, <c>{{precond, IntfName}, {M, F}}</c> which activates the call for all operations in a
          specific interface and <c>{{precond, OpName}, {M, F}}</c>
          which activates the call for a specific operation.</p>
        <p>The precondition function has the following signature
          <c>m:f(Module, Function, Args)</c>.</p>
        <p>Example option: <c>{precond, {mod, fun}}</c> adds the call
          of m:f for all operations in the idl file.</p>
        <p>Example options: <c>[{{precond, "M1::I"}, {mod, fun}}]</c>
          adds the call of <c>m:f</c> for all operations in the
          interface <c>M1::I1</c>.</p>
        <p>Example options: <c>[{{precond, "M1::I::Op"}, {mod, fun}}]</c> adds the call of <c>m:f</c> for the operation
          <c>M1::I::Op</c>.</p>
      </item>
      <tag><em>postcond</em></tag>
      <item>
        <p>Adds a postcondition call after the call to the operation
          implementation on the server side. </p>
        <p>The option comes in three varieties: <c>{postcond, {M, F}}</c> which activates the call for operations in all
          interfaces in the source file, <c>{{postcond, IntfName}, {M, F}}</c> which activates the call for all operations in a
          specific interface and <c>{{postcond, OpName}, {M, F}}</c>
          which activates the call for a specific operation.</p>
        <p>The postcondition function has the following signature
          <c>m:f(Module, Function, Args, Result)</c>.</p>
        <p>Example option: <c>{postcond, {mod, fun}}</c> adds the call
          of m:f for all operations in the idl file.</p>
        <p>Example options: <c>[{{postcond, "M1::I"}, {mod, fun}}]</c>
          adds the call of <c>m:f</c> for all operations in the
          interface <c>M1::I1</c>.</p>
        <p>Example options: <c>[{{postcond, "M1::I::Op"}, {mod, fun}}]</c> adds the call of <c>m:f</c> for the operation
          <c>M1::I::Op</c>.</p>
      </item>
    </taglist>
  </section>

  <section>
    <title>Warning options</title>
    <taglist>
      <tag><em>'Wall'</em></tag>
      <item>
        <p>The option activates all reasonable warning messages  in
          analogy with the gcc -Wall option. Default value is true.</p>
      </item>
      <tag><em>maxerrs</em></tag>
      <item>
        <p>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 <c>infinity</c>. Default number is 10.</p>
      </item>
      <tag><em>maxwarns</em></tag>
      <item>
        <p>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 <c>infinity</c>. Default value is
          infinity.</p>
      </item>
      <tag><em>nowarn</em></tag>
      <item>
        <p>Suppresses all warnings. Default value is false.</p>
      </item>
      <tag><em>warn_name_shadow</em></tag>
      <item>
        <p>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. </p>
      </item>
      <tag><em>pedantic</em></tag>
      <item>
        <p>Activates all warning options. Default value is false.</p>
      </item>
      <tag><em>silent</em></tag>
      <item>
        <p>Suppresses compiler printed output. Default value is false.</p>
      </item>
    </taglist>
  </section>

  <section>
    <title>Back-End options</title>
    <p>Which back-end IC will generate code for is determined by the supplied
      <c>{be,atom()}</c> option. If left out, <c>erl_corba</c> is used.
      Currently, IC support the following back-ends:</p>
    <taglist>
      <tag><em>erl_corba</em></tag>
      <item>
        <p>This option switches to the IDL generation for CORBA.</p>
      </item>
      <tag><em>erl_template</em></tag>
      <item>
        <p>Generate CORBA call-back module templates for each interface in the target
          IDL file. Note, will overwrite existing files.</p>
      </item>
      <tag><em>erl_plain</em></tag>
      <item>
        <p>Will produce plain Erlang modules which contain functions that
          map to the corresponding interface functions on the input file.</p>
      </item>
      <tag><em>erl_genserv</em></tag>
      <item>
        <p>This is an IDL to Erlang generic server generation option.</p>
      </item>
      <tag><em>c_client</em></tag>
      <item>
        <p>Will produce a C client to the generic Erlang server.</p>
      </item>
      <tag><em>c_server</em></tag>
      <item>
        <p>Will produce a C server switch with functionality of a
          generic Erlang server.</p>
      </item>
      <tag><em>java</em></tag>
      <item>
        <p>Will produce Java client stubs and server skeletons with
          functionality of a generic Erlang server.</p>
      </item>
      <tag><em>c_genserv</em></tag>
      <item>
        <p>Deprecated. Use <c>c_client</c> instead.</p>
      </item>
    </taglist>
  </section>

  <section>
    <title>Preprocessor</title>
    <p>The IDL compiler allows several preprocessors to be used, the
      <c>Erlang IDL preprocessor</c> or other standard <c>C</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 <c>gcc</c> is adequate.</p>
    <p>The preprocessor command is formed by appending the prepoc_cmd
      to the preproc_flags option and then appending the input IDL
      file name.</p>
  </section>

  <section>
    <title>Configuration</title>
    <p>The compiler can be configured in two ways:</p>
    <list type="ordered">
      <item>
        <p>Configuration file</p>
      </item>
      <item>
        <p>Command line options</p>
      </item>
    </list>
    <p>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
      <c>file:consult</c>.</p>
    <p>An example of a configuration file, note the "." after each
      line.</p>
    <code type="none">
{outdir, gen_dir}.
{{impl, "M1::M2::object"}, "obj"}.
    </code>
  </section>

  <section>
    <title>Output files</title>
    <p>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 (<c>.hrl</c>/
      <c>.h</c>) and one or more Erlang/C files (<c>.erl</c>/<c>.c</c>).
      Please look at the language mapping for each back-end for details.</p>
    <p>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.</p>
  </section>
  
</erlref>