omniORB2 on Win32 platforms.
                        ============================

This file contains information on installing, building, and using omniORB2
on Win32 (Windows NT and Windows '95) platforms.

If you are upgrading from 2.2.0, do not miss the important information about
omniNames at the end of this note.

OmniORB 2.5.0 has been tested with the following software configuration:

- Operating System  : Windows NT 4.0
- Architecture      : x86
- Compiler          : Visual C++ 4.2, Visual C++ 5.0

The omniORB2 binaries, when compiled using VC++ 5.0 on Windows NT, will 
execute on Windows '95 machines and vice-versa.

omniORB2 hasn't been built or tested on Alpha Windows NT, but this should
be possible. (Please e-mail omniorb@orl.co.uk if you do this).


Roadmap
=======

When the omniORB2 distribution is unpacked, the following are created:

<Top-Level Directory>\                     : Directory where distribution was 
                                             unpacked

<Top-Level Directory>\doc\                 : omniORB2 Documentation

<Top-Level Directory>\include\             : Include files
<Top-Level Directory>\include\omniORB2\    : Include files for ORB run-time 
                                             library
<Top-Level Directory>\include\omnithread.h : Main omnithread include file
<Top-Level Directory>\include\omnithread\  : Include files for thread library

<Top-Level Directory>\src\                 : Source files
<Top-Level Directory>\src\lib\omniORB2\    : Source files for ORB run-time 
                                             library
<Top-Level Directory>\src\lib\omnithread\  : Source files for thread library
<Top-Level Directory>\src\tool\omniidl2\   : Source files for IDL Compiler
<Top-Level Directory>\src\appl\omniNames\  : Source files for COS Naming 
                                             Service
<Top-Level Directory>\src\appl\utils\      : Source files for utilities
<Top-Level Directory>\src\examples\        : Source for example programs


Installation
============

If you downloaded the Win32 binary distribution of omniORB2, ready-built
binaries are provided. You are ready to go.

The executables and DLLs are in <Top-Level Directory>\bin\x86_win32.
The libraries are in            <Top-Level Directory>\lib\x86_win32.

You *should* set up your PATH environment to include 
   <Top-Level Directory>\bin\x86_win32
otherwise the DLLs will not be picked up when omniORB programs are run.

If you have the source-only distribution, you will need to build omniORB2. 
Please read the  "Building omniORB2 from the source files" section, below. 
(If you want the  Win32 binary distribution, but don't have it, you can 
download it from the ORL web site at 
http://www.orl.co.uk/omniORB/omniORB.html).

Configure the naming service
=============================
 
  If you are upgrading from 2.2.0, please read the important information about
  omniNames at the end of this note.

  You have to configure the omniORB2 runtime and the naming service,
  consult the user guides in ./doc for details. For a quick start, follow
  these steps:

    o Make sure that <Top-Level Directory>\bin\x86_win32 is in your
      PATH environment.

    o Set the environment variable OMNINAMES_LOGDIR to a directory where
      the naming service omniNames can store its data. For example:
          set OMNINAMES_LOGDIR=C:\OMNINAMES

    o Start omniNames. The binary is in <Install Location>\bin\win32_x86. 
      For example:
         omniNames -start 12345
      Notice that you have to give as a parameter to the option -start
      the TCP/IP port number omniNames will use to receive IIOP requests.

    o omniNames writes the stringified object reference for its root context 
      on standard error.
      Copy the IOR. (including the IOR: prefix).

    o Start the tool REGEDT32.EXE (on NT) or REGEDIT.EXE (on Windows '95). 
      Select the key  HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0 (or create
      it if it doesn't exist). Add a string value (known as a REG_SZ data type
      when using REGEDT32) called NAMESERVICE  , and paste the IOR in to the 
      value field associated with it.


Compiling the examples with nmake
=================================

Once the installation is completed. You can try compiling and running the
examples in <Top-Level Directory>\src\examples.

Just do the following:

  cd <Top-Level Directory>\src\examples
  nmake /f dir.mak

Have a look at the dir.mak file in <Top-Level Directory>\src\examples, it
should give you some idea about the compiler flags and libraries to compile
and link omniORB2 programs.

Building Projects using omniORB2
================================

Before building anything (or running the examples), you should refer to the 
omniORB2 documentation. In particular, you must add the (stringified) object 
reference of the naming service to the registry (in the (string) value 
NAMESERVICE, under the key HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0). 
You should use the tool REGEDT32.EXE on Windows NT, or REGEDIT.EXE on 
Windows '95. (See above for quickstart instructions on starting the Naming
Service).

Note that the instructions below are for Microsoft Visual C++ 4.2, using 
Microsoft Developer Studio. If you are using Microsoft Visual C++ 5.0, the 
setup will be slightly different. The instructions are for using the DLL
versions of omniORB2 and omnithread.

a) Add the stub (SK.cpp) files generated by the IDL compiler to the project 
   (Insert->"Files into Project")

b) Set up the search paths for include and library files: 

   1. Under Tools->Options, select the Directories tab.
   2. In the "Show directories for" box, select "Include files".
   3. Add the directory where you installed the omniORB2 include files to the 
       list (this is <Top-Level Directory>\include).
   4. In the "Show directories for" box, select "Library files".
   5. Add the directory where you installed the omniORB2 library files to the
       list (this is <Top-Level Directory\lib\x86_win32).
    
c) Set up macros and libraries:

    1. Under Build->Settings, select the "C/C++" tab.
    2. In the "Category" box, select "C++ Language". Tick the 
        "Enable exception handling" box.
    3. In the "Category" box, select "Code Generation". In the 
        "Use run-time library" box, select "Multithreaded DLL".
    4. **This is an import step.** 
       In the "Category" box, select "Preprocessor". In the
        "Preprocessor" box, add the macros __WIN32__,__x86__.
       If this is NT 4.0, add the macros __NT__ and __OSVERSION__=4 as well.
    
    5. Select the "Link" tab.
    6. In the "Category" box, select "Input". In the "Object/library modules"
       box, add the following libraries: wsock32.lib, advapi32.lib, 
       omniORB24_rt.lib, omnithread2_rt.lib

   If you are building a debug executable, the debug version of the libraries:
   omniORB24_rtd.lib and omnithread2_rtd.lib should be used.

d) Your project is now set up, and you can build it.


If you want to use the static versions of omniORB2 and omnithread, you must
add the macro _WINSTATIC (see step (c) 4, above), and replace the libraries
omniORB24_rt.lib and omnithread2_rt.lib with omniORB2.lib and omnithread.lib 
(see step (c) 6, above).


Important Change to omniNames for users upgrading from version 2.2.0
====================================================================

Since release 2.4.0, the naming service has used the prefix pragma "omg.org" in
its IDL.

Unfortunately, this is not compatible on-the-wire with clients that are
linked with the old library, i.e. any programs linked before version 2.4.0
was released.

The implications of this change are as follows:

a) omniNames built in this release *CANNOT* read the data file of the version
   2.2.0 omniNames. A new instance must be started from scratch. If you start
   omniNames and tell it to use the old data file, it will certainly crash.

   Possible migration path:
     At, we are running the old and the new omniNames in parallel.
     The new instance is setup to run on a different port. Also the
     new tree is built to read by default a different configuration file:
     (/project/omni/var/omniORB_NEW.cfg instead of 
     /project/omni/var/omniORB.cfg) so that a client will pick up the
     IOR of the old or the new omniNames depending on whether it is compiled
     with the old or the new library. When all our services have been
     recompiled, the old omniNames will be withdrawn.


b) If you want to continue to use the old omniNames, you can undo this
   change with the following steps:
     1. Edit <Top directory>\src\lib\omniORB2\Naming.idl and remove the 
        #pragma prefix "omg.org" line.
     2. Do the same to <Top directory>\idl\Naming.idl.
     3. Remove <Top directory>\include\omniORB2\Naming.hh.
     4. Rebuild everything. You should do a make veryclean at the
        top of <Top directory>\src to make sure that the naming service stubs 
        are regenerated.



Known Problems
==============

When compiling the stub files generated by omniidl2, you may come across
some bugs in Microsoft Visual C++ 4.2 (not fixed in Microsoft Visual C++
5.0). The bugs are to do with the handling of nested classes. You may
come across these bugs if you use modules in your IDL files, and in certain
other circumstances.

Unlike 2.2.0, this release generates stub code that works around most of
the MS VC++ bugs. However, it is not possible to avoid the bugs in all
cases. In particular, the following sample IDL will fail to compile:

// IDL

module A {
  struct B {
    long x;
  };
  enum C { C_1, C_2 };
  module D {
     struct B {
       float y;
     };
     // The stub for struct E would fail to compile
     struct E {
       A::B e1;
       B    e2;
  };
};



Building omniORB2 from the source files
=======================================

 OmniORB2 should be compiled using Visual C++ 4.2 or Visual C++ 5.0.


 A. Pre-requisites
    --------------

    Starting from this release, the omniORB2 source tree requires the 
    gnu-win32 utilities from Cygnus Solutions to build.

    The full distribution is freely available at:

       ftp://ftp.cygnus.com/pub/gnu-win32/latest

    or in UK

       ftp://src.doc.ic.ac.uk/public/gnu/cygnus/gnu-win32/latest


    The toolkit is big and you don't need all of it to compile
    omniORB2. Alternatively, you can download a cutdown version from:

       ftp://ftp.orl.co.uk/pub/omniORB/gnu-win32-lite.zip

    The utilities in this version are all you need to build omniORB2.

    Assume that you have downloaded the toolkit and have unpacked/installed
    it in some sensible subdirectory, say C:\gnuwin32, you then have to go
    through the following checklist:

      1. In a command prompt window, make sure that you have the environment
         variables and path setup properly to use MS Visual C++ (4.2/5.0).

         For instance, I have MS VC++ installed in C:\Program Files\DevStudio.
         The following environment variables should be set to:

         LIB=C:\Progra~1\DevStudio\VC\lib
        INCLUDE=C:\Progra~1\DevStudio\VC\include
        Path=<otherpaths>;C:\Progra~1\DevStudio\VC\bin;C:\Progra~1\DevStudio\SharedIDE\bin;<otherpaths>

      2. If you have unpacked gnu-win32-lite.zip in C:\gnuwin32, add
         C:\gnuwin32\bin to your Path environment variable. 

        Warning: If you have installed posix utilities from the Windows 
            resource kits, make sure that C:\gnuwin32 is searched before the 
            directory containing these utilities.

       If you have installed the full gnu-win32 toolkit, just follow its
       installation instructions and you can skip 3.

      3. Now you have to run a small script *once* to setup in your registry 
         the necessary 'mount' points. Basically, it tells the gnu-win32 
         runtime how to translate a path such as /bin/sh to the real path 
         name Win32  (e.g. C:\gnuwin32\bin\sh.exe) understands.

         Just execute this command in a command prompt window:
  
            C:\gnuwin32\bin\checkmounts C:\gnuwin32

        If all goes well, this is what you see:

            C:\> C:\gnuwin32\bin\checkmounts C:\gnuwin32
            no /bin/sh.exe, mounting c:\gnuwin32\bin as /bin
            Completed successfully.

      4. Now you are ready. You can now build the distribution by following 
         the instructions below.


  B. Choose the right platform configuration file
     --------------------------------------------

      Edit <top>\config\config.mk to select one of the following:

     platform = x86_nt_3.5
     platform = x86_nt_4.0
     platform = x86_win95

 
  C. Building and installing
     --------------------------

     Go into the directory <top>\src and type 'make export'. If all
     goes well:
        1. The executables and DLLs will be installed into
               <top>\bin\x86_win32\
        2. The libraries will be installed into
               <top>\lib\x86_win32\


Mailing List
============

There is a mailing list for discussing the use and development of
omniORB2. See README.FIRST for details on subscribing.