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

- Ice 3.2.1
- Python 2.3, 2.4, or 2.5 built with a C++ compiler compatible with the
  C++ compiler used to build Ice for C++.

Depending on your platform, you may need to download the Python source
distribution from http://www.python.org and make our own Python build.

You can use the Ice for C++ binary distribution for your platform to
build the Ice extension for Python.


======================================================================
Building the Ice extension for Python (Linux/Solaris/HP-UX/Mac OS X)
======================================================================

Follow these steps to build the Ice extension for Python:

1) Edit config/Make.rules and do the following:

   * Modify the installation prefix (if necessary).

   * Review the comments describing the PYTHON_HOME variable.

2) Execute 'python -V' to verify that the correct Python interpreter
   is in your executable search path.

3) Run 'make'.

4) Upon successful completion, run 'make install'. You may need
   additional user privileges to install in the directory specified by
   config/Make.rules.

5) See "Configuring your Environment" below.


======================================================================
Building the Ice extension for Python (Windows)
======================================================================

The Python interpreter is readily available on Windows platforms. You
can build it yourself using Microsoft Visual C++, or obtain a binary
distribution from the Python web site (http://www.python.org).

Follow these steps to build the Ice extension for Python:

1) Open a command prompt that supports command-line compilation with
   Visual C++. For example, you can execute the Visual C++ batch file
   vcvars32.bat to configure your environment. Alternatively, you can
   start a "Visual Studio Command Prompt" by selecting the appropriate
   entry from the Visual Studio program group in your Start menu.

2) Change to the Ice for Python source directory.

3) Set the ICE_HOME environment variable with the Ice installation
   directory. For example:

   > set ICE_HOME=C:\Ice-3.2.1

4) Edit config\Make.rules.mak and review the settings. In particular
   you must set CPP_COMPILER to the appropriate compiler.

5) Run nmake:

   > nmake /f Makefile.mak

NOTES:

 * Normally you should build with OPTIMIZE=yes. If you wish to build
   a debug version of the Ice extension, set OPTIMIZE=no. In this
   case, you will also need to build a debug version of the Python
   interpreter from sources.

 * The Ice extension is created as python\IcePy.pyd. The extension
   was named python\IcePy.dll in prior releases, but the .dll suffix
   is no longer supported by Python 2.5.


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.


======================================================================
Configuring your Environment
======================================================================

Unix:

  Modify your PYTHONPATH environment variable to include the Ice 
  extension for Python. Assuming you installed the extension in the
  default directory (/opt/IcePy-3.2.1), you would modify your
  environment as shown below:

  $ export PYTHONPATH=/opt/IcePy-3.2.1/python:$PYTHONPATH

Windows:

  Modify your environment to allow Python to find the Ice extension
  for Python. The interpreter must be able to locate the extension
  DLL as well as the Python source files in the "python" subdirectory.
  This is normally accomplished by setting the PYTHONPATH environment
  variable to contain the necessary subdirectory. For example, if
  the Ice for Python extension is installed in C:\IcePy-3.2.1, you
  could configure your environment as follows:

  > set PYTHONPATH=c:\IcePy-3.2.1\python

ICEPY_HOME is used by the Ice for Python test suite and the Ice for
Python bidir demo. If you want to run these than you should also set
ICEPY_HOME to your Ice for Python installation.

  # Unix
  $ export ICEPY_HOME=/opt/IcePy-3.2.1

  # Windows
  > set ICEPY_HOME=c:\IcePy-3.2.1

=========================================================================
Running the Tests
=========================================================================

To run the tests, open a command window and change to the top-level
directory. At the command prompt, execute:

  > python allTests.py

You can also run tests individually by changing to the test directory
and running this command:

  > python run.py

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


=========================================================================
HP-UX Notes
=========================================================================

Python needs to be configured and built with the following options in
order to successfully load the Ice extension:

./configure --enable-shared --with-cxx="aCC -AA +DAportable" \
--with-libs="-lxnet" ...


=========================================================================
Solaris Notes
=========================================================================

Python needs to be configured and built with the following options in
order to successfully load the Ice extension:

./configure --enable-shared --with-cxx=CC --without-gcc ...
