path: root/cpp/INSTALL.WINDOWS

======================================================================
Requirements
======================================================================


Windows version
---------------

Ice has been extensively tested on:

- Windows XP x86
- Windows 2003 Server x86 and x64
- Windows Vista x86

Ice is also expected to work on Windows 98, Windows 98 SE, Windows ME, 
Windows NT 3.51, Windows NT 4.0, and Windows 2000, but is not supported
on these Windows versions.

There are several Ice binary distributions available for Windows, each
built with a different C++ compiler. These distributions can be 
downloaded from:

  http://www.zeroc.com/download.html

The binary distributions include everything necessary to build Ice 
applications and require Windows XP, Windows Server 2003, or
Windows Vista.


C++ compiler
------------

The following C++ compilers are supported:

- Microsoft Visual C++ 2005 (both Professional and Express editions)
 
  Visual C++ 2005 Express is available for download from:

  http://msdn.microsoft.com/vstudio/express/visualc/

- Microsoft Visual C++ .NET 2003 SP1 (aka VC++ 7.1)

- Microsoft Visual C++ 6.0 SP5 with STLport 4.6.2 (or later)

  The Standard Template Library included with Visual C++ 6.0 is not 
  supported. STLPort is included in the Ice third-party package
  for Visual C++ 6.0.

  In order to build the MFC demos, you need to install the MFC
  "Shared Libraries for Unicode".

- Borland C++Builder 2006 Update 2


Visual C++ 2005 Express Setup
-----------------------------

Users of Visual C++ 2005 Express need to install the Microsoft
Platform SDK:

  http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en

Once installed, follow the instructions at the link below:

  http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/

You also need to add the Platform SDK directories to the INCLUDE, LIB
and PATH environment variables. For example:

@SET PDK_HOME=C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2
@SET PATH=%PDK_HOME%\bin;%PATH%
@SET INCLUDE=%PDK_HOME%\include;%INCLUDE%
@SET LIB=%PDK_HOME%\lib;%LIB%

The PDK_HOME environment variable must be defined in order to build
the Ice source distribution. Note that PDK_HOME must not contain a
trailing backslash (\).

You may also need to execute the vsvars32.bat script, located in
C:\Program Files\Microsoft Visual Studio 8\Common7\Tools, to properly
configure your build environment.


NMAKE and Message Compiler (MC.EXE)
-----------------------------------

In order to build Ice you need the Microsoft NMAKE and Message Compiler 
utilities. These are included in all Microsoft C++ compiler distributions. If
you are using the Borland C++ compiler, you can download them as part of the 
Windows Platform SDK:
 
  http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en


Third-party libraries
---------------------

Ice has dependencies on a number of third-party libraries:

- STLport 4.6.2 or later (only for Visual C++ 6.0)
- Berkeley DB 4.5.20
- expat 2.0
- OpenSSL 0.9.7 or later (OpenSSL 0.9.8 or later recommended)
- bzip2 1.0
- mcpp 2.6.4

If you have downloaded an Ice binary installer, you already have all 
of the required third-party libraries and do not need to download any 
additional packages, nor do you need to compile the Ice source
code.

If you want to compile an Ice source distribution, you can download an
installer containing binaries for all of the required third-party
libraries from the ZeroC web site:

  http://www.zeroc.com/download.html

Finally, if you prefer to download and install the third-party
dependencies yourself, you can find them at the following locations:

STLport         http://www.stlport.org/download.html
Berkeley DB     http://www.oracle.com/database/berkeley-db/index.html
expat           http://sourceforge.net/projects/expat/
OpenSSL         http://www.openssl.org
bzip2           http://sources.redhat.com/bzip2
mcpp            http://mcpp.sourceforge.net/download.html

For STLport installation instructions, please refer to

  http://www.stlport.org/doc/install.html

Note: For a regular build of bzip2, both the debug and the release
library are named "libbz2.lib". In order to have both a debug and a
release version on your system, please rename the debug library to
"libbz2d.lib". This is also what the Ice project files expect if you
build a debug version of Ice. 

For mcpp it is necessary to first apply a source patch available on
the Ice download page before building. From the mcpp 2.6.4 base 
directory run

  patch -p0 < mcpp-2.6.4.patch

Ice requires the library build of mcpp, so please follow the library
build instructions found in doc/mcpp-porting.html in the mcpp source
distribution.

If you compile the third-party libraries from source code, we
recommend that you use the same Visual C++ version to build all of
the third-party libraries.

Users of Visual C++ 6.0 must configure Visual Studio to use STLPort
before building Berkeley DB:

- In the Visual C++ 6.0 IDE, choose Tools->Options->Directories

- Select "Include files"

- Add the include directory for STLport first in the list. (Note that
  you must add the "include\stlport" directory, not just "include".)

- Select "Library files"

- Add the lib directory for STLport.


Python
------

You will need Python to run the automated test suite. If you have no
interest in running the test scripts, Python is not required.

You can download a Python distribution for Windows from

  http://www.python.org/download

Important note for Windows 98, Windows 98 SE and Windows ME users:

The Windows 9x shell is too limited to run the Ice test suite. For
these versions of Windows, you need Cygwin and the python interpreter
that comes with Cygwin in order to run the test suite. Cygwin can be
downloaded from:

  http://www.cygwin.com


======================================================================
Compilation and Testing
======================================================================


Building Ice
------------

Using your favorite Zip tool, unzip the Ice source archive anywhere 
you like.

Add the "bin" directory of the third-party libraries to your PATH.

Open a command prompt and change the working directory to Ice-@ver@.
For example:

> cd C:\Ice-@ver@

Edit config\Make.rules.mak to establish your build configuration. The
comments in the file provide more information. In particular, you
must set CPP_COMPILER to the appropriate compiler.

Now you're ready to build Ice:

> nmake /f Makefile.mak


Visual C++ 2005 Note
--------------------

Compiling the src\IcePatch2 directory generates a number of warnings:
 
security.manifest:manifest authoring warning 81010002:Unrecognized Element
"trustInfo" in namespace "urn:schemas-microsoft-com:asm.v3".

This warning is harmless and is due to a known problem in MT.EXE. For
more information, see

  https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=237720


Running the Test Suite
----------------------

You can now run the test suite, provided that you have installed 
Python. Open a command prompt and change to the top-level Ice 
directory. At the command prompt, execute:

> python allTests.py

If everything worked out, you should see lots of "ok" messages. In
case of a failure, the tests abort with "failed".

If you want to try out any of the demos, make sure to update your PATH
environment variable to add the "bin" directory, which contains the
Ice DLLs and executables.


======================================================================
x64 Platform
======================================================================

Building Ice on x64 with the Visual Studio 2005 C++ compiler is like
building Ice on x86. You just need need to perform the build in a 
"Visual Studio x64 Win64 Command Prompt", and not in a regular "Visual
Studio 2005 Command Prompt".


======================================================================
Windows 98, Windows 98 SE, Windows ME, Windows NT 3.51 
======================================================================

By default, IceUtil::Mutex and related classes are implemented using
Windows' CriticalSection, and in particular they use the function
TryEnterCriticalSection. This function is either not present or
implemented as a "no-op" call on Windows 98, Windows 98 SE, Windows ME
and Windows NT 3.51, so default Ice builds cannot be used on these
versions of Windows.

IceUtil::Mutex and related classes can also use "heavier" mutex
objects that allow Ice to work on all Windows versions (>= 98). If you
wish to build Ice in this configuration, you must first edit the file
include\IceUtil\Config.h and remove the following lines:

#   ifndef _WIN32_WINNT
        //
        // Necessary for TryEnterCriticalSection.
        //
#       define _WIN32_WINNT 0x0400
#   endif

The IceGrid Node is not available on Windows 98, 98SE and ME, because
it requires a DLL that is not available on these versions of Windows.

On Windows 98, Windows 98 SE and Windows ME, we also recommend that
you increase the number of connections supported by TCP/IP (to 500 for
example). See MaxConnections at

  http://support.microsoft.com/default.aspx?scid=kb;EN-US;158474


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

Simply run "nmake /f Makefile.mak install". This will install Ice in
the directory specified by the "prefix" variable in
config\Make.rules.mak. After installation, make sure that the
<prefix>/bin directory is in your PATH. You must also add the include
directory to the Visual C++ "Include files", the lib directory to the
"Library files", and the bin directory to the "Executable files":

  * Visual C++ 6.0: Tools->Options->Directories

  * Visual C++ .NET 2003: Tools->Options->Projects->VC++ Directories

  * Visual C++ 2005: Tools->Options->Projects and Solutions->
                                                    VC++ Directories

See the WINDOWS_SERVICES.txt file included in this distribution for
information on how to install and run the IceGrid registry, IceGrid
node, and Glacier2 router as Windows services.