[omniORB] COS infrastructure

[Robert E. Gruber]

The question about the omg.org pragma for COS interfaces
reminded me to send this announcement.  (The answer is yes the
prefix should be there.)  -- Bob

----------

There is now a good infrastructure in place for people to conveniently
write clients of various COS services and also for people to provide
new implementations of COS services.

Here is an overview of this infrastructure.  Sai-Lai is also putting
this info on an omniORB web page.

OVERVIEW
--------

In omniORB 3.0.2 (and beyond :->) there are idl files for a number of COS
interfaces under

    <omni_top>/idl/COS/

The corresponding stubs+skeletons have been compiled and linked into two
libraries, COS and COSBOA, containing POA and BOA stubs and skeletons,
respectively.

The corresponding POA .hh files have been placed at

    <omni_top>/include/COS

while the BOA .hh files have been placed at

    <omni_top>/include/COS/BOA

WRITING CLIENTS
---------------

If you have downloaded omniNotify you can look at the example clients
provided with that release.

As another example, you should be able to write a POA client of any CosEvent
event service by putting

#include "COS/CosEventComm.hh"
#include "COS/CosEventChannelAdmin.hh"

at the top of the client program and linking your program against the COS
library.  If you write dir.mk files in the style of other omniORB dir.mk
files, you can include cos.mk which provides rules to help with compiling
and linking against the COS libraries.

cos.mk is found at <omni_top>/mk/cos.mk

The comments from cos.mk are repeated here:

# COS Stub Library
#
# Provide the following make variables to use the library
#     COS_LIB, COS_LIB_DEPEND
#   e.g.
#   foo: foo.o $(COS_LIB_DEPEND) $(CORBA_LIB_DEPEND)
#          @(libs="$(COS_LIB) $(CORBA_LIB)"; $(CXXExecutable))
#
#     COS_LIB_NODYN, COS_LIB_NODYN_DEPEND to be used when Any and Typecodes
#     of the types defined in the library are not required.
#   e.g.
#   foo: foo.o $(COS_LIB_NODYN_DEPEND) $(CORBA_LIB_DEPEND)
#          @(libs="$(COS_LIB_NODYN) $(CORBA_LIB)"; $(CXXExecutable))
#
# To use the COS idls in application IDLs
#   DIR_IDLFLAGS += $(COS_IDLFLAGS)
#
# To compile the application stubs:
#   DIR_CPPFLAGS += $(COS_CPPFLAGS)


IMPLEMENTING COS SERVICES
-------------------------

The source for COS services should live under directory

    <omni_top>/src/services

Thus, omniNotify source is placed at

    <omni_top>/src/services/omniNotify

We want to encourage others to release COS services that also install under
the src/services directory, and to have these services build against the COS
or COSBOA libraries.

[[If we could say that omniEvents is released this way that would be great]]

CHANGING THE INTERFACES COMPILED INTO THE LIBRARIES
---------------------------------------------------

The COS and COSBOA libraries are built using the rules in 3 .mk files in
directory

  <omni_top>/src/services/mklib

The 3 files are:

cosinterfaces.mk  :
    Defines all of the different sets of interfaces that you
    *might* want to include in the COS/COSBOA libraries.
    Should only be changed to add new COS interfaces.

libdefs.mk :
    Selects which of the sets of interfaces to actually include
    in the COS/COSBOA libraries (see COS_INTERFACES definition).
    The default is the set of interfaces required for
    CosEvents an CosNotification.
    This is the appropriate file to change to add/remove
    interfaces from the libraries.

dir.mk :
    The rules for building static and dynamic COS/COSBOA libraries.
    Should not be changed.