Building Ice for MATLAB

This document describes how to build and install Ice for MATLAB from source.

ZeroC provides Ice for MATLAB toolboxes for all recent versions of MATLAB on Windows, so building Ice for MATLAB from source is usually unnecessary.

• Prerequisites
• Build Instructions
• Packaging the Ice Toolbox
• Using Ice for MATLAB
  • Search Path
  • Slice Files
  • Loading the Library
  • Running the Tests
    • Running the Tests Manually
    • Running the Automated Tests

Prerequisites

The build system requires MATLAB 2016a or later for Windows, Visual Studio 2015 and a Perl installation.

Build Instructions

Open a Visual Studio x64 command prompt, VS2015 x64 Native Tools Command Prompt. In this Command Prompt, change to the matlab subdirectory:

cd matlab

Now you're ready to build Ice for MATLAB:

msbuild msbuild\ice.proj

To build in debug mode instead:

msbuild msbuild\ice.proj /p:Configuration=Debug

Upon completion, a build in release mode generates the following components:

• Ice for C++11 libraries, located in cpp\bin\x64\Release
• slice2matlab executable, located in cpp\bin\x64\Release
• ice.mexw64 MEX file, located in matlab\lib\x64\Release
• Prototype and thunk files, located in matlab\lib\x64\Release
• MATLAB code for core Slice files, located in matlab\lib\generated
• MATLAB code for test Slice files, located in matlab\test\**\generated

The MATLAB extension depends on Ice for C++ components from the cpp subdirectory, and those are built if required. It is also possible to build the MATLAB extension using Ice C++ NuGet packages by setting the ICE_BIN_DIST msbuild property to cpp:

msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp

Packaging the Ice Toolbox

Use the following command to build the Ice toolbox package:

msbuild msbuild\ice.proj /t:Package

This creates the toolbox package msbuild\ice-<Ice Version>-<MATLAB Version>.mltbx.

You can install the toolbox from within MATLAB by double-clicking on the file.

Using Ice for MATLAB

Search Path

To use a source build, add the following directories to your MATLAB path:

• matlab\lib
• matlab\lib\generated
• matlab\lib\x64\Release

Slice Files

Use slice2matlab to compile your Slice files. Run slice2matlab -h for a description of its command-line options. You can place the generated *.m files anywhere you like, but the enclosing directory must be in your MATLAB path.

Loading the Library

The Ice for MATLAB library can be loaded with this command:

loadlibrary('ice', @iceproto)

The MEX file depends on bzip2.dll and several Ice DLLs that are part of the Ice for C++ distribution. The build copies all DLL dependencies to the matlab\lib\x64\Release directory.

Running the Tests

The Ice for MATLAB tests are located in matlab\test.

Since Ice for MATLAB only supports client functionality, you need test servers from a different language mapping.

Running the Tests Manually

In a Command Prompt, start a test server from your chosen server language mapping.

In MATLAB, change to a test directory:

cd matlab\test\...

Now you can start the MATLAB test client. Assuming the server is running on the same host, use this command:

client({})

If you started the server on a different host, use this command instead:

client({'--Ice.Default.Host=<addr>'})

Replace <addr> with the host name or IP address of the server host.

Running the Automated Tests

Assuming you've installed Ice for Python, run allTests.py:

python allTests.py

This script automatically starts a Python server for each MATLAB client. MATLAB clients are executed using a minimized MATLAB interpreter and the test output is copied to the Command Prompt window.