This file contains information on
installing, building, and using omniORB3 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 has been tested with the following software configuration:
- Operating System : Windows NT 4.0 and Windows 2000
- Architecture : x86 (and alpha in earlier versions)
- Compiler : Visual C++ 5.0 and Visual C++ 6.0
The omniORB binaries, when compiled using VC++ 6.0 on Windows NT,
will execute on Windows '95/8 machines and vice-versa.
As of 2.6.1, Alpha Windows NT is also supported. Unless otherwise stated, the
description below also applies to Alpha NT. Where appropriate the reference to
"x86" has to be changed to "alpha".
Roadmap
When the omniORB3 distribution is unpacked, the following are created:
- <Top-Level Directory>\ : Directory where distribution was unpacked
- <Top-Level Directory>\doc\ : omniORB Documentation
- <Top-Level Directory>\include\ : Include files
- <Top-Level Directory>\include\omniORB3\ : 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\omniidl\ : 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 omniORB, 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 omniORB3. Please read
the "Building omniORB3 from the source files" section, below. (If you want the
Win32 binary distribution, but don't have it, you can download it from our web site at
http://www.uk.research.att.com/omniORB/omniORB.html).
omniidl requires Python 1.5.2 or later. You can download the full
Python distribution from
Alternatively, for Windows on x86, you can install a minimal
version of Python which contains just the functionality required
by omniidl. The Win32 binary ditribution of omniORB comes with this
minimal python package. Download it from
Unpack the zip file at the top of the omniORB tree. It places
files in the bin, lib and include directories.
Configure the naming service
You have to configure the omniORB runtime and the naming service, consult the user
guides in ./doc for details. For a quick start, follow these steps:
- Make sure that <Top-Level Directory>\bin\x86_win32 is in your PATH environment.
- 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
- Start omniNames. The binary is in <Install
Location>\bin\win32_x86. For example:
omniNames -start
That starts omniNames on the default port of 2809. If you want
it to start on a different port, give the port number as an
argument to -start:
omniNames -start 12345
- 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 ORBInitRef , and
give it the value
NameService=corbaname::my.host.name
where my.host.name is the name of the machine running omniNames.
If you have specified a non-default port, use something like
NameService=corbaname::my.host.name:12345
- The registry entries must be duplicated on all machines that will run omniORB programs.
It is only necessary to run one instance of omniNames on your network.
- Once you are satisfied the naming service is running properly. You can setup omniNames
to run as an NT service. See the description below.
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 omniORB
programs.
Building Projects using omniORB
Before building anything (or running the examples), you should refer to the omniORB
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 omniORB and omnithread.
- Add the stub (SK.cpp) files generated by the IDL compiler to the project
(Insert->"Files into Project")
- Set up the search paths for include and library files:
- Under Tools->Options, select the Directories tab.
- In the "Show directories for" box, select "Include files".
- Add the directory where you installed the omniORB include files to the list (this is
<Top-Level Directory>\include).
- In the "Show directories for" box, select "Library files".
- Add the directory where you installed the omniORB library files to the list (this is
<Top-Level Directory\lib\x86_win32).
- Set up macros and libraries:
- Under Build->Settings, select the "C/C++" tab.
- In the "Category" box, select "C++ Language". Tick the "Enable
exception handling" box.
- In the "Category" box, select "Code Generation". In the "Use
run-time library" box, select "Multithreaded DLL".
- **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.
- Select the "Link" tab.
- In the "Category" box, select
"Input". In the "Object/library modules" box, add the following
libraries: wsock32.lib, advapi32.lib, omniORB300_rt.lib,
omniDynamic300_rt.lib, omnithread2_rt.lib
- If you are building a debug executable, the debug version of the libraries:
omniORB300_rtd.lib, omniDynamic300_rtd.lib and omnithread2_rtd.lib should be used.
- Your project is now set up, and you can build it.
If you want to use the static versions of omniORB and omnithread, you must add the
macro _WINSTATIC (see step (c) 4, above), and replace the libraries
omniORB3_rt.lib, omniDynamic300_rt.lib and
omnithread3_rt.lib with omniORB3.lib, omniDynamic3.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:
- 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 AT&T Laboratories Cambridge, 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.
- If you want to continue to use the old omniNames, you can undo this change with the
following steps:
- Edit <Top directory>\src\lib\omniORB2\Naming.idl and remove the #pragma prefix
"omg.org" line..
- Do the same to <Top directory>\idl\Naming.idl.
- Remove <Top directory>\include\omniORB3\Naming.hh.
- 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 omniidl, 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 omniORB3 from the source files
OmniORB3 should be compiled using Visual C++ 5.0 or Visual C++ 6.0. The following
description only applies to x86 platform. For alpha NT, the binary distribution is
compiled under Interix (OpenNT) posix subsystem. There is no gnu-win32 utilities available
under alpha NT at the moment.
Pre-requisites
Starting from this release, the omniORB source tree requires the
gnu-win32 utilities from Cygnus Solutions to build. It also
requires the scripting language Python to both compile and run.
gnu-win32
The full gnu-win32 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
omniORB. Alternatively, you can download a cutdown version from:
ftp://ftp.uk.research.att.com/pub/omniORB/gnu-win32-lite.zip
The utilities in this version are all you need to build
omniORB.
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:
- 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;
Path=%Path%;C:\Progra~1\DevStudio\SharedIDE\bin;<otherpaths>
- 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.
- 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.
- Now you are ready. You can now build the distribution
by following the instructions below.
Python
omniidl requires Python 1.5.2. You can download the full Python
distribution from:
http://www.python.org/download/download_windows.html
or
ftp://ftp.uk.research.att.com/pub/omniORB/python/py152.exe
Alternatively, for Windows on x86, you can install a minimal
version of Python which contains just the functionality required
by omniidl. Download it from:
ftp://ftp.uk.research.att.com/pub/omniORB/python/omnipython-x86_win32.zip
Unpack the zip file at the top of the omniORB tree. It places
files in the bin, lib and include directories.
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
Set the location of the Pyhton interpreter
Edit <top>\mk\platforms\<platform>.mk
where <platform> is the platform you just chose in config.mk,
e.g. <top>\mk\platforms\x86_nt_4.0.mk.
If you are using the omnipython minimal distribution, uncomment
the line which reads
PYTHON = $(ABSTOP)/$(BINDIR)/omnipython
otherwise, set PYTHON to the location of your Python executable.
Note that you must use a Unix-style gnu-win32 path.
Building and installing
Go into the directory <top>\src and type 'make export'. If all goes well:
- The executables and DLLs will be installed into <top>\bin\x86_win32\
- The libraries will be installed into <top>\lib\x86_win32\
Running omniNames as an NT service
- Use srvany from the NT resource kit.
- Follow the instruction provided with srvany to run a program as a service.
- An example:
- The binary of omniNames.exe is in C:\omniNames\omniNames.exe
- The log directory is set to C:\omniNames
- The standard error output is to be redirected to C:\omniNames\omniNames.errlog
- Set the following registry parameters with the service applet:
- Application: REG_SZ C:\omniNames\omniNames.exe
- AppParameters: REG_SZ -logdir C:\omniNames -errlog C:\omniNames\omniNames.errlog
- AppDirectory: REG_SZ C:\omniNames
Mailing List
There is a mailing list for discussing the use and development of omniORB. Look
here for details on subscribing.
|