MPC: CDT6 Project Type

# CDT6 Project Type documentation

### Background/Abstract

- The CDT6 Project Type generates project files utilizable by Eclipse's CDT plugin, version 6. This is the version generally available/compatible with the Eclipse "Galileo" release. The project type generates eclipse projects from generic mpc files. These Eclipse/CDT projects can then be imported into a user's workspace and built using CDT's internal builder.
- MPC's CDT6 Project Type currently supports Linux and Windows as both host and target platforms.

### Pre-requisites

- The following software items are required and in the execution path (as well as any of their respective dependencies):
  Eclipse Galileo
    Standard download from http://www.eclipse.org/downloads.
  CDT 6.0
    This comes packaged together with Eclipse Galileo in the Eclipse IDE for C/C++ Development.
  Eclipse-compatible toolchain
    On linux platforms, this should just be the standard installation of the GNU toolchain for that linux distribution. On Windows, Eclipse uses the MinGW toolchain, available for download. Suggested tool set is Automated MinGW Installer.
  a compatible `make` tool
    This does not need to be a full-featured GNU make, but it must be in the PATH as an executable named make. On Linux, the standard GNU make suffices. On Windows, the make package from GNUWin32 is a good choice.
- The default value of 256Mb for Eclipse's Java VM heap size is insufficient for building projects the size of ACE/TAO/CIAO. A minimum of 768Mb or more is suggested. This can be done on the command line launch of eclipse, or in the `eclipse.ini` file.

### Usage

For every `project myprojname { }` in mpc files, the CDT6 project type generates a corresponding "eclipse project" directory of the form `cdt_myprojname`. The CDT6 Project Type uses Eclipse's linked resource feature to work around Eclipse's usual requirement that source files reside inside the Eclipse project directory. However, the linked resource feature also comes with restrictions; see the note for details.

#### Generic workflow

Presuming .mpc files already exist:

1. Generate projects using `-type cdt6`.
2. Import projects into an Eclipse workspace.

#### Workflow for building ACE/TAO

1. Check out a copy of ACE/TAO.
2. Configure ACE/TAO for your target(s) by setting up `config.h`.
3. Set up environment variables (ACE_ROOT, TAO_ROOT, etc.), PATH, LD_LIBRARY_PATH (or similar), etc.
4. Verify settings in `global.features` and, if changes are necessary, make appropriate changes in `default.features`.
5. Generate projects using `-type cdt6` insuring the use of `mwc.pl` from within ACE, e.g.,

   >     $ cd $TAO_ROOT
   >     $ mwc.pl -type cdt6 TAO_ACE.mwc

   `mwc.pl` will churn for awhile.
6. Suggestion: Verify that Project->Build Automatically is unchecked (has no checkmark to its immediate left). If this is left on, then the build will start as soon as the import in the next step begins, and it will build everything.
7. From within Eclipse (preferably an otherwise-empty workspace) select File->Import... and perform the following actions:
   1. Choose General->Existing Projects Into Workspace and click Next
   2. In "Select Root Directory:" text field, enter the full path to the directory above ACE, TAO, etc. (you can also use the "Browse" feature to select the directory from the GUI). For example, if you checked everything out into `/home/joedeveloper/acetao` and ACE and TAO are in a peer layout under that directory, you would enter `/home/joedeveloper/acetao` in the text field.
   3. Eclipse will scan all the subdirectories looking for existing projects; this can take a few minutes for something as large as TAO or CIAO. NOTE: If you have previously run MPC to generate CDT projects with one workspace (`.mwc` file) and then ran it later with a different workspace without removing the projects from the first generation, Eclipse will still find those projects for import. See the note on removing generated projects for information on how to do that.
   4. Be sure that the checkbox next to Copy projects into workspace is UNchecked. Copying projects into the workspace unnecessarily duplicates files, plus we have found that Eclipse can get confused with file paths sometimes (though sometimes it will work).
   5. Feel free to use Working Sets or not. You may also choose to import a subset of the discovered projects by manipulating them in the list, however, experience suggests that the list is ignorant of dependency interactions between projects, so you must manage that manually (i.e., you could import a project, but not projects upon which the first depends, and that first project would then fail to build).
   6. Click Finish to proceed with the import.
   Eclipse will now start populating the Projects pane with projects. If you didn't uncheck Build Automatically, then builds will start. Regardless, the C++ indexer will run in the background across the source of all projects.

#### Building A Project

To build a project or set of projects, select the project (or projects) in the Project pane, then select Project->Build Project. Eclipse will evaluate ALL dependencies automatically, though not necessarily quickly.

Hint: a good choice to get all of ACE/TAO built is to choose the Naming Service project.

### Multiple Platforms

Just as a project created within CDT can be set up to support multiple platforms, so too can projects generated via MPC. To the extent possible, the platforms are represented in generated projects in the same way as they are in "native" projects (though there will be some differences).

#### Generating Projects with Multiple Platform Support

Platforms are named in a list called `platforms` in the CDT6 template (much like other MPC templates). The list defaults to the platform on which `mwc.pl` is run. To generate for another platforms, or for additional platforms, you must provide `platforms` with the list of platforms to generate.

Generate projects using a similar incantation to the default (from above) using `-type cdt6` and `-value_template platform="<platform_list>"`, insuring the use of `mwc.pl` from within ACE, e.g.,

>     $ cd $TAO_ROOT
>     $ mwc.pl -type cdt6 -value_template platforms="linux cellppu" TAO_ACE.mwc

Platforms are defined as scopes in `templates/cdt6platforms.mpt`.

#### Cross-Compilation

Cross-compilation is handled the same as a platform; the target is the platform. If you want to generate for cross-compilation, the cross-compiler information must be defined in a scope (typically named for the target type) in `templates/cdt6platforms.mpt`. If a scope does not exist for the target, follow the instructions for adding a new platform.

In the example given above, `cellppu` is the name of the platform for cross-compilation.

#### Adding a New Platform

To add a new platform, particularly one for cross-compilation, it's probably easiest to start from an existing scope, e.g., `cellppu`. For cross-compilation where the cross-compiler toolchain is GNU Compiler-based, you will need to provide the names of the various executables in the toolchain in the values `as`, `ar`, `cc`, and `cxx`. And, optionally, `ccld` and/or `cxxld` if the linker used for linking C and C++ executables, respectively, is different from the respective compiler. CDT expects these to be in the path.

### Notes

1. There is no generated workspace. Eclipse's concept of workspace is very different from MPC's, and there is no way to generate a workspace. Eclipse's workspace concept doesn't permit sharing among machines or developers or even checking a workspace into version control.
2. The Eclipse "workspace" and MPC project + source must not be in the same directory hierarchy. For example, if you chose to have Eclipse store its workspace in `/home/joedeveloper/workspace`, you may not put your MPC project+source under that directory. However, putting the MPC project+source under `/home/joedeveloper/acetao` or similar, i.e., as a peer to the workspace directory, is fine.
3. CDT6 uses Eclipse's linked resource feature to work around the usual requirement that all source code reside in Eclipse project directories. These act similar to Unix symbolic links. While convenient so that a developer is not required to conform to Eclipse's directory layout, it comes at a price: the target of the link must be specified as a full path. The consequence of this restriction is that, once the CDT6 projects get generated, the source should not move in the filesystem.
4. MPC's CDT Project Generator creates directories named `cdt_*` for projects, similar to how the GNUACE generator generates makefiles of the form `GNUmakefile.*`. To remove all CDT projects from a directory hierarchy, on Linux you can use a command such as:

         $ find . -name 'cdt_*' -print | xargs rm -rf

5. Perfect hash generation using the IDL compiler is not currently working because the IDL compiler cannot find the `gperf` executable. This may be a `PATH` issue, "installation" issue, or an mpc file dependency issue. The IDL compiler works but does not generate perfect hash lookups.

Last modified: Thu Jul 22 11:14:15 CDT 2010