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

======================================================================
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++, C#, Java,
Python, Ruby, PHP, 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, C# (Mono) and PHP. These
  libraries enable you to execute Ice applications.

- Tools and libraries for developing Ice applications.


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

This binary distribution was compiled on SuSE Linux Enterprise Server
10 (SLES10), using the default C++ compiler (GCC 4.1.0).

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

- expat
- OpenSSL
- bzip2

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

expat:	       expat
OpenSSL:       openssl
bzip2:         bzip2


Java
----

Ice for Java requires Java 1.4.2, 1.5.0 or 1.6.0. RPMs can be obtained 
from Sun Microsystems at http://java.sun.com.


Python
------

The Ice extension for Python included in this distribution requires
the installation of the SLES10 python RPM.


C#
--

Ice for C# requires Mono 1.2.2 or later. You can download the RPMs at:

  http://www.go-mono.com/download/x86/mono/1.2.2.1/mono-core-1.2.2.1-0.novell.i586.rpm
  http://www.go-mono.com/download/x86_64/mono/1.2.2.1/mono-core-1.2.2.1-0.novell.x86_64.rpm


PHP
---

The Ice extension for PHP included in this distribution requires the
SLES10 php5 RPM, version 5.1.2-29.22 or greater (as long as the
greater version maintains binary compatibility). 

Note that php5 5.1.2-29.22 is not binary compatible with the php5 RPM
(version 5.1.2-29.5) included in the original SLES10 distribution.


======================================================================
Berkeley DB
======================================================================

This distribution includes the C++ and Java runtime for Berkeley DB
4.5.20. The Berkeley DB license is provided in the file 
THIRD_PARTY_LICENSE.


======================================================================
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 as shown in the bash command
below:

$ export PATH=$ICE_HOME/bin:$PATH

Ice shared libraries and executables in this distribution contain 
/opt/Ice-@mmver@/lib as the embedded runpath. In order to run Ice
services and tools, you can do one of the following:

 - Create a symbolic link /opt/Ice-@mmver@ that points to your Ice
   installation:

   $ ln -s $ICE_HOME /opt/Ice-@mmver@

 - Add $ICE_HOME/lib to your LD_LIBRARY_PATH environment variable:

   $ export LD_LIBRARY_PATH=$ICE_HOME/lib:$LD_LIBRARY_PATH

   With the x86_64 distribution, libraries are installed in 
   $ICE_HOME/lib64; if you use this distribution, set your 
   LD_LIBRARY_PATH as follows:

   $ export LD_LIBRARY_PATH=$ICE_HOME/lib64:$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

Use -L$ICE_HOME/lib64 instead of -L$ICE_HOME/lib for 64-bit builds.

Additional libraries are necessary if you are using an Ice service
such as IceGrid 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

To use the Java2 version of Ice instead, modify your CLASSPATH as
follows:

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

If you plan to use Freeze for persistence, you must also add the
Berkeley DB JAR file (db.jar) to your CLASSPATH:

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

In addition, the JVM requires that the directory containing the
Berkeley DB libraries be listed in java.library.path, therefore you
must add this directory to your LD_LIBRARY_PATH.

When using the Ice for Java SSL plugin (IceSSL), you may experience
occasional hangs. The most likely reason is that your system's entropy
pool is empty. If you have sufficient system privileges, you can solve
this issue by editing the following file

<java.home>/jre/lib/security/java.security

and changing it to use /dev/urandom instead of /dev/random. If you do
not have permission to modify the security file, you can also use the
command line option shown below:

$ java -Djava.security.egd=file:/dev/urandom MyClass ...

On SuSE Linux Enterprise Server, you may experience occasional hangs 
the first time an Ice object adapter is activated within a JVM. A 
work-around is to disable IPv6 support by setting the Java property 
java.net.preferIPv4Stack to true. For example:

$ java -Djava.net.preferIPv4Stack=true MyClass ...

For more information on this issue, refer to Sun's bug database:

  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6483406


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:$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

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

(With the x86_64 distribution, use <ICE_HOME>/lib64 instead of 
<ICE_HOME>/lib)

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.


======================================================================
Using the IceGrid Administrative Console
======================================================================

A Java-based graphical tool for administering IceGrid applications
is included in this distribution. The Java archive file is installed
as

$ICE_HOME/lib/IceGridGUI.jar

With a suitable Java installation, you can execute the application
using the following command:

$ java -jar IceGridGUI.jar


======================================================================
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/index.html for information on the documentation included with
this distribution.


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

Patch releases of Ice are binary compatible. For example, version
<x>.<y>.1 is compatible with <x>.<y>.0, so you can run applications
compiled with <x>.<y>.0 with the <x>.<y>.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 <x>.<y>.0 runtime will automatically use the
<x>.<y>.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 applications compiled with previous minor versions of
      Ice against a newer version of the Ice assemblies. For example,
      an application compiled with version <x>.<y>.0 of Ice cannot run
      with the <x>.<y>.1 Ice assemblies.