## Simple CIAO tutorial

Note:

- CoSMIC tools are not used in this tutorial.
- This is only a GENERAL way of building up a CIAO application and deploying it with DAnCE. The user could always change the process in his own way. For example: the IDL file content, the project structure etc.
- An CCM application may consist of several components, deployed on several (hardware) nodes, which work together as one big application.
- To download the code of this example please refer to the SVN repository at `$CIAO_ROOT/examples/Hello`.

## Example Description

This Hello example is contructed in the following ways:

1. There are 2 components in the application: Sender and Receiver
2. The Sender will send out the timeout event to the Receiver.
3. Upon receiving the timeout event, the Receiver will go and fetch data from the Sender.
4. The user could deploy multiple instances of the Receiver without changing any C++/idl source code.

## Code generation

Note that an user only need to write the IDL files. All the rest of the files can be generated. The following code generators are used throughout this example:

- `$CIAO_ROOT/bin/generate_component_mpc.pl`
  This perl script is able to generate MPC files out of a single name. MPC is a utility we use to generate makefiles or VC project/solution files for all ACE, TAO and CIAO libraries and executables.
- `$ACE_ROOT/bin/tao_idl` Besides all the stub and skeleton code, the TAO IDL compiler is also suitable to generate the so called executor files. An executor C++ code file contains the business logic the user need to write. Since this should be deployable by the DAnCE framework, there're some restriction to this code. The TAO IDL compiler takes care of that.
- `$ACE_ROOT/bin/mwc.pl` This script will generate VS solutions and/or GNU makefiles out of the generated MPC files.

All these generators will be handled throughout this tutorial.
If there's a ccm_noevent entry in your default.features (location `$ACE_ROOT/bin/MakeProjectCreator/config/`), make sure it's set to 0 (nil)!

## Step-By-Step

### Hello_Base

1. Write an IDL file (`Hello_Base.idl`) which contains all the interfaces and events common to all the components. The reason we do this is because the generated lib of this idl file will be linked in by all the components in the application. To reduce the size of the component lib we have to include only the necesary part. In this example, we have an eventtype `timeout` and an interface `ReadMessage`, which are used by both the Sender and the Receiver, so we put both of them in Hello_Base.idl.
2. Look at the `Hello_Base.mpc` file to get an idea how the Hello_Base_stub and Hello_Base_svnt projects are organized.
   There's a utility in $CIAO_ROOT/bin, called generate_component_mpc. This a perl script which is able to generate a complete mpc file based on a given name. The commandline used to generate `Hello_Base.mpc` is:
   `$CIAO_ROOT/bin/generate_component_mpc.pl -e -n -l../lib -o../lib Hello_Base`
   Use `$CIAO_ROOT/bin/generate_component_mpc.pl --help` to get more information about this tool. See also the Quoter tutorial for more information.

### For Every Component

1. Execute :
   - `$CIAO_ROOT/bin/generate_component_mpc.pl -e -l ../lib -o ../lib -c starter -p Hello_Base Sender` in Sender directory. The `-c` option will be handled later on in the step-by-step.
   - `$CIAO_ROOT/bin/generate_component_mpc.pl -e -l ../lib -o ../lib -p Hello_Base Receiver` in Receiver directory
   Note:
   - There're different directories for `"Hello_Base", "Sender", "Receiver"` respectively.
   - All output DLL's/executable will be stored in a separate directory, called "lib".
2. Write an IDL file for every component (`Sender.idl` and `Receiver.idl`).
   Here you can put the component specific IDL definitions in this file. In this example we have a interface `trigger` specific to the Sender. Please note that the Sender component `"supports"` (IDL keyword) this interface. This interface can be used by `starter` (an IDL 2 client) to start the application.
3. There's a possibility that the TAO IDL compiler can generate a 'template' for the executor code (=business logic). Steps to generate the executor files:
   1. Backup the following files to a temporary directory:
      - Sender/Sender_exec.cpp
      - Sender/Sender_exec.h
      - Receiver/Receiver_exec.cpp
      - Receiver/Receiver_exec.h
   2. Add -Gex to the `idlflags` entry in the IDL generator projects in the MPC file, meaning
   - Project `Hello_Base_Sender_idl_gen` in Sender/Sender.mpc
   - Project `Hello_Base_Receiver_idl_gen` in Receiver/Receiver.mpc
   3. Generate GNUmakefiles / VS project files and build
   4. Remove -Gex(r) again
   5. Generate GNUmakefiles / VS project files (and build)
   Mind the last step! The TAO IDL compiler does not check whether the executor file already exists. It will overwrite the existing!
   After step 2 the following files should be overwritten:
   - Sender/Sender_exec.cpp
   - Sender/Sender_exec.h
   - Receiver/Receiver_exec.cpp
   - Receiver/Receiver_exec.h

Performing all steps could be troublesome to a new CCM user. The best way of learning this is to just do it more than once. I'll also help to read the example source code. If you are familliar with CORBA programming, it should not take too much time before you can declare yourself as a CCM programmer.

### The Entry Point

After both components are implemented we still need a small program to initialize the process. In Sender.idl there is a Sender specific interface with a single method in it created for this purpose. Hence there is a CORBA client application called `starter`. The `starter` will make a invocation on a supported interface called `trigger` on the Sender component to get the whole distributed application started. The `starter` will first obtain the Sender component object reference through the ior string supplied as a command argument. Please see the the last part of `Sender/Sender.mpc` file for details.

### Build

This example assumes that ACE/TAO/CIAO/DANCE is build. If not, please follow the instructions to build these frameworks.
Tip : Experienced users may want to use `$CIAO_ROOT/CIAO_TAO_DAnCE.mwc` to generate the needed VC project/solutions or GNU make files.
Perform the following steps to build this example:

1. Navigate to `$CIAO_ROOT/examples/Hello`
2. For windows:
   - Visual C++ 2005: execute `$ACE_ROOT/bin/mwc.pl -type vc8`
   - Visual C++ 2008: execute `$ACE_ROOT/bin/mwc.pl -type vc9`
   - Visual C++ 2010: execute `$ACE_ROOT/bin/mwc.pl -type vc10`
3. For linux:
   Execute `$ACE_ROOT/bin/mwc.pl -type gnuace`.

Build this example using Visual Studio or make.

### Assemble

Now we can step forward to build the assembly. Here we are going to build the simplest case only, which is 1 Receiver and 1 Sender. If you are interested in CIAO you could try 1 Sender with multiple Receivers. However, you need to change the Sender.idl to make it publishes timeout event instead of emits event.
Note: Creating the deployment plan descriptor is a tedious and error-prone job, you can download CoSMIC to assist you in this step.
You need to create an XML descriptor file to describe your deployment plan, which is defined in a Deployment Plan Descriptor (.cdp) (see Hello deployment plan). In this file, you need to declaratively specify how the component assembly is constructed. Specificly, you need to specify the component types, component instances, component connections, implementation artifact descriptions, and whether you want to register component instances with naming service.

### Deploy with DAnCE

Once the DeploymentPlan is ready, the apllication can be deployed, using the newly created Deployment Plan.
Next figure shows how DAnCE will handle the deployment plan.
To deploy the application, we're using perl scripts to launch the executables of which DAnCE consist. A perl script typically launches the DAnCE executables in this order:

1. Naming service (if needed).
2. A DAnCE Node Manager for each node.
3. The DAnCE Execution Manager.
4. The DAnCE Plan Launcher.

See run_test.pl for an example.
The two most important variations:

1. Deploying the application, using the naming service. See run_test.pl.
2. Deploying the application, without the use of the naming service. See run_test_without_ns.pl

When using the first option, one will need to write a cdd-file. This file dictates which nodes are available in the system and which CORBA IIOP is necessary to contact these. Click here for an example of a CDD file.

### More Features

- Running the components in the same process: see PlanLocality_SameProcess.cdp at the end of this file.
- Running the components in the different process: see PlanLocality_DifferentProcesses.cdp at the end of this file.
- Using the Health and Status interceptors. see run_test_shs.pl, shs.ciao.localityconfig, and shs.localityconfig.

Email: ciao-users@list.isis.vanderbilt.edu