The R13B03 release.OTP_R13B03

1 files changed, 469 insertions, 0 deletions

diff --git a/lib/ic/doc/src/ic.xml b/lib/ic/doc/src/ic.xml
new file mode 100644
index 0000000000..9f48229425
--- /dev/null
+++ b/lib/ic/doc/src/ic.xml
@@ -0,0 +1,469 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1997</year>
+      <year>2007</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  The contents of this file are subject to the Erlang Public License,
+  Version 1.1, (the "License"); you may not use this file except in
+  compliance with the License. You should have received a copy of the
+  Erlang Public License along with this software. If not, it can be
+  retrieved online at http://www.erlang.org/.
+
+  Software distributed under the License is distributed on an "AS IS"
+  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+  the License for the specific language governing rights and limitations
+  under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </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>
+