path: root/cpp/install/unix/README.Linux

======================================================================
The Internet Communications Engine
======================================================================

Ice is a modern alternative to object middleware such as CORBA or
COM/DCOM/COM+. It is easy to learn, yet provides a powerful network
infrastructure for demanding technical applications. It features an
object-oriented specification language, easy to use C++, Java, Python,
PHP, C#, and Visual Basic mappings, a highly efficient protocol,
asynchronous method invocation and dispatch, dynamic transport
plug-ins, TCP/IP and UDP/IP support, SSL-based security, a firewall
solution, and much more.

Ice is available under the terms of the GNU General Public License
(GPL) (see LICENSE file). Commercial licenses are available for
customers who wish to use Ice with proprietary products. Please
contact sales@zeroc.com for more information about licensing Ice.


======================================================================
About this distribution
======================================================================

This distribution is a binary release of Ice @ver@ for Linux and
includes the following components:

- The Ice runtime, including executables for the Ice services, HTML
  documentation, and Slice files.

- Run time libraries for C++, Java, Python, and C# (Mono). These
  libraries enable you to execute Ice applications.

- Tools and libraries for developing Ice applications.


======================================================================
Binary compatibility
======================================================================

Patch releases of Ice are binary compatible. For example, version 2.1.1
is compatible with 2.1.0, so you can run applications compiled with
2.1.0 with the 2.1.1 runtime without having to recompile.

With the binary installers, simply uninstall the previous version of
Ice and install the new one. Already deployed applications that were
compiled against the 2.1.0 runtime will automatically use the 2.1.1
runtime.

Note: Under Mono, binary compatibility currently does not work due to
      issues with Mono. Until this problem in Mono is fixed, you cannot
      run 2.1.0 applications against the 2.1.1 runtime.


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

This binary distribution was compiled on Linux Fedora Core 3 (FC3)
using FC3's default C++ compiler, GCC 3.4.2.

This distribution depends on a number of third-party libraries:

- Berkeley DB 4.2.52
- expat 1.95
- OpenSSL 0.9.7
- bzip2 1.0.2
- readline 4.3
- ncurses 5.4
- libgcc 3.4.2
- libstdc++ 3.4.2

All of these libraries are included with your FC3 distribution in the
following RPMs:

Berkeley DB    db4, db4-utils, db4-java
expat 	       expat
OpenSSL	       openssl, openssl-devel
bzip2          bzip2-libs
readline       readline
ncurses        ncurses
libgcc         libgcc
libstdc++      libstdc++

If you prefer to install the third-party libraries yourself, be aware
that Berkeley DB must be configured with --enable-cxx and
--enable-java.


Java
----

Ice for Java requires J2SE 1.4.2 or 1.5.0. RPMs can be obtained from
JavaSoft at http://www.javasoft.com/j2se.


Python
------

The Ice extension for Python included in this distribution requires
Python 2.3.4. The Python runtime RPM is python-2.3.4-11. If you
prefer to use Python 2.4, you can download the Ice for Python source
code from the ZeroC web site at http://www.zeroc.com/download.html.


C#
--

Ice for C# requires Mono 1.1.7. The following RPM can be downloaded at
http://www.mono-project.com/Downloads:

mono-core-1.1.7-1.novell.i586.rpm

Note that this RPM depends on libicu 2.6, which can be obtained by
installing libicu-2.6.2-1.1.fc3.rf.i386.rpm, available from
http://dag.wieers.com/packages/icu/.


PHP
---

The Ice extension for PHP included in this distribution requires
PHP 5.0.4. You can obtain a PHP source code distribution from
http://www.php.net.


======================================================================
64 bit builds on x86-64
======================================================================

This distribution only contains 32-bit binaries. If you need a 64-bit
version, you can download the Ice sources from the ZeroC web site at
http://www.zeroc.com/download.html and build Ice in 64-bit mode. See
the INSTALL.LINUX file of the source distribution for more details.


======================================================================
Setting up your environment to use Ice
======================================================================


General
-------

The discussion below assumes you have defined the ICE_HOME variable
with the directory of your Ice installation.

In order to use Ice services and tools such as Slice translators, you
need to add $ICE_HOME/bin to your PATH and $ICE_HOME/lib to your
LD_LIBRARY_PATH, as shown in the bash commands below:

$ export PATH=$ICE_HOME/bin:$PATH
$ export LD_LIBRARY_PATH=$ICE_HOME/lib:$LD_LIBRARY_PATH


C++
---

When compiling Ice for C++ programs, you must pass $ICE_HOME/include
to the compiler with the -I option, and $ICE_HOME/lib with the -L
option. Furthermore, a C++ program needs to link with at least libIce
and libIceUtil, so a typical link command would look like this:

$ c++ -o myprogram myprogram.o -L$ICE_HOME/lib -lIce -lIceUtil

Additional libraries are necessary if you are using an Ice service
such as IcePack or Glacier2.


Java
----

To use Ice for Java, you must add $ICE_HOME/lib/Ice.jar to your
CLASSPATH, as shown below:

$ export CLASSPATH=$ICE_HOME/lib/Ice.jar:$CLASSPATH

Note that the Freeze component of Ice for Java requires Berkeley DB.
In order to use Freeze, you must add db.jar to your CLASSPATH. In
addition, the JVM requires the directory containing the Berkeley DB
libraries to be listed in java.library.path, therefore you must add
this directory to your LD_LIBRARY_PATH (even if the libraries reside
in /usr/lib).


Python
------

To use Ice for Python, the PYTHONPATH environment variable must be
updated so that the interpreter can load the Ice extension and
supporting Python files:

$ export PYTHONPATH=$ICE_HOME/python:$ICE_HOME/lib:$PYTHONPATH


C#/Mono
-------

You can update MONO_PATH with the directory containing the Ice for C#
runtime libraries, as the following bash command shows:

$ export MONO_PATH=$ICE_HOME/bin:$MONO_PATH

Alternatively, you can add the libraries to the GAC yourself using a
command like this:

$ gacutil -i bin/icecs.dll

You also need to add $MONO_PATH/lib to your LD_LIBRARY_PATH.

The instructions for running the demos assume that you have configured
your kernel to automatically execute the Mono interpreter. To do this,
run the following commands as root (replace /usr/bin/mono with the
location of your mono interpreter):

    if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then
	/sbin/modprobe binfmt_misc mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
    fi 
    if [ -e /proc/sys/fs/binfmt_misc/register ]; then
	echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register
    else
	echo "No binfmt_misc support" exit 1
    fi 

If you don't want to do this you need to run the executable with
mono. For example,

$ mono server.exe


PHP
---

The Ice extension for PHP must be added to your PHP configuration
by editing php.ini and adding the following lines:

extension_dir = <ICE_HOME>/lib
extension = icephp.so

At run time, the PHP interpreter requires the Ice shared libraries
as well as the Slice preprocessor ($ICE_HOME/bin/icecpp), therefore
these components must be in a standard location or accessible via the
PATH and LD_LIBRARY_PATH environment variables.

You can verify that the Ice extension is installed properly by
examining the output of the "php -m" command, or by calling the
phpinfo() function from a script.


======================================================================
Demos and documentation
======================================================================

Sample programs are provided in the Ice-@ver@-demos.tar.gz package,
which can be downloaded from the ZeroC web site at

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

Please refer to the README.DEMOS file included in that package for
more information.

See doc/README.html for information on the documentation included with
this distribution.