Using the macOS Binary Distribution for Ice 3.6.3

This page provides important information for users of the Ice binary distribution for macOS.

On this page:

Overview of the macOS binary distribution

Ice for C++, Java, Objective-C, and PHP on macOS are provided through Homebrew. The ice formula includes the following components by default:

  • Run-time libraries for C++, Objective-C and PHP
  • Run-time libraries for the Freeze service in C++
  • Executables for IceGrid, IceStorm, Glacier2, and IcePatch2 services
  • Tools and libraries for developing Ice applications

More information about Homebrew is available at http://brew.sh.

By default, the ice formula does build any Java component - this includes Ice for Java, the Freeze service for Java, and the IceGrid Admin graphical tool.

Back to Top ^

Installing the macOS binary distribution

Using Homebrew, you can install the distribution with this command:

brew install ice [--with-java]

The --with-java option builds the Java components and the IceGrid Admin app. You can also install IceGrid Admin on its own by downloading IceGrid Admin.dmg.

Alternatively, you can install Ice from ZeroC's Homebrew tap.

Back to Top ^

Setting up your macOS environment to use Ice

After installing Ice, read the relevant language-specific sections below to learn how to configure your environment and start programming with Ice.

C++

Xcode Builder

We recommend installing the Ice Builder for Xcode, which automates the compilation of Slice files to C++ and Objective-C.

Compiling and Linking

The distribution includes libraries built with LLVM libc++. These libraries also support C++11 applications when compiled with the --std=c++11 option. 

When compiling Ice for C++ programs, you must pass the -pthread option. A typical compile command would look like this:

c++ -c -pthread myprogram.cpp

When linking a program you must link with at least libIce and libIceUtil. A typical link command would look like this:

c++ -o myprogram myprogram.o -lIce -lIceUtil

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

If you want to include Ice in your application bundle, you will need to copy the necessary Ice libraries to the Contents/Frameworks subdirectory of your bundle and use  @loader_path/../Frameworks as the run path when linking the application.

Please refer to the dyld man page on your macOS system to learn more about @loader_path.

Back to Top ^

Objective-C

Xcode Builder

We recommend installing the Ice Builder for Xcode, which automates the compilation of Slice files to C++ and Objective-C.

Compiling and Linking

When compiling Ice for Objective-C programs, you must pass the -pthread option. A typical compile command would look like this:

cc -c -pthread myprogram.m

When linking a program you must link with libIceObjC. A typical link command would look like this:

cc -o myprogram myprogram.o -lIceObjC -framework Foundation

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

If you want to include Ice in your application bundle, you will need to copy the necessary Ice libraries to the Contents/Frameworks subdirectory of your bundle and use  @loader_path/../Frameworks as the run path when linking the application.

Please refer to the dyld man page on your macOS system to learn more about @loader_path.

Back to Top ^

PHP

The macOS distribution includes the Ice extension for PHP and the Slice-to-PHP compiler (slice2php).

The PHP interpreter loads the Ice extension automatically when you add the following directive to /etc/php.ini:

extension=/usr/local/php/extensions/IcePHP.dy

Additional configuration directives can also be added to /etc/php.ini.

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.

Your application will also need to include at least some of the Ice for PHP run-time source files (installed in /usr/local/lib/share/php). You can modify the include_path setting in php.ini to add the installation directory:

include_path = /usr/local/lib/share/php:...

Another option is to modify the include path from within your script prior to including any Ice run-time file:

PHP
ini_set('include_path', ini_get('include_path') . PATH_SEPARATOR . '/usr/local/opt/ice/lib/share/php');
require 'Ice.php'; // Load the core Ice run time definitions.

Java

Gradle Builder

Developers can use the Ice Builder for Gradle to simplify their Java projects. The builder is not included in the distribution and must be installed separately.

JAR Files

The preferred way to use Ice for Java is to configure your build environment to fetch the build artifacts from the ZeroC Maven repository located at:

http://repo.zeroc.com/nexus/content/repositories/releases

You can create Java apps with Ice for Java on macOS without installing Ice for Java. The Slice-to-Java (slice2java) compiler is always included in your Ice installation, even if you did not install Ice using the --with-java option.

The --with-java option is necessary only if you develop with Freeze for Java.

The Maven package ids are as follows:

  • groupId=com.zeroc, version=3.6.3, artifactId=ice, 
  • groupId=com.zeroc, version=3.6.3, artifactId=freeze
  • groupId=com.zeroc, version=3.6.3, artifactId=glacier2
  • groupId=com.zeroc, version=3.6.3, artifactId=icebox
  • groupId=com.zeroc, version=3.6.3, artifactId=icediscovery
  • groupId=com.zeroc, version=3.6.3, artifactId=icegrid
  • groupId=com.zeroc, version=3.6.3, artifactId=icelocatordiscovery
  • groupId=com.zeroc, version=3.6.3, artifactId=icepatch2
  • groupId=com.zeroc, version=3.6.3, artifactId=icestorm

If you cannot fetch the Ice for Java artifacts from the ZeroC Maven repository, the Ice JAR files are installed locally in /usr/local/share/java when you install Ice using the --with-java option. The JAR files are named as follows:

  • ice-3.6.3.jar
  • freeze-3.6.3.jar
  • glacier2-3.6.3.jar
  • icebox-3.6.3.jar
  • icediscovery-3.6.3.jar
  • icegrid-3.6.3.jar
  • icelocatordiscovery-3.6.3.jar
  • icepatch2-3.6.3.jar
  • icestorm-3.6.3.jar

Freeze and Berkeley DB

In order to use Freeze for Java, you need to add both freeze-3.6.3.jar and the Berkeley DB JAR file (db.jar) to your build path.

ZeroC's Maven Repository does not provide db.jar, as this JAR file is a wrapper for a C library. Both db.jar and the associated C library are built and installed when you install Ice from Homebrew with the --with-java option.   

Bzip2

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 http://www.kohsuke.org/bzip2.

You can also retrieve this bzip2 JAR file from ZeroC's Maven repository located at http://repo.zeroc.com/nexus/content/repositories/thirdparty

The Maven package id for the bzip2 JAR file is as follows:

  • groupId=org.apache.tools, version=1.0, artifactId=bzip2

These classes are a pure Java implementation of the bzip2 algorithm and therefore add significant latency to Ice requests.

Back to Top ^

Berkeley DB utilities

Berkeley DB utilities are installed in/usr/local/opt/ice/libexec/bin. You may add this directory to your PATH, or call the executables directly.

Back to Top ^

Using the sample programs on macOS

Sample programs for all programming languages are available in a separate GitHub repository. Simply clone this repository and use its 3.6 branch:

git clone -b 3.6 https://github.com/zeroc-ice/ice-demos.git
cd ice-demos

Back to Top ^

Starting IceGrid Admin on macOS

You can launch IceGrid Admin with the IceGridAdmin application installed in your /Applications directory. This app is a Java program and requires JRE 7u6 or later.

Back to Top ^