If you're building OpenDDS for use by Java applications, please see the file
$DDS_ROOT/java/INSTALL instead of this one.

BUILDING OpenDDS
========================

* Supported platforms:

  We have built OpenDDS on number of different platforms and compilers.  See
  $DDS_ROOT/README for a complete description of supported platforms.


* Compiling [Option A]:

  Starting with version 2.2, OpenDDS has a "configure" script to automate the
  steps described below (Option B).  This script requires Perl 5.10 or newer to
  be installed and available on the system PATH.  Perl 5.8 may be sufficient on
  Unix systems but ActiveState Perl 5.10 or newer should be used on Windows.
  To start the script simply change to the directory containing this INSTALL
  file, and run
  ./configure         (Unix)
  configure           (Windows: use a Visual Studio Command Prompt)
  Optionally add "--help" to the command line to see the advanced options
  available for this script.  The configure script will download ACE+TAO and
  configure it for your platform.  To use an existing ACE+TAO installation,
  either set the ACE_ROOT and TAO_ROOT enviornment variables or pass the --ace
  and --tao (if TAO is not at $ACE_ROOT/TAO) options to configure.
  If configure runs successfully it will end with a message about the next
  steps for compiling OpenDDS.  If it fails, you may need to follow the
  "Option B" steps below for manual configuration.


* Compiling [Option B]:

    DDS requires the TAO PortableServer and dependent libraries to build.  It
    is preferable to have a complete build of TAO's core (every library under
    $TAO_ROOT/tao) before attempting to build DDS.

  1 Build ACE and TAO.

    See the instructions in
    http://theaceorb.com/faq/index.html#HowToBuildACEandTAOonWindows
    or http://theaceorb.com/faq/index.html#HowToBuildACEandTAOonLinux,
    or the relevant sections in OCI's TAO Developer's Guide.

  2 Set the environment variables.

    Set DDS_ROOT to the location of the DDS checkout.

    Add $DDS_ROOT/bin to the PATH (on, Windows add %DDS_ROOT%\bin)

    Add $DDS_ROOT/lib to the LD_LIBRARY_PATH (or %DDS_ROOT%\lib to
    the PATH for Windows)

    Make sure that the other normal ACE/TAO environment
    variables are defined.

  4 Build

    On Linux or Solaris:
    make
    (on Solaris be sure this is GNU make, possibly using "gmake")

    On Windows:
    Load the solution of your choice into Visual Studio and build all.  There
    are a few solutions to select from:
        DDS.sln - VC71, DLLs
        DDS_Static.sln - VC71, Static libs
        DDS_vc8.sln - VC8, DLLs
        DDS_Static_vc8.sln - VC8, Static libs
        DDS_vc9.sln - VC9, DLLs
        DDS_Static_vc9.sln - VC9, Static libs
        DDS_vc10.sln - VC10, DLLs
        DDS_Static_vc10.sln - VC10, Static libs
    (Do not up-convert a VC71 solution or project to VC8/VC9)

  5 Test

    Optionally, you can run the entire OpenDDS regression test suite with one
    Perl command.
    $DDS_ROOT/bin/auto_run_tests.pl
        If you built static libraries, add "-Config STATIC" to this command.
        On Windows if you build Release mode add "-ExeSubDir Release".
        On Windows if you build static libraries add "-ExeSubDir Static_Debug"
        or "-ExeSubDir Static_Release".


* Cross Compiling:

  DDS can be built for some platforms that require compilation of code
  on a separate system than where the code will execute.

  Compilation uses the Option B method with an additional requirement of
  building the opendds_idl tool for the host system.  This requires having
  two separate builds, one for the host and one for the target.

  1 Build ACE and TAO IDL compiler for the HOST.

    This requires building the TAO host components necessary for the cross
    compilation.

    See the cross compilation instructions in $ACE_ROOT/ACE-INSTALL.html
    and $TAO_ROOT/TAO-INSTALL.html for the list of projects to build.

    See the standard build instructions in
    http://theaceorb.com/faq/index.html#HowToBuildACEandTAOonWindows
    or http://theaceorb.com/faq/index.html#HowToBuildACEandTAOonLinux,
    or the relevant sections in OCI's TAO Developer's Guide.

  2 Set the environment variables for the HOST build.

    Set DDS_ROOT to the location of the DDS checkout for the HOST build.

    Add $DDS_ROOT/bin to the PATH (on, Windows add %DDS_ROOT%\bin)

    Add $DDS_ROOT/lib to the LD_LIBRARY_PATH (or %DDS_ROOT%\lib to
    the PATH for Windows)

    Make sure that the other normal ACE/TAO environment
    variables are defined using the HOST's build.

  3 Build opendds_idl executable for the HOST build.

    On Linux or Solaris:
    make -C dds/idl
    (on Solaris be sure this is GNU make, possibly using "gmake")

    On Windows:
    Load the solution of your choice into Visual Studio and build the
    opendds_idl project.
    There are a few solutions to select from:
        DDS.sln - VC71, DLLs
        DDS_Static.sln - VC71, Static libs
        DDS_vc8.sln - VC8, DLLs
        DDS_Static_vc8.sln - VC8, Static libs
        DDS_vc9.sln - VC9, DLLs
        DDS_Static_vc9.sln - VC9, Static libs
    (Do not up-convert a VC71 solution or project to VC8/VC9)

  4 Build ACE and TAO for the TARGET.

    Using the cross compilation instructions in 
    $ACE_ROOT/ACE-INSTALL.html and $TAO_ROOT/TAO-INSTALL.html set the
    appropriate HOST compiled tools.

    Depending on the tool and compiler setup, it may require
    regenerating Makefile and Solution files.

    For regenerating project files, see the build instructions in
    http://theaceorb.com/faq/index.html#HowToBuildACEandTAOonWindows
    or http://theaceorb.com/faq/index.html#HowToBuildACEandTAOonLinux,
    or the relevant sections in OCI's TAO Developer's Guide.

  5 Set the environment variables for the TARGET.

    Set DDS_ROOT to the location of the DDS checkout for the TARGET.

    Add $DDS_ROOT/bin to the PATH (on, Windows add %DDS_ROOT%\bin)

    Add $DDS_ROOT/lib to the LD_LIBRARY_PATH (or %DDS_ROOT%\lib to
    the PATH for Windows)

    Make sure that the other normal ACE/TAO environment
    variables are defined for the TARGET's build.

  6 Configure the TARGET build to use the HOST built opendds_idl tool

    Either copy or link the opendds_idl executable from the HOST
    build's bin/ directory to the TARGET build's bin/ directory.

  7 Build for the HOST

    Depending on the compiler and instructions to use it,
    compilation may consist of using existing Makefiles with the 
    make command or regeneration of project files may be necessary.
    See the MPC documentation http://www.ociweb.com/products/MPC

  8 Test

    Presently, there is no automated testing setup for deployed platforms.
    Any testing has to be done manually.


* Getting Started building your own applications:

  See the OpenDDS Developer's Guide:
      http://download.ociweb.com/OpenDDS/OpenDDS-latest.pdf
  Run the Developer's Guide Example program:
  Unix                                            Windows
  ----                                            -------
  cd $DDS_ROOT/DevGuideExamples/DCPS/Messenger    cd %DDS_ROOT%\DevGuideExam...
  ./run_test.pl                                   perl run_test.pl
  [ see the notes in step 5 "Test", above, for options to run_test.pl ]

  The Perl script will start 3 processes, the DCPSInfoRepo, one publisher, and
  one subscriber.  Note that the command lines used to spawn these processes
  are echoed back to standard output.  The options and config files used here
  are helpful starting points for developing and running your own OpenDDS
  applcations.


* Note:

 [ This note does not apply to using the "configure" script because it will   ]
 [ generate the makefiles or project files.                                   ]
 The instructions above assume you have obtained OpenDDS as a released version
 from the website.  If you have obtained OpenDDS from subversion, you will need
 to generate makefiles or Visual Studio project files first.
 Make sure your environment variables are set, including MPC_ROOT.

     On Linux or Solaris:
      cd $DDS_ROOT
      perl $ACE_ROOT/bin/mwc.pl -type gnuace DDS.mwc

     On Windows:
      cd %DDS_ROOT%
      perl %ACE_ROOT%\bin\mwc.pl -type [CompilerType] DDS.mwc
        "CompilerTypes" tested include vc71, vc8, vc9, vc10, and nmake

* Platform specific notes:

 QNX:
  QNX requires the MPC feature "link_codecfactory=1" be present during makefile
  generation for both TAO and OpenDDS.  Technically, this is part of Step #1
  above because it's required in order to have a functioning TAO build.  Use
  the instructions under "Note:" above to re-generate the makefiles after
  adding the line "link_codecfactory=1" to the end of
  $ACE_ROOT/bin/MakeProjectCreator/config/default.features.

 Android:
  Currently there is only support for building with Standalone compiler
  toolchain of the Android Native Development Kit.  The standard NDK compiler
  is not identified as supporting exceptions or RTTI, as of NDK r5c.
  Compilation on Windows can fail due to cygwin/Windows not differentiating
  between the ACE file Signal.h and the system file signal.h.
