diff options
Diffstat (limited to 'modules/CIAO/tests/IDL3/ImpliedIDL/All/README')
-rw-r--r-- | modules/CIAO/tests/IDL3/ImpliedIDL/All/README | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/modules/CIAO/tests/IDL3/ImpliedIDL/All/README b/modules/CIAO/tests/IDL3/ImpliedIDL/All/README new file mode 100644 index 00000000000..2f4e09eaf3c --- /dev/null +++ b/modules/CIAO/tests/IDL3/ImpliedIDL/All/README @@ -0,0 +1,88 @@ + Converting IDL3 to IDL2 + ======================= + +Introduction +============ + +This directory contains a test for the executable +tao_idl3_to_idl2, which inputs a single IDL file and +outputs a single IDL file which has the IDL3 declarations +from the input file converted to the corresponding 'implied +IDL' declarations specificed by the mapping in the CCM +document. + +This utility can be used in conjunction with some IDL compiler +that does not support IDL3 keywords and syntax. The output of +the utility can be processed by such a compiler, yielding code +in the target programming language equivalent to that which +would have been generated in one step by a CCM-aware IDL compiler. + +The tao_idl3_to_idl2 executable itself is built in +CIAO_ROOT/tools/IDL3_to_IDL2. It uses the TAO IDL compiler +front end parsing engine and the TAO IDL compiler driver +files, so it depends on ACE. The IDL generation is +accomplished by a custom backend library. + +Other Features Tested +===================== + +The IDL file keyword_clash.idl contains many identifiers that +are either escaped (to avoid a clash with IDL keywords) or +are C++ keywords. Coverting this file, then generatin and +compiling C++ from it, tests the ability of the conversion +tool to preserve these identifiers correctly when mapping +from IDL to IDL. + +The IDL file raw_include.idl is intentionaly left out of +conversion processing. It contains no IDL with 'implied IDL' +mapping. Since it is included in pass_through.idl, it +must be included in pass_through_IDL2.idl, but without itself +having the '_IDL2' suffix added. This type of 'raw' inclusion +is necessary in some cases, and the MPC file adds a command +line option to the processing of pass_through.idl to make +sure the raw_include.idl is processed in this way. + +Running The Test +================ + +This test is only to determine that the generated IDL files +are valid. So once the converted IDL file (having the +extension _IDL2.idl) is generated by tao_idl3_to_idl2, the +TAO IDL compiler is executed on the generated IDL file and +the resulting C++ files compiled. If the compilation is +successful for all such files, the test is a success. + +Notable Build Features +====================== + +Two features of the MPC file for this test are of interest: + +1. +Two of the three IDL files in the test, pass_through.idl and +include.idl, contain no IDL3 constructs, but merely test the +executable's regeneration of IDL2 constructs. Since one IDL +file is included in the other, there is a dependency that +requires both IDL files to be processed before running the +IDL compiler on pass_through_IDL2.idl. The line + + pass_through_IDL2.idl << include_IDL2.idl + +indicates this dependency to the MPC tool, ensuring the correct +order of execution. + +2. +The -Sm option passed to the IDL compiler must be used when +processing an IDL file resulting from the execution of +tao_idl3_to_idl2. This option disables the action of the +tao_idl backend 'preprocessor' (which is 'on' by default) +that adds implied IDL nodes to the Abstract Syntax Tree +for subsequent C++ code generation. In the case of an eventtype, +the CCM spec requires additional code generation for a corresponding +implied 'event consumer' IDL interface, as well as for the +eventtype itself. The tao_idl3_to_idl2 executable adds this +interface explicitly to the generated IDL file, along with the +original eventtype. Without the -Sm option, the event consumer +interface would appear redundantly in both explicit and implied +IDL, resulting in a name clash. Since the IDL compiler cannot +know the origin of the IDL file it is processing, the -Sm +option encapsulates that knowledge.
\ No newline at end of file |