This page provides important information for users of the Ice binary distribution on Windows platforms.
On this page:
The Ice binary distribution for Windows provides all Ice run time services and development tools to build Ice applications on Windows:
You only need the development environment for your target programming language to use this distribution. For example, if you want to build Ice applications in Java, you need to install a JDK, but do not need to install Visual Studio or Python.
After installing Ice, read the relevant language-specific sections below to learn how to configure your environment and start programming with Ice.
To use Ice for C++ you need to add one or more of the Ice bin
directories to your PATH
. The changes you must make depend on your compiler and architecture, as listed below:
Visual Studio 2010SP1, 32-bit
{zcode} > set PATH=<Ice installation root directory>\bin;%PATH% {zcode} |
Visual Studio 2010SP1, 64-bit
{zcode} > set PATH=<Ice installation root directory>\bin;%PATH% > set PATH=<Ice installation root directory>\bin\x64;%PATH% {zcode} |
The x64
directory must come first in your PATH
.
Visual Studio 2012, 32-bit
{zcode} > set PATH=<Ice installation root directory>\bin\vc110;%PATH% {zcode} |
Visual Studio 2012, 64-bit
{zcode} > set PATH=<Ice installation root directory>\bin\vc110;%PATH% > set PATH=<Ice installation root directory>\bin\vc110\x64;%PATH% {zcode} |
The x64
directory must come first in your PATH
.
Visual Studio 2013, 32-bit
{zcode} > set PATH=<Ice installation root directory>\bin\vc120;%PATH% {zcode} |
Visual Studio 2013, 64-bit
{zcode} > set PATH=<Ice installation root directory>\bin\vc120;%PATH% > set PATH=<Ice installation root directory>\bin\vc120\x64;%PATH% {zcode} |
The x64
directory must come first in your PATH
.
If you don't want to rely on the PATH
environment variable to locate the Ice for C++ DLLs, you can also copy the DLLs into the same directory as your executable.
To compile Ice for C++ applications with Visual C++, you should use the Ice Visual Studio Add-In.
To compile with Visual C++ Express where the Ice Visual Studio Add-in is not available, you need to configure Visual Studio manually. This involves adding the locations of the Ice header files, libraries, and executables to Visual Studio's configuration. Follow these steps:
cd Documents\My Project
Ice.props
to your project directory: copy $(ALLUSERSPROFILE)\ZeroC\Ice.props
Add Ice.props
The Release versions of the Ice libraries are compiled with /MD
to select the multi-threaded Visual C++ run-time library, while the Debug versions use /MDd
to select the debug multi-threaded run-time library. Both versions of the Ice libraries are compiled with /EHsc
to select an exception handling model.
Your application must be compiled with the same flags as the Ice libraries:
/MD /EHsc
/MDd /EHsc
To use Ice for .NET, you can either copy the .NET assemblies to the directory of your executable or add the .NET assemblies to the Global Assembly Cache (GAC).
Copying the Ice for .NET assemblies to the executable directory is the simplest solution. You can set up your Visual Studio projects to copy the assemblies by setting the Copy Local
property to True
. To access this property in the Solution Explorer, open the References
folder of your project and click on the assembly to access its properties in the Properties
panel.
You can also add the Ice for .NET assemblies to the GAC. To do this, open a command prompt window with Administrator privileges and use gacutil
:
{zcode} > gacutil /i <library.dll> {zcode} |
The gacutil
tool is included with your Visual C# installation. For example, if you have installed Visual Studio 2010 in C:\Program Files
, the path to gacutil
is
C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\gacutil.exe
Once installed in the GAC, the assemblies will always be located correctly without having to set environment variables or copy them into the same directory as an executable.
If you want line numbers for stack traces, you must also install the PDB (.pdb) files in the GAC. Unfortunately, you cannot do this using Explorer, so you have to do it from the command line. Open a command shell window and navigate to C:\Windows\Microsoft.NET\assembly\GAC_MSIL\Ice
(assuming C:\Windows
is your system root). Doing a directory listing there, you will find a directory named v4.0_3.5.1.0__<UUID>
, for example:
v4.0_3.5.1.0__cdd571ade22f2f16
Change to that directory (making sure that you use the correct version number for this release of Ice). In this directory, you will see the Ice.dll
you installed into the GAC in the preceding step. Now copy the Ice.pdb
file into this directory:
{zcode} > copy <Ice installation root directory>\Assemblies\Ice.pdb {zcode} |
The Ice for .NET run time implements protocol compression by dynamically loading the native library bzip2.dll
from a directory in your PATH
. Ice disables the protocol compression feature if it is unable to load the bzip2
library successfully.
This DLL is included in your Ice distribution, therefore the Ice bin
directory must be added to your PATH
:
{zcode} > set PATH=<Ice installation root directory>\bin;%PATH% {zcode} |
On 64-bit Windows, use the following setting instead:
{zcode} > set PATH=<Ice installation root directory>\bin\x64;%PATH% {zcode} |
If the wrong PATH
is set, the Ice run time prints a warning to the console when it detects a bzip2.dll
format mismatch during start-up.
The Ice assembly for the .NET Compact Framework is installed as <Ice installation root directory>
\Assemblies\cf\Ice.dll
. The Visual Studio Add-in detects a Smart Device project and automatically configures it to use the .NET CF version of the Ice assembly.
The Ice assembly for Silverlight is installed as <Ice installation root directory>
\Assemblies\sl\Ice.dll
. The Visual Studio Add-in detects a Silverlight project and automatically configures it to use the Silverlight version of the Ice assembly.
To use Ice for Java, you must add Ice.jar
to your CLASSPATH
, as shown below:
{zcode} > set CLASSPATH=<Ice installation root directory>\lib\Ice.jar;%CLASSPATH% {zcode} |
If you intend to use Freeze for Java, you must include Freeze.jar
in your CLASSPATH
along with Ice.jar
:
{zcode} > set CLASSPATH=<Ice installation root directory>\lib\Freeze.jar;%CLASSPATH% {zcode} |
Classes for the other Ice services are provided in separate JAR files:
Glacier2.jar
IceBox.jar
IceGrid.jar
IcePatch2.jar
IceStorm.jar
If your application uses any of these services, add the appropriate JAR files to your CLASSPATH
as shown above.
To use a Freeze demo, the JVM requires that the directory containing Berkeley DB's native libraries be included in java.library.path
, therefore you must add this directory to your PATH
:
{zcode} > set PATH=<Ice installation root directory>\bin;%PATH% {zcode} |
For a 64-bit JVM, use the following setting instead:
{zcode} > set PATH=<Ice installation root directory>\bin\x64;%PATH% {zcode} |
Ice for Java supports protocol compression using the bzip2
classes included with ant. Compression is automatically enabled if these classes are present in your CLASSPATH
. You can either add ant.jar
to your CLASSPATH
, or download only the bzip2 classes from
Note that these classes are a pure Java implementation of the bzip2 algorithm and therefore add significant latency to Ice requests.
ZeroC has created a Slice2Java plug-in for Eclipse that automates the translation of your Slice files. If you use Eclipse, we strongly recommend using this plug-in for your own development.
The Slice2Java plug-in is required if you intend to build any of the Android sample projects included in this distribution. |
For installation instructions, please refer to the ZeroC web site. The manual provides more information about configuring the plug-in and using it in your projects.
Ice requires Android 2.3 or later. Aside from that, there are no other special requirements for using Ice in an Android application. We strongly recommend installing our Slice2Java plug-in for Eclipse to automate the compilation of your Slice definitions.
To use Ice for Python, you must add the Ice bin
directory to your PATH
and set PYTHONPATH
so that the Python interpreter is able to load the Ice extension. For a 32-bit Python installation, use these settings:
{zcode} > set PATH=<Ice installation root directory>\bin;%PATH% > set PYTHONPATH=<Ice installation root directory>\python {zcode} |
For a 64-bit Python installation, use these settings instead:
{zcode} > set PATH=<Ice installation root directory>\bin\x64;%PATH% > set PYTHONPATH=<Ice installation root directory>\python\x64 {zcode} |
To use Ice for Ruby, you must add the Ice bin
directory to your PATH
:
{zcode} > set PATH=<Ice installation root directory>\bin;%PATH% {zcode} |
You must also set RUBYLIB
so that the Ruby interpreter is able to load the Ice extension:
{zcode} > set RUBYLIB=<Ice installation root directory>\ruby;%RUBYLIB% {zcode} |
The binary distribution of PHP 5.4 for Windows is compiled with Visual Studio 2008 (Visual C++ 9) and therefore is not compatible with the Apache binaries provided by the Apache Software Foundation, which are compiled with Visual C++ 6.
The Ice extension for PHP included in this installer is also compiled with VC9 for compatibility with the PHP binary distribution. To use this extension, you will need a compatible PHP binary distribution as well as a compatible Web server. If you wish to use Apache, you can obtain a VC9 build of Apache from alternate sources.
If you require a version of the Ice extension for a different environment, you will need to compile the extension from source. Download the Ice source distribution and review the php/INSTALL
file for details.
The PHP documentation describes how to configure the Apache servers for PHP, and the PHP installer may have already performed the necessary steps. We provide instructions below for configuring PHP to use the Ice extension. These instructions make several assumptions:
C:\Program Files\PHP
C:\Ice
If you have a different installation, you will need to make the appropriate changes as you follow the instructions.
With Apache running, verify that PHP has been loaded successfully by creating a file in Apache's document directory (htdocs
) called phpinfo.php
that contains the following line:
{zcode:php} <?php phpInfo();?> {zcode} |
Open the file in your browser using a URL such as
If you have configured PHP correctly, you should see a long page of PHP configuration information. If you do not see this page, or an error occurs, check Apache's error log as well as the Windows event log for more information. Also note that you may need to restart Apache if it was running at the time you installed PHP.
Review the settings on the browser page for an entry titled Loaded Configuration File
. It will have a value such as
C:\Program Files\PHP\php.ini
As an administrator, open this file in a text editor and append the following line:
extension = php_ice.dll
The file php_ice.dll
contains the Ice extension for PHP.
Look for the extension_dir
setting in the browser page or in PHP's configuration file. It typically has the following value by default:
extension_dir = "C:\Program Files\PHP\ext"
If instead the extension_dir
setting contains a relative path, it it is resolved relative to the working directory of the Apache process (Apache's working directory is usually its installation directory).
Copy the DLL for the Ice extension to PHP's extension directory:
{zcode} > copy C:\Ice\bin\php_ice.dll "C:\Program Files\PHP\ext" {zcode} |
Regardless of the location of PHP's extension directory, the Ice extension's dependent libraries must be located in Apache's executable search path.
The Ice extension depends on the following libraries:
bzip2_vc90.dll
ice35_vc90.dll
iceutil35_vc90.dll
slice35_vc90.dll
All of these files can be found in the bin
subdirectory of your Ice installation (e.g., C:\Ice\bin
). Apache must be able to locate these DLLs during startup, and several alternatives are available:
PATH
. Using the System
control panel, change the system PATH
to include C:\Ice\bin
. Note that Windows must be restarted for this change to take effect.C:\WINDOWS\system32
). We do not recommend this option.If Apache cannot find or access a DLL, Apache startup may fail with an access violation, or the PHP module may ignore the Ice extension and continue its initialization. Consequently, a successful Apache startup does not necessarily mean that the Ice extension has been loaded. Unfortunately, the message reported by PHP in Apache's error log is not very helpful; the error might imply that it cannot find php_ice.dll
when in fact it was able to open php_ice.dll
but a dependent DLL was missing or inaccessible.
Review the access rights on PHP's extension directory, the Ice extension DLL, and its dependent libraries. When running as a Windows service, Apache runs in the Local System
account (also known as NT Authority\SYSTEM
). You can use the cacls
utility in a command window to view and modify access rights. For example, run the following commands to review the current access rights of the Ice extension:
{zcode} > cd \Program Files\PHP\ext > cacls php_ice.dll {zcode} |
Restart Apache and verify that the PHP module and the Ice extension have been loaded successfully. After reloading the phpinfo.php
page in your browser, scan the entries for a section titled ice
. The presence of this section indicates that the extension was loaded.
If Apache does not start, check the Windows Event Viewer as well as Apache's log files for more information. The most likely reasons for Apache to fail at startup are missing DLLs (see step 4) or insufficient access rights (see step 5).
Your application will also need to include at least some of the Ice for PHP run-time source files (installed in C:\Ice\php
). To make these files available to your application, you can either modify PHP's include path or copy the necessary files to a directory that is already in the interpreter's include path. You can determine the current include path by loading the phpinfo.php
page in your browser and searching for an entry named include_path
.
If you want to make the Ice run-time files available to all PHP applications on the host, you can modify the include_path
setting in php.ini
to add the installation directory:
{zcode} include_path = C:\Ice\php;... {zcode} |
Another option is to modify the include path from within your script prior to including any Ice run-time file:
{zcode:php} ini_set('include_path', ini_get('include_path') . PATH_SEPARATOR . 'C:/Ice/php') require 'Ice.php'; // Load the core Ice run time definitions. {zcode} |
The main Ice for .NET assembly (Ice.dll
) included in the Windows binary distribution uses unmanaged code. If you require only managed code then you can download the Ice source distribution and build Ice for .NET in a purely managed version. Note that the managed version of Ice for .NET omits support for protocol compression and for signal handling in the Ice.Application
class.
You can download the source distribution at the ZeroC web site.
During installation, sample programs for all supported programming languages are installed by default in a sub-folder of the Documents
or My Documents
folder of the user who performed this installation. You'll find a shortcut to this directory in your Start menu. You can also download a ZIP archive of these sample programs and extract the archive in a folder of your choice.
The config
subdirectory of your Ice installation includes sample configuration files for the Glacier2 router, IceGrid node, and IceGrid registry. These files provide a good starting point on which to base your own configurations, and they contain comments that describe the settings in detail.
If you intend to edit one of the configuration files but you have installed your distribution into \Program Files
or \Program Files (x86)
on Windows Vista or later, be aware that Windows makes it difficult to make permanent modifications to files in these directories. We recommend copying the files to the location of your choice. For more information on this topic, refer to the Virtualization section of New UAC Technologies for Windows Vista.
The Ice manual provides more information on installing and running the IceGrid registry, IceGrid node, and Glacier2 router as Windows services.
You can launch the IceGrid Administrative Console using the shortcut that the Ice installer created in your Start menu as IceGrid Admin. The console is a Java program and requires JRE 7u6 or later.
The Ice binary distribution includes an add-in for Visual Studio that helps to create and manage projects with Slice files. The Ice Visual Studio Add-In supports C++, .NET, .NET Compact Framework, and Silverlight projects.
The add-in does not support Visual Studio Express editions because Microsoft does not permit add-ins to be written for Express editions of Visual Studio. |
The installer for the Ice binary distribution detects if Visual Studio 2008, Visual Studio 2010, Visual Studio 2012, or Visual Studio 2013 is installed on the target computer and configures the corresponding Ice add-in for all users. If you install Visual Studio after installing Ice, you will have to re-run the Ice installer and choose Repair to install the add-in.
The Ice installer adds information to the Windows registry to indicate where it was installed. Developers can use this information to locate the Ice files in their applications.
The registration key used by this installer is:
HKEY_LOCAL_MACHINE\Software\ZeroC\Ice 3.5.1
The install location is stored as a string value named InstallDir
.
The binary distribution for Windows includes the following third-party packages as separate binary libraries: