diff options
Diffstat (limited to 'CIAO/CCF/Documentation')
| -rw-r--r-- | CIAO/CCF/Documentation/Build.html | 402 | ||||
| -rw-r--r-- | CIAO/CCF/Documentation/DesignNotes | 459 | ||||
| -rw-r--r-- | CIAO/CCF/Documentation/TODO | 98 |
3 files changed, 959 insertions, 0 deletions
diff --git a/CIAO/CCF/Documentation/Build.html b/CIAO/CCF/Documentation/Build.html new file mode 100644 index 00000000000..94415303afe --- /dev/null +++ b/CIAO/CCF/Documentation/Build.html @@ -0,0 +1,402 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<!-- + +file : Documentation/Build.html +author : Boris Kolpackov <boris@dre.vanderbilt.edu> +cvs-id : $Id$ +--> + +<html> + +<head> + + <title>Building CORBA Compiler Framework (CCF) Libraries</title> + + <meta name="author" content="Boris Kolpackov"/> + <meta name="keywords" content="build,compile,make,CCF,CORBA,compiler,framework,library"/> + <meta name="description" content="Building CCF Libraries"/> + <meta http-equiv="Content-Language" content="en"/> + + <style type="text/css"> + body { + font-family : sans-serif; + color : black; + background : white; + + max-width : 40em; + padding : 2em 2em 2em 3em; + margin : 0 0 0 0; + } + + h1, h2, h3, h4, h5, h6 { + font-family : sans-serif; + font-weight : 500; + } + + h1 { font-size : 170%; } + h2 { font-size : 125%; + text-decoration : underline + } + ul.toc li { + padding : .4em 0em 0em 0em; + } + + ol.multiline li { + padding-top : 0.6em; + padding-bottom : 0.6em; + } + + </style> + +</head> + +<body> +<h1>Building CORBA Compiler Framework (CCF) Libraries</h1> +<h2>Table of Contents</h2> +<ol> +<li><a href="#prereqs">Prerequisite Libraries</a></li> +<ul class="toc"> +<li><a href="#debian">Debian GNU/Linux [i386.deb]</a></li> + +<li><a href="#redhat">RedHat OS family [i386.rpm]</a></li> + +<li><a href="#other_platforms">Other GNU/Linux or UNIX Distributions & Windows</a> +<ul> +<li><a href="#cxx">C++</a></li> +<li><a href="#boost">Boost Libraries</a></li> +<li><a href="#utility">Utility Library</a></li> +</ul></li> + +<!--li><a href="#windows">Windows</a> +<ul> +<li><a href="#windows_cxx">C++</a></li> +<li><a href="#windows_boost">Boost Libraries</a></li> +<li><a href="#windows_utility">Utility Library</a></li> +</ul></li --> +</ul> + +<li><a href="#initial_setup">Configuring the Build Environment</a></li> +<li><a href="#building_ccf">Building CORBA Compiler Framework (CCF)</a></li> +</ol> + +<hr /> +<h1><a name="prereqs">Prerequisite Libraries</a></h1> + +<!-- Debian --> + +<h2><a name="debian">Debian GNU/Linux [i386.deb]</a></h2> + +<p>You will need to install the following packages from the Debian package repository: + +<ol> +<li><code>libboost-dev-1.30.2-2</code> or better</li> +<li><code>libboost-regex-dev-1.30.2-2</code> or better</li> +</ol> + +<p>Additionally, you will need to download and and install + +<ol> +<li><a href="ftp://kolpackov.net/pub/Utility/Utility-1.2/deb/libutility_1.2.2-1_i386.deb"> +<code>libutility_1.2.2-1_i386.deb</code></a></li> +<li><a href="ftp://kolpackov.net/pub/Utility/Utility-1.2/deb/libutility-dev_1.2.2-1_i386.deb"> +<code>libutility-dev_1.2.2-1_i386.deb</code></a></li> +</ol> + +For example, if you downloaded them into <code>/tmp</code> then to +install you can issue these commands:</p> + +<pre>$ cd /tmp +$ dpkg -i libutility*.deb +</pre> +</p> + +<!-- RedHat --> + +<h2><a name="redhat">RedHat OS family [i386.rpm]</a></h2> + +<p>You will need to install the following RedHat packages:</p> + +<ol> + +<li><a href="http://www.dre.vanderbilt.edu/cidlc/prerequisites/rpm/boost-devel-1.30.2-2.i386.rpm"> +<code>boost-devel-1.30.2-2.i386.rpm</code></a></li> + +<li><a href="ftp://kolpackov.net/pub/Utility/Utility-1.2/rpm/Utility-1.2.2-3.i386.rpm"> +<code>Utility-1.2.2-3.i386.rpm</code></a></li> +</ol> + +<p>For example, if you downloaded them into <code>/usr/src/redhat/RPMS/i386 +</code> then to install you can issue these commands:</p> + +<pre>$ cd /usr/src/redhat/RPMS/i386 +$ rpm -Uhv boost-devel-1.30.2-2.i386.rpm +$ rpm -Uhv Utility-1.2.2-3.i386.rpm +</pre> +</p> + +<!-- Linux --> + +<h2><a name="other_platforms">Other GNU/Linux or UNIX Distributions & Windows</a></h2> + +<!-- + +<h2><a name="linux_make">Make</a></h2> +<p>Currently in order to build CCF Libraries you will need +<a href="http://savannah.gnu.org/projects/make/">GNU make</a> 3.80 with the +following bug fixes: + +<ol> +<li> +<a href="http://savannah.gnu.org/bugs/index.php?func=detailitem&item_id=1516"> +eval inside condition</a></li> + +<li> +<a href="http://savannah.gnu.org/bugs/index.php?func=detailitem&item_id=1517"> +eval memory exhaustion</a></li> +</ol> + +Your system distributor should have the recent version of make with those +fixes applied. +</p> + +<p>If you are unsure whether you have those bugfixes or not then you can +just try building CCF and if you see some strange make-related errors then +you will need to upgrade.</p> + +--> + +<h3><a name="cxx">C++</a></h3> +<p>On the Lunix/UNIX platforms, you can use any standard-conformant C++ compiler. +We recommend you use the lastest stable release of the <a href="http://gcc.gnu.org">GNU C++</a> + +compiler.</p> + +<p>On the Windows platform, VC++ 7.1 or better is required to build CCF. We do not +support VC++ 6 or VC++ 7.0.</p> + +<h3><a name="boost">Boost Libraries</a></h3> +<p>In order to build CCF you will need the following libraries from the +<a href="http://www.boost.org">Boost distribution</a>:</p> + +<ol> +<li>regex</li> +<li>filesystem</li> +<li>spirit parser framework</li> +</ol> + +<p>There are two commonly used ways to obtain those libraries: you can get +precompiled binaries from your system distributor or download source code and +compile it yourself. The first approach is recommended where available +and if you got precompiled binaries then you can skip the rest of this +section.</p> + +</p>If you choose to compile Boost Libraries yourself please refer to the +<a href="http://www.boost.org/more/getting_started.html">Boost Building +Instructions</a>. Please remember the install locations of the boost libraries +because they will be needed to properly configure your environment for building +CCF.<p> + +<!--p>After you have successfully compiled necessary libraries in the boost +distribution you need to do one more thing. Inside the boost distribution +directory (e.g. <code>boost-1.30.2</code>) create a directory with the name +<code>lib</code> and copy (or soft link) <code>libboost_filesystem.a</code> +and <code>libboost_regex.a</code> into it.</p--> + +<h3><a name="utility">Utility Library</a></h3> + +<p>Another prerequisite for CCF is the Utility Library. You don't need +to build anything in this library. The Utility library is available in +the following two different forms for convinience:</p> + +<ol> +<li>A <a href="http://www.dre.vanderbilt.edu/cidlc/prerequisites/Utility-1.2.2.tar.bz2">bz2 package</a> for unix based platforms including Unix.</li> +<li>A <a href="http://www.dre.vanderbilt.edu/cidlc/prerequisites/Utility-1.2.2.tar.zip">zip package</a> for Win32 based platforms. </li> +</ol> + +<p>Just unpack it to some convenient place and remember its location because it will be need +to properly configure the build environment for CCF.</p> + +<!-- Windows --> + +<!--h2><a name="windows">Windows</a></h2> + +<h3><a name="windows_cxx">C++</a></h3> + +<h3><a name="windows_boost">Boost Libraries</a></h3> +<p>In order to build CCF you will need the following libraries from +the <a href="http://www.boost.org">Boost distribution</a>: + +<ol> +<li>regex</li> +<li>filesystem</li> +<li>spirit parser framework</li> +</ol> + +<p>Below is the list of step-by-step instructions for building boost. As +an example, I assume that the installation directory is <code>D:\lib</code>. +</p> + +<ol class="multiline"> + +<li>Download boost source distribution version <code>1.30.2</code> (<code>boost-1.30.2.zip</code>) +from the <a href="http://sourceforge.net/project/showfiles.php?group_id=7586">Boost web site</a>. +After downloading unzip the file in <code>D:\lib</code> so that you get +<code>D:\lib\boost-1.30.2</code>. Note that boost version <code>1.31.0</code> + +will not work.</li> + +<li>Download the latest pre-built +<a href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941"> +<code>boost-jam</code></a>. At the time of writing, the latest version was +<code>3.1.7</code> thus the file you download would be +<code>bjam-3.1.7-ntx86.zip</code>. Unzip this file in <code>D:\lib</code> so +that you get <code>D:\lib\bin.ntx86\bjam.exe</code>.</li> + +<li>Open a command prompt and <code>cd D:\lib\boost-1.30.2</code>. Then +issue the following command. + +<pre>D:\lib\bin.ntx86\bjam.exe "-sTOOLS=vc7.1" +</pre> +</li> + +<li>Create a directory called <code>lib</code> in +<code>D:\lib\boost-1.30.2</code>.</li> + +<li>Copy <code>D:\lib\boost-1.30.2\libs\filesystem\build\bin\libboost_filesystem.lib\vc7.1\debug\runtime-link-dynamic\libboost_filesystem.lib</code> +to <code>D:\lib\boost-1.30.2\lib\libboost_filesystem_debug.lib</code>.<br> +(Don't ask me who came up with this directory structure ;-) +</li> + +<li>Copy <code>D:\lib\boost-1.30.2\libs\regex\build\bin\libboost_regex.lib\vc7.1\debug\runtime-link-dynamic\libboost_regex.lib</code> +to <code>D:\lib\boost-1.30.2\lib\libboost_regex_debug.lib</code>. +</li> + +<li>Add <code>D:\lib\boost-1.30.2</code> to your VC7.1 include directory +search list (Go to Tools -> Options -> Projects -> VC++ Directories -> Include Files). +Add <code>D:\lib\boost-1.30.2\lib</code> to your VC7.1 library directory +search list.</li> + +</ol> + +<p>Please refer to the +<a href="http://www.boost.org/more/getting_started.html">Boost Building +Instructions</a> if you have any questions.<p> + +<h3><a name="windows_utility">Utility Library</a></h3> + +<p>Another prerequisite for CCF is +<a href="http://www.dre.vanderbilt.edu/cidlc/prerequisites/Utility-1.2.2.tar.bz2">Utility +Library</a>. You don't need to build anything in this library. Just unpack +it to some convenient place and add it to your VC7.1 include directory search +list. For example if you unpacked <code>Utility-1.2.2.tar.bz2</code> in +<code>D:\lib</code> then add <code>D:\lib\Utility-1.2.2</code> to your +search list.</p --> + +<hr /> + +<!-- Configuring the Build Environment --> + +<h1><a name="initial_setup">Configuring the Build Environment</a></h1> + +<p>Before you can start building CCF you need to specify the location +of Boost Libraries and Utility Library. There are two ways you can do +this. The first way is to specify the environment variables + +<code>BOOST_ROOT, BOOST_INCLUDE, BOOST_LIB, BOOST_VERSION, BOOST_CFG</code> +and <code>UTILITY_ROOT</code>. + +<p>To configure <code>BOOST_ROOT</code> and <code>UTILITY_ROOT</code>, + +set both enviroment variables to the root directory for the respective +libraries as follows:</p> +<ul> +<li>On Linux/UNIX +<pre> +%> export BOOST_ROOT=<path_to_boost> +%> export UTILITY_ROOT=<path_to_utility> +</pre> +</li> +<li>On Windows +<pre> +%> set BOOST_ROOT=<path_to_boost> +%> set UTILITY_ROOT=<path_to_utility> +</pre> +</li> +</ul> + +<p>If <code>BOOST_INCLUDE</code> and <code>BOOST_LIB</code> are not initialized, + +then their values are derived from <code>BOOST_ROOT</code> as follows:<p> + +<pre> +BOOST_LIB := $(BOOST_ROOT)/lib +BOOST_INCLUDE := $(BOOST_ROOT) +</pre> + +<p><code>BOOST_VERSION</code> and <code>BOOST_CFG</code> are two environment variables that +depend on the version and configuration of Boost that you are using. <code>BOOST_VERSION</code> +is initialized as follows:</p> +<ol> +<li>Look in <code>$BOOST_ROOT/include/boost</code> directory</li> +<li>If there is another boost directory, e.g. <code>boost-1_32</code> for building boost-1.32, then this is your version + <ul> + <li>On Linux/UNIX: + + <pre><code>%> export BOOST_VERSION=boost-1_32</code></pre></li> + <li>On Windows: + + <pre><code>%> set BOOST_VERSION=boost-1_32</code></pre></li> + </ul> +</li> +</ol> +<p> +<code>BOOST_CFG</code> depends on which configuration of the boost libraries you want use for CCF. If +you look in <code>$BOOST_ROOT/lib</code>, you will notice all the Boost libraries. Each library has +the compiler and threading support, e.g. <code>-vc71-mt</code> for VC++ 7.1 and multi-threaded, as part + +of the filename. If this is not the case for your libraries, then you can + +<a href="#building_ccf">skip</a> this section and continue at + +<a href="#building_ccf">Building CORBA Compiler Framework (CCF)</a>. This part of + +the filename is known as the <code>BOOST_CFG</code> and needs to be specified. For example, if you are + +using VC++ 7.1 and want to use the multi-threaded version of the libraries for CCF, your would do the +following: +<blockquote><code>%> set BOOST_CFG=-vc71-mt</code></blockquote> +This can be done similarly on the Linux/UNIX platforms depending on your compiler version and the + +Boost configuration you want to use.</p> + +<p>Alternatively, you can specify all values for <code>BOOST_*</code> and +<code>UTILITY_*</code> in <code>$CIAO_ROOT/CCF/Config.rules</code></p> + +<!-- Building CORBA Compiler Framework (CCF) --> + +<hr /> +<h1><a name="building_ccf">Building CORBA Compiler Framework (CCF)</a></h1> + +Now that you have built and installed the required libraries, you are now ready +to build the CCF libraries. If there are any makefiles or project solutions +in the CCF directory we recommend that you disgard those and regenerate +all the projects files using MPC. To build all project files and CCF, please use the +following steps: +<ol> +<li><code>%> cd $CIAO_ROOT/CCF/CCF</code></li> +<li><code>%> $ACE_ROOT/bin/mwc.pl -type <project-type> -static -features cidl=1, exceptions=1, boost=1</code></li> +</ol> +On Linux/UNIX, if you are building with a make utility, e.g., gmake, use the following command +to build CCF: + +<pre>%> gmake cidl=1 exceptions=1 boost=1</pre> +<p>If you are building on Windows, just open the generated solution file.</p> + +<p><b>Note:</b> If you are building CCF on a Windows platform, use <code>%ACE_ROOT%\bin\mwc.pl</code> instead + +<code>of $ACE_ROOT/bin/mwc.pl</code>. Also, for a list of project types and other command-line options +supported by MPC, type <code>$ACE_ROOT/bin/mwc.pl --help</code>.</p> +</body> +</html> diff --git a/CIAO/CCF/Documentation/DesignNotes b/CIAO/CCF/Documentation/DesignNotes new file mode 100644 index 00000000000..1cf74e88400 --- /dev/null +++ b/CIAO/CCF/Documentation/DesignNotes @@ -0,0 +1,459 @@ + +Note: this file is somewhat outdated + +Intention of this file is to capture and document CIDL complier design +ideas/decisions. + +Conceptual parts of CIDL compiler design +---------------------------------------- + +Option Parser Consists of option parser and option + database. + +C Preprocessor Interfacing Represents mechanism of preprocessing + cidl files. + +IDL Compiler Interfacing Represents mechanism of invoking IDL + compiler. + +Scanner Scanner for preprocessed cidl file. + +Parser CIDL grammar parser. Consists of grammar + and semantic rules. + +Syntax Tree Intermediate representation of cidl file. + Consists of syntax tree nodes itself and + perhaps symbol tables. + +Semantic Analyzer Traverses Syntax Tree and performs + semantic analysis as well as some + semantic expansions. + + +Code Generation Stream Stream to output generated code to. Used + by concrete Code Generators + +Code Generators +{ + + Executor Mapping Generator Generator for local executor mapping. + + Executor Implementation Generator Generator for partial implementation + of local executor mapping. + + Skeleton Thunk Generator Generator for skeleton thunks i.e. + code that implements skeleton and + thunks user-defined functions to + executor mapping. +} + +Compiler driver Establishes order of execution of + different components as part of + compilation process. + + +How everything works together +----------------------------- + +(1) Compiler Driver executes Option Parser to populate Option Database + +(2) Compiler Driver executes C Preprocessor on a supplied cidl file + +(3) Compiler Driver executes Parser which uses Scanner to scan preprocessed + cidl file and generates Syntax Tree by means of semantic rules. + +(4) At this point we have Syntax Tree corresponding to the original cidl + file. Compiler Driver executes Executor Mapping Generator, + Executor Implementation Generator and Skeleton Thunk Generator on + Syntax Tree. + + + +General Design Ideas/Decision +------------- + +[IDEA]: There is an effort to use autoconf/automake in ACE/TAO. Maybe it's + a good idea to start using it with CIDLC? There is one side advantage + of this approach: if we decide to embed GCC CPP then we will have to + use configure (or otherwise ACE-ify the code which doesn't sound like + a right solution). + +[IDEA]: CIDLC is a prototype for a new IDLC, PSDLC and IfR model. Here are + basic concepts: + + - use common IDL grammar, semantic rules and syntax tree nodes + for IDLC, CIDLC, PSDLC and IfR. Possibly have several libraries + for example ast_idl-2.so, ast_idl-3.so, scaner_idl-2.so + scaner_idl-3.so, parser_idl-2.so, parser_idl-3.so. Dependency + graph would look like this: + + + ast_idl-2.so scanner_idl-2.so + | | + |---------------------------------| + | | | + | | | + | parser_idl-2.so | + | | | + ast_idl-3.so | scanner_idl-3.so + | | | + | | | + | | | + ---------parser_idl-3.so--------- + + Same idea applies for CIDL and PSDL. + + + - use the same internal representation (syntax tree) in all + compilers and IfR. This way at some stage if we will need + to make one of the compilers IfR-integrated (import keyword?) + then it will be a much easier task than it's now. This internal + representation may also be usable in typecodes + + @@ boris: not clear to me. + + @@ jeff: A typecode is like a piece of the Syntax Tree with these + exceptions - + + (1) There is no typecode for an IDL module. + + (2) Typecodes for interfaces and valuetypes lack some of the + information in the corresponding Syntax Tree nodes. + + With these exceptions in mind, a typecode can be composed and + traversed in the same manner as a Syntax Tree, perhaps with + different classes than used to compose the ST itself. + + @@ boris: Ok, let me see if I got it right. So when typecode + is kept in parsed state (as opposite to binary) (btw, when + does it happen?) it makes sense to apply the same techniques + (if in fact not the same ST nodes and traversal mechs) as + for XIDL compilation. + +[IDEA]: We should be consistent with the way external compilers that we call + report errors. For now those are CPP and IDLC. + +Option Parser +------------- + +[IDEA]: Use Spirit parser framework to generate option parser. + +[IDEA]: Option Database is probably a singleton. + + @@ jeff: This is a good idea, especially when passing some of the + options to a preprocessor or spawned IDL compier. But I think we + will still need 'state' classes for the front and back ends (to + hold values set by command line options and default values) so + we can keep them decoupled). + + + @@ boris: I understand what you mean. Though I think we will be + able to do with one 'runtime database'. Each 'compiler module' + will be able to populate its 'namespace' with (1) default + values, (2) with module-specific options and (3) arbitrary + runtime information. I will present prototopy design shortly. + + +[IDEA]: It seems we will have to execute at least two external programs + as part of CIDLC execution: CPP and IDLC. Why wouldn't we follow + GCC specs model (gcc -dumpspecs). Here are candidates to be put into + specs: + + - default CPP name and options + - default IDLC name and options + - default file extensions and formats for different mappings + - other ideas? + +[IDEA]: Provide short and long option names (e.g. -o and --output-dir) + for every option (maybe except -I, -D, etc). + + +C Preprocessor Interfacing +-------------------------- + +[IDEA]: Embed/require GCC CPP + +[IDEA]: We need a new model of handling includes in CIDLC (as well as IDLC). + Right now I'm mentally testing a new model (thanks to Carlos for the + comments). Soon I will put the description here. + +[IDEA]: We cannot move cidl file being preprocessed to for example /tmp + as it's currently the case with IDLC. + +[IDEA]: Can we use pipes (ACE Pipes) portably to avoid temporary files? + (Kitty, you had some ideas about that?) + + + +IDL Compiler Interfacing +------------------------ + +[IDEA]: Same as for CPP: Can we use pipes? + + @@ jeff: check with Nanbor on this. I think there may be CCM/CIAO + use cases where we need the intermediate IDL file. + +[IDEA]: Will need a mechanism to pass options to IDLC from CIDLC command + line (would be nice to have this ability for CPP as well). + Something like -x in xterm? Better ideas? + + + +Scanner +------ + +[IDEA]: Use Spirit framework to construct scanner. The resulting sequence + can be sequence of objects? BTW, Spirit parser expects a "forward + iterator"-based scanner. So this basically mean that we may have to + keep the whole sequence in memory. BTW, this is another good reason + to have scanner: if we manage to make scanner a predictable parser + (i.e. no backtracking) then we don't have to keep the whole + preprocessed cidl file in memory. + + + +Parser +------ + +[IDEA]: Use Spirit framework to construct parser. + +[IDEA]: Define IDL grammar as a number of grammar capsules. This way it's + much easier to reuse/inherit even dynamically. Need to elaborate + this idea. + +[IDEA]: Use functors as semantic actions. This way we can specify (via + functor's data member) on which Syntax Tree they are working. + Bad side: semantic rules are defined during grammar construction. + However we can use a modification of the factory method pattern. + Better ideas? + + @@ jeff: I think ST node creation with a factory + is a good idea - another ST implementation could be plugged in, + as long as it uses a factory with the same method names. + + @@ boris: Right. In fact it's our 'improved' way of handling 'BE' + usecases. + + + +Syntax Tree +----------- + +[IDEA]: Use interface repository model as a base for Syntax Tree hierarchy. + +[IDEA]: Currently (in IDLC) symbol lookup is accomplished by AST navigation, + and is probably the biggest single bottleneck in performance. Perhaps + a separate symbol table would be preferable. Also, lookups could be + specialized, e.g., for declaration, for references, and perhaps a + third type for argument-related lookups. + +[NOTE]: If we are to implement symbol tables then we need to think how we + are going to inherit (extend) this tables. + +[NOTE]: Inheritance/supports graphs: these graphs need to be traversed at + several points in the back end. Currently they are rebuilt for each + use, using an n-squared algorithm. We could at least build them only + once for each interface/valuetype, perhaps even with a better + algorithm. It could be integrated into inheritance/supports error + checking at node creation time, which also be streamlined. + + @@ boris: Well, I think we should design our Syntax Tree so that + every interface/valuetype has a list (flat?) of interfaces it + inherits from/supports. + +[IDEA]: We will probably want to use factories to instantiate Syntax Tree + Nodes (STN). This will allow a concrete code generators to alter (i.e. + inherit off and extend) vanilla STNs (i.e. alternative to BE nodes + in current IDLC design). + + +Common Syntax Tree traversal Design Ideas/Decision +-------------------------------------------------- + +[IDEA] If we specify Syntax Tree traversal facility then we will be able + to specify (or even plug dynamically) Syntax Tree traversal agents + that may not only generate something but also annotate or modify + Syntax Tree. We are already using this technique for a number of + features (e.g. AMI, IDL3 extension, what else?) but all these agents + are hardwired inside TAO IDLC. If we have this facility then we will + be able to produce modular and highly extensible design. Notes: + + - Some traversal agents can change Syntax Tree so that it will be + unusable by some later traversal agents. So maybe the more + generic approach would be to produce new Syntax Tree? + + @@ jeff: Yes, say for example that we were using a common ST + representation for the IDL compiler and the IFR. We would not + want to send the extra AMI nodes to the IFR so in that case + simple modification of the ST might not be best. + +[IDEA] Need a generic name for "Syntax Tree Traversal Agents". What about + "Syntax Tree Traverser"? + + +Code Generation Stream +---------------------- + +[IDEA] Use language indentation engines for code generation (like a c-mode + in emacs). The idea is that code like this + + out << "long foo (long arg0, " << endl + << " long arg1) " << endl + << "{ " << endl + << " return arg0 + arg1; " << endl + << "} " << endl; + + will result in a generated code like this: + + namespace N + { + ... + + long foo (long arg0, + long arg1) + { + return arg0 + arg1; + } + + ... + } + + Note that no special actions were taken to ensure proper indentation. + Instead the stream's indentation engine is responsible for that. + The same mech can be used for different languages (e.g. XML). + + +Code Generators +--------------- + +[IDEA] It makes sense to establish a general concept of code generators. + "Executor Mapping Generator", "Executor Implementation Generator" + and "Skeleton Thunk Generator" would be a concrete code generators. + +[IDEA] Expression evaluation: currently the result (not the expression) + is generated, which may not always be necessary. + + @@ boris: I would say may not always be correct + + + However, for purposes of type coercion and other checking (such as + for positive integer values in string, array and sequence bounds) + evaluation must be done internally. + + @@ boris: note that evaluation is needed to only verify that things + are correct. You don't have to (shouldn't?) substitute original + (const) expression with what's been evaluated. + + + @@ jeff: it may be necessary in some cases to append 'f' or 'U' to + a generated number to avoid a C++ compiler warning. + + @@ boris: shouldn't this 'f' and 'U' be in IDL as well? + +[IDEA] I wonder if it's a good idea to use a separate pass over syntax tree + for semantic checking (e.g. type coercion, positive values for + sequence bounds). + + @@ jeff: This may hurt performance a little - more lookups - but it + will improve error reporting. + + @@ boris: As we dicussed earlier this pass could be used to do + 'semantic expansions' (e.g. calculate a flat list of interface's + children, etc). Also I don't think we should worry about speed + very much here (of course I don't say we have to be stupid ;-) + In fact if we are trading better design vs faster compilation + at this stage we should always go for better design. + + +Executor Mapping Generator +-------------------------- + + + +Executor Implementation Generator +-------------------------------- + +[IDEA]: Translate CIDL composition to C++ namespace. + + + +Skeleton Thunk Generator +------------------------ + + + + +Compiler driver +--------------- + + + +Vault +----- + +Some thoughts from Jeff that I are not directly related to CIDLC and are +rather current IDLC design defects: + +* AMI/AMH implied IDL: more can be done in the BE preprocessing pass, + hopefully eliminating a big chunk of the huge volume of AMI/AMH visitor + code. The implied IDL generated for CCM types, for example, leaves almost + nothing extra for the visitors to do. + +* Fwd decl redefinition: forward declaration nodes all initially contain a + heap-allocated dummy full-definition member, later replaced by a copy + of the full definition. This needs to be streamlined. + +* Memory leaks: inconsistent copying/passing policies make it almost + impossible to eliminate the huge number of leaks. The front end will be + more and more reused, and it may be desirable to make it executable as a + function call, in which case it will important to eliminate the leaks. + Perhaps copying of AST nodes can be eliminated with reference counting or + just with careful management, similarly for string identifiers and literals. + Destroy() methods have been put in all the node classes, and are called + recursively from the AST root at destruction time, but they are far from + doing a complete job. + +* Visitor instantiation: the huge visitor factory has already been much + reduced, and the huge enum of context state values is being reduced. + However there will still be an abundance of switch statements at nearly + every instance of visitor creation at scope nesting. We could make better + use of polymorphism to get rid of them. + +* Node narrowing: instead of the impenetrable macros we use now, we + could either generate valuetype-like downcast methods for the (C)IDL + types, or we could just use dynamic_cast. + +* Error reporting: making error messages more informative, and error recovery + could both be a lot better, as they are in most other IDL compilers. If a + recursive descent parser is used (such as Spirit), there is a simple + generic algorithm for error recovery. + + +* FE/BE node classes: if BE node classes are implemented at all, there should + be a complete separation of concerns - BE node classes should contain only + info related to code generation, and FE node classes should contain only + info related to the AST representation. As the front end becomes more + modular and reusable, this will become more and more necessary. + + @@ boris: It doesn't seem we will need two separate and parallel hierarhies. + +* Undefined fwd decls: now that we have dropped support for platforms without + namespaces, the code generated for fwd declarations not defined in the same + translation unit can be much improved, most likely by the elimination of + generated flat-name global methods, and perhaps other improvements as well. + +* Strategized code generation: many places now have either lots of + duplication, or an explosion of branching in a single visitor. Adding code + generation for use cases incrementally may give us an opportunity to + refactor and strategize it better. + +* Node generator: this class does nothing more than call 'new' and pass + unchanged the arguments it gets to the appropriate constructor - it can be + eliminated. + +* Virtual methods: there are many member functions in the IDL compiler that + are needlessly virtual. + +* Misc. leveraging: redesign of mechanisms listed above can have an effect + on other mechanisms, such as the handling of pragma prefix, typeprefix, and + reopened modules. diff --git a/CIAO/CCF/Documentation/TODO b/CIAO/CCF/Documentation/TODO new file mode 100644 index 00000000000..879602513df --- /dev/null +++ b/CIAO/CCF/Documentation/TODO @@ -0,0 +1,98 @@ +Legend: + +@@ signifies a to-be-done item + +%% signifies a done item (should be cleaned-up periodically) + +@% signifies a partially-done item + +++ signifies difficulty of an item (the more pluses the more difficult) + +------------------------------------------------------------------------ + +@@ In operation comma member function is used both for parameters and + exceptions. As a result one can get unexpected extra commas. + +@@ Make CCF buildable with MPC. + +@@ Write proper build instructions. + +@@ Can I use C++ templates instead of m4 in BuiltIn stuff? + +@@ Typedef.hpp TypeId.hpp: naming inconsistency. + +@@ Need ICE mechanism (search for abort ()) + +@@ Need evolution of semantic action error handling/reporting. + +@@+ It's a good idea to include ostream instead of iostream where I only + use ostreams. + +@@+++ Currently character stream is scanned completely before parsing. The + better approach would be scanning on demand (1). + +@@+++ IDL2::Parsing::parse () should be eliminated (or terminated if you + like ;-). This item depends on (1). + +@@++ 'using namespace' cleanup. + +@@ Replace all i++ with ++i. + +@@ It seems that SyntaxTree::Node origin in terms of file:line should be + preserved for subsequent diagnostic implemented as separate paths + (see repository id generator for example). + +@@++++ Diagnostic evolution + +@%++ XML indentation buffer + +@@+++ Introduction (injection) of names into scope + +@@++++ C Preprocessor integration (wave) + + +%% IDL feature: type id/prefix + +%% IDL feature: exception declaration + +%% IDL feature: built-in types + +%% IDL feature: struct + +%% IDL feature: enum + +%% IDL feature: factories/finders (completion) (left: finder) + +%% IDL feature: oprations (completion) (left: oneway) + +--- + +@% IDL feature: literals and constant expression (3) + +@% IDL feature: constant declaration; depends on 3 + +@% IDL feature: sequences; depends on 2,3 (left: bounded seq) + +@% IDL feature: attribute (completion) (left: exception spec) + +@% IDL feature: valuetype (4) + +@% IDL feature: event (completion); do after (4) + +@% IDL feature: literals (left FP, fixed) + +--- + +%% Inherited name lookup + +%% Revisit LEM for interconnected rules. + +@@ Maybe do something with diagnostic + +--- + +@@ IDL feature: array; depends on 2,3 + +@@ IDL feature: union + +@@ IDL feature: fixed; depends on 2,3 |