
             Brutus C++ sample/test README
           Copyright (C) 2004-2008 OMC Denmark ApS.


Your rights
===========

Copying and distribution of this file, with or without 
modification, are permitted in any medium without royalty 
provided the copyright notice and this notice are preserved.
                

Introduction
============

This directory holds C++ sample/test source code for the 
Brutus framework.

Any and all code is written for clarity, not performance or 
smartness. If there is two ways to do things, the clever way 
and the obvious way, then the obvious way is chosen.

The Makefiles are written the same way, allthough there are 
most likely better and clearer ways to write the Makefiles. 

I am not exactly a GNU make guru, so there re undoubtly many 
silly and stupid mistakes in those Makefiles, but they work.
Please submit patches to fix this (hint, hint..).

Please visit <http://www.42tools.com/> for more information.


License
=======

All sample/test code is distributed under the terms the GNU 
Affero General Public License. Please see the file COPYING 
for the specifics.


External dependencies
=====================

 CORBA:
     The C++ sample/test project are written for the TAO CORBA 
     implementation. You must download and build TAO before you
     will be able to build this sample/test project. As few TAO 
     specific implementation details as possible has been used. 
     You can obtain TAO from:

        <http://deuce.doc.wustl.edu/Download.html>.

     Please see Appendix A for build instructions on GNU/Linux.

     On Fedora Core you have the option of installing pre-build
     ACE and TAO RPMs. They can be downloaded from:

        <http://dist.bonsai.com/ken/ace_tao_rpm/>

     You'll need the tao-devel RPM package with all dependences. 
     Thanks goes to Ken Sedgwick for making those RPMs available!

     The Makefiles will check for the presence of the environment
     variable ACE_ROOT and assume that you have build ACE and TAO 
     from source if defined.

 Operating system:
     All of the projects has been verified to work under Fedora 
     Core 1, 2 and 3. It is possible and very likely that other 
     Linux distributions and UNIX like operating systems will
     work equally well as long as a recent GNU tool chain is 
     available. You will might need to make adjustments to the 
     Makefiles - YMMV.


Sub projects
============

The following sub projects lives in similar named directories 
directly under the C++ top level directory (in which you are 
reading this README):

 bresult: 
     A helper class to translate BRESULT return values into 
     strings.

 brutus_utils:
     Various Brutus specific helper functions.

 client:
     Source code for the sample/test executable lives here.

 config:
     A helper class that parses the client configuration file.

 init_orb:
     A helper class to call ORB_init() with the correct command 
     line arguments.

 proptags:
     A helper class to translate property tags and types into 
     strings.

 servant_impl:
     Servant implementations.

 servant_activator:
     Servant Activator implementation.


How to build
============

Simply issue "make stubs && make" in the C++ top level directory. 

"make stubs" will rebuild all of the IDL files. The client stubs 
and server skeleton objects will also be build by this target. 

The client stub objects are all linked into the client executable, 
to make it as easy as possible to add new functionallity without
Makefile modifications.

There are individual Makefiles in all sub directories.

There is currently no mechanism in the "client" Makefile to detect
modified source files on which the client executable depends. You 
must rebuild the object files manually for all modified external 
source files. A patch to rectify this obvious limitation will be 
very welcome.


Make targets
============

stubs:      All IDL files are recompiled. Client stub and server 
            skeleton objects are build from the generated files.
            Depends on target "idl". 

all:        All sample code are build and linked against all client
            stub objects and those few server skeleton objects that 
            are strictly needed. It does *not* depend on target 
            "stubs". It is rather rare that the IDL files are 
            modified and it would therefore be unbearably time 
            consuming and burdensome to rebuild all client stubs 
            and server skeletons for each "make" or "make all". 
 
idl:        All IDL files are recompiled.

clean:      Will run "make clean" in all sub directories.

clean_idl:  Will remove all generated files in the IDL output 
            directory including object files.

very_clean: No actions on its own. Depends on "clean" and 
            "very_clean". 


Tips and troubleshooting
========================

Please see the README for the top level sample directory. C++ 
specific questions, currently none, are answered here. Please 
report any bugs found to <bugs@42tools.com>. The sample code can
be discussed on the brutus mailing list.


-- 
  Jules Colding
  colding@42tools.com




                    *** APPENDIXES ***

Appendix A
==========

This section describes in detail how the author managed to build
TAO. TAO depends on ACE with which it is packaged if you download
the <http://deuce.doc.wustl.edu/ACE+TAO.tar.gz> package. It is 
assumed that you have access to a fairly recent GNU tool chain on 
your system. At least GNU Make 3.79.1 is required to build ACE.

You should know that there might be harmless compile errors in your
build. ACE+TAO is very well tested but the test applictions are 
known to misbehave compile-wise from time to time. Just ignore any 
compile errors for the ACE+TAO test applications.

You can get ACE+TAO from <http://deuce.doc.wustl.edu/> as a 
distribution or you can get it from anonymous CVS. I'll first 
describe how to build ACE+TAO from a distribution and then briefly
cover the steps in compiling from CVS. 

There are some optional steps in both procedures that you can execute 
if you want SSL support in ACE+TAO. You must have OpenSSL installed 
if you want to enable SSL support. Please see the OpenSSL distribution 
for installation instructions if you need to install OpenSSL from 
source. 

You can install OpenSSL on most RPM-based GNU/Linux distributions by 
installing the openssl-devel and openssl RPM packages.

These instructions assume that you are using Bash or another sh-like 
shell.


From a distribution:
--------------------

Step 1)
  Create ~work/src by issuing "mkdir -p ~/work/src". 


Step 2)
  Download http://deuce.doc.wustl.edu/ACE+TAO.tar.gz to ~/work/src.


Step 3)
  Go to ~/work/src and unpack the tar-ball:

      cd ~/work/src ; tar xzf ACE+TAO.tar.gz


Step 4)
  Add the following to ~/.bashrc:

      ACE_ROOT="$HOME/work/src/ACE_wrappers"
      export ACE_ROOT

      TAO_ROOT="$ACE_ROOT/TAO"
      export TAO_ROOT

      LD_LIBRARY_PATH="$ACE_ROOT/ace:$ACE_ROOT/lib:$LD_LIBRARY_PATH"
      export LD_LIBRARY_PATH


Step 5)
  Log out and log in again to make sure that your environment is 
  updated.


Step 6)
  Build ACE. 

  Step 6a)
    Execute (you can cut'n paste to a terminal):

	    echo '#include "config-linux.h"' > $ACE_ROOT/ace/config.h

  Step 6b)
    Execute (you can cut'n paste to a terminal):

	    echo 'include $(ACE_ROOT)/include/makeinclude/platform_linux.GNU' > $ACE_ROOT/include/makeinclude/platform_macros.GNU

  Step 6c)
    OPTIONAL - ONLY IF YOU WANT SSL SUPPORT.

    1) Execute (you can cut'n paste to a terminal):

	    echo 'ssl=1' >> $ACE_ROOT/include/makeinclude/platform_macros.GNU

    2) Execute (you can cut'n paste to a terminal):

	    echo 'ssl=1' > $ACE_ROOT/bin/MakeProjectCreator/config/default.features

    3) Execute (you can cut'n paste to a terminal):

	    cd $ACE_ROOT/ ; find . -name GNUmakefile -type f -print0 | xargs -0 -e rm -f

    4) Execute (you can cut'n paste to a terminal):

	     cd $ACE_ROOT ; $ACE_ROOT/bin/mwc.pl ACE.mwc

    5) Execute (you can cut'n paste to a terminal):

             cd $TAO_ROOT ; $ACE_ROOT/bin/mwc.pl TAO.mwc


  Step 6d)
    Go into the ACE source tree and execute make (you can cut'n paste to a terminal):

	    cd $ACE_ROOT ; make

    This will build the entire ACE distribution and can take a very long time. Now 
    is the time for a cup of coffee...


Step 7)
  Build TAO.

  Step 7a)
    Execute (you can cut'n paste to a terminal):

	    cd $TAO_ROOT ; make

    This will take a very, very long time...


Step 8)
  There is no Step 8 :-)


From anonymous CVS:
-------------------

Step 1)
  Create ~work/src by issuing "mkdir -p ~/work/src". 


Step 4)
  Add the following to ~/.bashrc:
    
      CVSROOT=:pserver:anonymous@anoncvs.ociweb.com:/cvs
      export CVSROOT

      ACE_ROOT="$HOME/work/src/ACE_wrappers"
      export ACE_ROOT

      TAO_ROOT="$ACE_ROOT/TAO"
      export TAO_ROOT

      LD_LIBRARY_PATH="$ACE_ROOT/ace:$ACE_ROOT/lib:$LD_LIBRARY_PATH"
      export LD_LIBRARY_PATH


Step 5)
  Log out and log in again to make sure that your environment is 
  updated.


Step 3)
  Log into CVS (press ENTER when prompted for a password):

      cvs login


Step 4)
  Go to ~/work/src and get the files (you can cut'n paste to a terminal):

      cd ~/work/src ; cvs -z 9 checkout ACE_wrappers ; cd $ACE_ROOT; cvs -z 9 checkout MPC


Step 6)
  Configure ACE+TAO:

  Step 6a)
    Execute (you can cut'n paste to a terminal):

	    echo '#include "config-linux.h"' > $ACE_ROOT/ace/config.h

  Step 6b)
    Execute (you can cut'n paste to a terminal):

	    echo 'include $(ACE_ROOT)/include/makeinclude/platform_linux.GNU' > $ACE_ROOT/include/makeinclude/platform_macros.GNU

  Step 6c)
    OPTIONAL - ONLY IF YOU WANT SSL SUPPORT.

    1) Execute (you can cut'n paste to a terminal):

	    echo 'ssl=1' >> $ACE_ROOT/include/makeinclude/platform_macros.GNU

    2) Execute (you can cut'n paste to a terminal):

	    echo 'ssl=1' > $ACE_ROOT/bin/MakeProjectCreator/config/default.features


  Step 6d)
    Execute (you can cut'n paste to a terminal):

             cd $TAO_ROOT ; $ACE_ROOT/bin/mwc.pl TAOACE.mwc


Step 7)
    Now execute make to build ACE and TAO in one go (you can cut'n paste to a terminal):

	    cd $TAO_ROOT ; make

    This will build the entire ACE+TAO distribution and can take a very long 
    time depending on your workstation. Now is the time for a cup of coffee...


Step 8)
    You can update from CVS and re-compile, but you must remember to re-run MPC: 

      cd $ACE_ROOT/ ; find . -name GNUmakefile -type f -print0 | xargs -0 -e rm -f ; cvs -z 9 update -d ; cd $ACE_ROOT/MPC ; cvs -z 9 update -d ; cd $TAO_ROOT ; $ACE_ROOT/bin/mwc.pl TAOACE.mwc ; make
