diff options
Diffstat (limited to 'lib/ic/doc/src/ic.xml')
| -rw-r--r-- | lib/ic/doc/src/ic.xml | 468 |
1 files changed, 0 insertions, 468 deletions
diff --git a/lib/ic/doc/src/ic.xml b/lib/ic/doc/src/ic.xml deleted file mode 100644 index 98e8414a4e..0000000000 --- a/lib/ic/doc/src/ic.xml +++ /dev/null @@ -1,468 +0,0 @@ -<?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> - |