NOTE: Please read the file ../INSTALL.WINDOWS first!

INTRODUCTION
============

This README discusses the requirements for building ORBacus under
Microsoft Windows NT and compiling Windows applications that use
ORBacus.  A short troubleshooting section is included at the bottom of
this file.

Building ORBacus
~~~~~~~~~~~~~~~~

Supported Windows compilers for ORBacus include Visual C++ 5.0 and
6.0.  It is always a good idea to have the most recent service pack
installed for your development environment.  Building ORBacus requires
approximately 150 MB of free disk space, but may require more
depending on compiler and linker settings.

Building Debug and Optimized versions of ORBacus
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For your convenience, ORBacus allows you to easily change build settings
from developer debug builds to optimized release builds. The main
Make.rules.mak file in the distribution's config directory contains
an option "OPTIMIZE" that is disabled by default.  To enable
optimizations and disable debug information, simply remove the comment
from the beginning of the line and rebuild ORBacus.  Alternatively, you
can specify the appropriate settings on the command line, eg.

          nmake /f Makefile.mak OPTIMIZE=yes

Building ORBacus Windows Applications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Building a MS-Windows application that uses ORBacus is a
straightforward process.  It is required that the ORBacus libraries
are built with compiler and linker settings that are compatible with
the settings used when compiling your Windows applications.

Most problems in building a Windows application revolve around the /M
compiler switch.  This switch controls which run-time library names
are embedded in the object files, and consequently which libraries are
used during linking.  Function references may also be modified
depending on the switch.  For example, specifying /MD or /MDd will
cause references to functions to be prefixed with __imp_func.
Attempts to mix and match compiler settings and libraries can cause
link errors and even if successful, may produce undefined run-time
behavior.

Changing run-time library settings for ORBacus under Win32
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Changing compiler settings for building ORBacus is very easy and only
needs to be done in one place.  Locate the file Make.rules.mak in the
config directory off the source distributions root directory and open
it in your favorite editor, e.g.:

    cd \src\ooc
    unzip OB-3.1.2.zip
    cd OB-3.1.2\config
    edit Make.rules.mak

Now you need to locate the line that begins with CXXFLAGS. It probably
looks something like:

    CXXFLAGS     = /nologo /MD /W3 /GX $(CXX_OPTFLAGS) 

The only setting you need to change is the /MD switch, which you can
change to one of:

    /MD - Multithreaded dynamically-linked library *

    /MDd- Multithreaded dynamically-linked library, debug version *

    /MT - Multithreaded statically-linked library **

    /MTd - Multithreaded statically-linked library, debug version **

    /ML - Single thread statically-linked ***

    /MLd - Single thread statically-linked, debug version ***

  * You can use the multithreaded libraries even if you compile a
    non-multithreaded version of ORBacus, i.e., if you don't compile
    with JThreads/C++.

 ** Statically linked versions of the libraries and utilities will
    be much larger than dynamically linked ones, but will not be
    vulnerable to different versions of runtime libraries.

*** If you want to use JThreads/C++ to create multithreaded programs,
    use of single threaded libraries is not recommended.

After changing the compiler switches, you should run "nmake /f
makefile.mak clean" from the distribution's root directory to remove
settings and artifacts that may interfere with your build.

If you feel that you will have to rebuild ORBacus too frequently you
can give the "Debug" versions of ORBacus different names than the
standard ones, eg. OBd.lib, JTCd.lib and OB.lib and JTC.lib.

Using /MT, /ML, /MTd or /MLd when building ORBacus with the DLL 
variable in Make.rules.mak set to "yes" will produce unusable 
executables (idl, hidl, etc.)  These flags cause the ORBacus DLL
to link with the static run-time library.  The effect is that the
DLL will have its own run-time heap, causing fatal memory management
problems.  If you wish to produce and use the ORBacus DLL, you must
use /MD or /MDd to build ORBacus and your applications.

Changing the run-time library settings in Developer Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Changing the /M switch in Developer Studio is done through a dialog
box.  To open this dialog box click on the "Project" menu and select
the "Settings" option.  To change the compiler switch click on the
"C/C++" tab and select "Code Generation" from the "Category" drop-down
list.  The "Use run-time library" drop-down list is used to change the
compiler switch.  By looking at the string in the "Project Options"
edit box you can see what the switch value is for the drop-down list
selection.

Single-Threaded = /ML
Multithreaded = /MT
Multithreaded DLL = /MD
Debug Single-Threaded = /MLd
Debug Multithreaded = /MTd
Debug Multithreaded DLL = /MDd

As changing this setting in some cases will cause many link errors and
undesired results, it is sometimes better to leave Developer Studio
defaults alone and rebuild ORBacus with a matching /M switch.

Other required compiler and linker settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

ORBacus makes extensive use of exceptions and Run-Time Type
Information (RTTI), and so requires the /GX and /GR options be enabled
when compiling ORBacus or applications that use ORBacus.  The setting
can be found in Microsoft Developer Studio in the "Project Settings"
dialog box.  Click on the "C/C++" tab and select "C++ Language" in the
"Category" drop-down list.  To enable exception handling, make sure
the "Enable exception handling" check box has a check in it.  RTTI is
enabled by checking the "Enable Run-Time Type Information (RTTI)" box
right under the "Enable exception handling" check box.

ORBacus is a cross-platform product and relies on the preprocessor
identifier WIN32 being defined in order to configure itself at build
time.  Normally this will already be defined in a Developer Studio
created project.

ORBacus uses the Winsock libraries under Windows so it is necessary to
link wsock32.lib in your projects.  ORBacus also has support for NT
Services and uses the Registry management API functions, so it is 
necessary to link advapi32.lib with you projects.  If you are using 
Developer Studio, Winsock support is an option in some of the Wizards 
and is often included by default.

Most importantly, you will need to include the ORBacus libraries in
your project's linker settings.  The ORBacus libraries are ob.lib, and
if you compiled ORBacus with JThreads/C++ for multithreading support,
jtc.lib.  On the command line you add the location of the libraries
using the /LIBPATH: command line argument and the names of the
libraries, ob.lib and jtc.lib.  To add ob.lib in the Developer Studio
environment, open the "Project Settings" dialog box and click on the
"Link" tab.  Select "Input" from the "Category" drop-down list and add
"ob.lib jtc.lib" to the list of libraries in the "Object/library
modules" box.  Please note that if you did NOT build ORBacus with
JThreads/C++ and if your application does not use JThreads/C++ then
you can safely omit jtc.lib.

ORBacus and Microsoft Developer Studio - A Concrete Example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As a Windows developer and Microsoft Visual C++ user, it is likely that
the Developer Studio IDE is the environment that you usually create, build
and debug applications in.  While integrating ORBacus into your build 
environment is easy, it is instructive to go through an example.  Lets
consider the "Hello World" example found in the ORBacus ob/demo/hello
directory.  For this example we will build the client part of the demo
only. 

- Copy Hello.idl and Client.cpp from ob\demo\hello into c:\myhello. 
  (for the purpose of this demo we will use c:\myhello, this can 
   be a different directory in practice)

- Change directories to c:\myhello.
  eg:
     c:\
     cd \myhello

- Create the Hello stub source files (Hello.cpp Hello.h) by calling 
  "idl Hello.idl" 

- Start the Developer Studio IDE

- Select File/New from the Developer Studio menu.  This opens a dialog box
  with a list of Project types.

- Select "Win32 Console Application" from the list of project types.

- Specify c:\ as the directory and myhello as the project name.

- Specify "An Empty Project".

- Add Hello.cpp, Hello.h and Client.cpp to your new project.

- Open the project settings dialog and select the "C++" tab and
  the "Code Generation" settings.

- Select "Multithreaded DLL" from the "use run-time library:" options.

- Open the Link options by clicking on the "Link" tab.  

- Add ob.lib, advapi32.lib and wsock32.lib to the "Object/Library modules" 
  box.

- Select "Tools/Options" from the menu to open the "Options" dialog box.

- Add "c:\myhello" and "c:\ooc\include" to the "Include files" directories.

- Add "c:\ooc\lib" to the "Library files" directories.

- Build your project.

This example assumes that you built and installed ORBacus with the 
distribution defaults.  If you change the default settings that ORBacus 
uses when installed, then you need to modify the project settings 
accordingly.

MFC applications in Microsoft Developer Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Win32 Debug and Win32 Release -

MFC applications that are generated automatically using the MFC
AppWizard have two groups of setting configurations: "Win32 Debug" and
"Win32 Release".  The important thing to realize is that by changing
the configuration from "Win32 Debug" to "Win32 Release" or vice versa
changes a lot of settings, including which Windows and MFC libraries
are linked with your application.  There are two principal differences
that affect compilation and linking with ORBacus Windows application,
the /M switch and the _DEBUG define.  In the Win32 Debug
configuration, the /M switch will be one of /MLd, /MDd or /MTd and
there will be a /D _DEBUG compiler switch defining _DEBUG.  This will
cause debug versions of libraries to be linked with your application
and debugging code to be conditionally compiled in as well.  In the
Win32 Release configuration, the /M switch becomes one of /ML, /MD or
/MT and NDEBUG will be defined instead of _DEBUG.  This results in a
whole different set of libraries being linked with your application as
well as conditional debug code being omitted from your program.

You can find out and change which configuration is currently active
for your project by selecting the "Build|Set Active Configuration..."
menu item.

So what does this have to do with ORBacus and your application?  By
default ORBacus only builds one version of a library.  In order to
successfully link your application with the ORBacus library you will
need to make sure it was built with flags compatible with your
application.  In essence this means that if you are building the
"Win32 Debug" version of your MFC application and dynamically linking
with MFC then you need to configure ORBacus to build with the /MDd
option.  If you are building "Win32 Release" and dynamically linking
with MFC then you need to configure ORBacus to build with the /MD
switch.

Pretty simple.  Remember to add the ORBacus libraries to your linker
settings! (see "Other required compiler and linker settings" in this
file)

ATL Controls in Developer Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ATL COM AppWizard sets up a series of configurations similar to
the MFC AppWizard, but there are a lot more of them.  The guidelines
for MFC applications apply here as well.  You will almost certainly
have to add wsock32.lib to the list of libraries being linked in as
well.

You may notice that all of the configurations use either /MT or /MTd.
This means that you will have to create a statically linked version of
ORBacus if you want to build controls that use it.

MFC ActiveX Controls in Developer Studio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The MFC ActiveX ControlWizard sets up a series of configurations
similar to the MFC AppWizard with a couple of additional ones for
Unicode support.  The guidelines for MFC applications apply here as
well.

You may notice that all of the configurations use either /MD or /MDd.
This means that you will have to create a dynamically linked version
of ORBacus.  You can change your control to statically link with MFC,
but this may cause some problems that are beyond the scope of this
README.

Troubleshooting
~~~~~~~~~~~~~~~

- If, while linking, you get a slew of unresolved symbols that look like
  this:

    ob.lib(IIOPInit.obj) : error LNK2001: unresolved external symbol 
    _inet_ntoa@4
    ob.lib(OCI_IIOP_impl.obj) : error LNK2001: unresolved external symbol 
    _inet_ntoa@4
    ob.lib(IIOPInit.obj) : error LNK2001: unresolved external symbol 
    _WSAGetLastError@0

  It means that wsock32.lib must be added to the list of linked
  libraries.

- If the linker displays a warning like:
  
    LINK : warning LNK4098: defaultlib "MSVCRTD" conflicts with use of other 
    libs; use /NODEFAULTLIB:library

  You probably have some object files lying around that were compiled
  with a different setting.  Delete the object files being linked
  manually or by running "nmake /f makefile.mak clean", and rebuild.

- If the linker displays an error such as:

    LINK : fatal error LNK1104: cannot open file "jtc.lib"

  Then you probably have something wrong in your 
  "Project Settings|Link|Input|Additional library path" setting.
  Check the setting then confirm that the missing library is where you
  indicated it would be.

- If when building ORBacus you get warnings such as:
  
    TypeCode.cpp(2558) : warning C4273: 'CORBA__tc_FREE_MEM' : inconsistent 
    dll linkage.  dllexport assumed.

  Then the ob/include/OB/Config.h include file probably contains
  conflicting information.  This is most common when building an OB
  DLL and later disabling it.  To fix it, delete the Config.h and
  rebuild.
