aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ic/doc/src/ic.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ic/doc/src/ic.xml')
-rw-r--r--lib/ic/doc/src/ic.xml469
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>
+