======================================================================
Introduction
======================================================================

This file describes the Ice source distribution, including information
about compiler requirements, third-party dependencies, and
instructions for building and testing the distribution.

If you prefer, you can download a Windows installer that contains
pre-compiled debug and release libraries, executables, and everything
else necessary to build Ice applications on Windows. Installers for
each supported compiler are available at the link below:

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


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


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

Ice has been extensively tested on:

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

Ice does not work on Windows 2000. However, porting Ice to Windows
2000 should be fairly simple if you do not require UDP multicast or
IPv6.

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++ 2008 (Professional and Express editions)

  Visual C++ 2008 Express is available for download from:

  http://www.microsoft.com/express/vc/

- Microsoft Visual C++ 2005 SP1 (Professional and Express editions)
 
  Service Pack 1 is available for download from:

  http://msdn2.microsoft.com/en-us/vstudio/bb265237.aspx

  Visual C++ 2005 Express and SP1 is available for download from:

  http://www.microsoft.com/express/2005/

- Microsoft Visual C++ 6.0 SP5 with the Windows Server 2003 PSDK
  (February 2003) and 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.

- CodeGear C++Builder 2007 R2 with December 2007 Update

- CodeGear C++Builder 2009 Update 2


Visual C++ Express/C++Builder Setup
---------------------------------

Users of Visual C++ 2005 Express, Visual C++ 2008 Express, 
C++Builder 2007 or C++Builder 2009 need to install the Microsoft
Platform SDK:

  http://www.microsoft.com/Downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en

Once installed, you need to add the Platform SDK directories to the
INCLUDE, LIB and PATH environment variables. This can be done by
executing the following script from within the compiler command prompt:

  C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\SetEnv.Cmd


Visual C++ 6.0 Setup
--------------------

Users of Visual C++ 6.0 need to install the February 2003 Microsoft
Platform SDK in order to compile Ice:

  http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm

Alternatively, for MSDN subscribers, you may download the PSDK from
the MSDN Subscriber Downloads. In the content tree open:

  Tools, SDKs, and DDKs / Platform SDK / Platform SDK - February 2003 Edition (English)

and then download en_platformsdk_win2003.exe

Once installed, you need to add the Platform SDK directories to the
INCLUDE, LIB and PATH environment variables. This can be done by
executing the following script:

  C:\Program Files\Microsoft SDK\SetEnv.Bat

Note that you must execute this script after setting up your VC60
build environment to ensure that the Platform SDK include directory
appears before the VC60 include directories in the INCLUDE environment
variable.

This Platform SDK is only required to compile Ice and is not necessary
to build applications using Ice.

To build the MFC demos, you must have the Unicode library installed.
If you get a link failure about a missing MFC42UD.LIB, run Visual Studio
setup, and add the Unicode library (under "MFC and Template Libraries",
"MS Foundation Class Libraries", "Shared Libraries for Unicode") to
your Visual Studio installation.


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.6.21
- expat 2.0
- OpenSSL 0.9.7 or later (OpenSSL 0.9.8 or later recommended)
- bzip2 1.0
- mcpp 2.7.2

You do not need to build these packages yourself, as ZeroC supplies a
Windows installer for each supported compiler that contains release
and debug libraries for all of the third-party dependencies.

If you intend to build the third-party dependencies from source, we
recommend downloading the Ice third-party source archive from

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

This archive contains the source distributions for each of the
third-party dependencies, as well as required source patches and 
configuration instructions.

For more information about these dependencies, please refer to
the links below:

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


Monotonic clock
---------------

Ice uses the QueryPerformanceCounter Windows API function to measure
time with a monotonic clock. If you are experiencing timing or
performance issues, there are two knowledgebase articles that may be
relevant for your system:

  http://support.microsoft.com/?id=896256
  http://support.microsoft.com/?id=895980


======================================================================
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 that is configured for your target architecture.
For example, when using Visual Studio 2005 or Visual Studio 2008, you
have several alternatives:

 - Visual Studio Command Prompt
 - Visual Studio x64 Win64 Command Prompt
 - Visual Studio x64 Cross Tools Command Prompt

Using the first configuration produces 32-bit binaries, while the
second produces 64-bit binaries. In order to build a 64-bit version of
Ice using a "Cross Tools" command prompt, you must set the following
environment variable:

> set XTARGET=x64

Note that you must be using a Windows x64 platform when compiling a
64-bit version of Ice.

For C++Builder use the "RAD Studio Command Prompt".

Change the working directory to Ice-3.3.1. For example:

> cd C:\Ice-3.3.1\cpp

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 and src\iceserviceinstall directories
generates warnings like the one shown below:
 
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
----------------------

Python is required to run the test suite:

  http://www.python.org/download

You can now run the test suite. 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/2008 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/2008 Command Prompt".

You can also use the "Visual Studio x64 Cross Tools Command Prompt" if
you set the following environment variable:

> set XTARGET=x64

Note that you must be using a Windows x64 platform when compiling a
64-bit version of Ice.


======================================================================
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, if you plan to use the Visual Studio IDE for your
Ice project, make sure to add the bin directory to the Visual C++
"Executable files", the include directory to the "Include files" and
the lib directory to the "Library files" in the IDE:

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

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

If you built Ice on x64, the binaries are installed in the bin\x64
directory and the libraries are installed in the lib\x64 directory.