diff options
Diffstat (limited to 'lib/ic/doc/src/ic.xml')
| -rw-r--r-- | lib/ic/doc/src/ic.xml | 469 |
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> + |