Skip to content

Latest commit

 

History

History
530 lines (376 loc) · 16.9 KB

BUILDING.md

File metadata and controls

530 lines (376 loc) · 16.9 KB

Building Ice for C++

This file describes how to build Ice for C++ from source and how to test the resulting build.

ZeroC provides Ice binary distributions for many platforms and compilers, including Windows and Visual Studio, so building Ice from source is usually unnecessary.

C++ Build Requirements

Operating Systems and Compilers

Ice was extensively tested using the operating systems and compiler versions listed on supported platforms.

On Windows, the build requires a recent version of Visual Studio. When building with Visual Studio 2017 you have to install Desktop development with C++ workload and select the optional component Windows 8.1 SDK and UCRT SDK.

Third-Party Libraries

Ice has dependencies on a number of third-party libraries:

  • bzip2 1.0
  • expat 2.1 or later
  • libedit (Linux and macOS)
  • LMDB 0.9 (LMDB is not required with the C++11 mapping)
  • mcpp 2.7.2 with patches
  • OpenSSL 1.0.0 or later (on AIX and Linux)

You do not need to build these packages from source.

AIX

OpenSSL (openssl.base) is provided by AIX. bzip2 and bzip2-devel are included in the IBM AIX Toolbox for Linux Applications.

ZeroC provide RPM packages for expat, LDMB and mcpp. You can install these packages as shown below:

sudo yum install https://zeroc.com/download/ice/3.7/aix7.2/ice-repo-3.7.aix7.2.noarch.rpm
sudo yum install expat-devel lmdb-devel mcpp-devel

The expat-devel package contains the static library libexpat-static.a built with xlc_r, together with header files and other development files.

Linux

Bzip, Expat, Libedit and OpenSSL are included with most Linux distributions.

ZeroC supplies binary packages for LMDB and mcpp for several Linux distributions that do not include them. You can install these packages as shown below:

Amazon Linux 2
sudo yum install https://zeroc.com/download/ice/3.7/amzn2/ice-repo-3.7.amzn2.noarch.rpm
sudo yum install lmdb-devel mcpp-devel
RHEL 8
sudo yum install https://zeroc.com/download/ice/3.7/el8/ice-repo-3.7.el8.noarch.rpm
sudo yum install lmdb-devel mcpp-devel
RHEL 7
sudo yum install https://zeroc.com/download/ice/3.7/el7/ice-repo-3.7.el7.noarch.rpm
sudo yum install lmdb-devel mcpp-devel
SLES 12
wget https://zeroc.com/download/ice/3.7/suse/zeroc-ice3.7.repo
sudo zypper addrepo zeroc-ice3.7.repo
sudo sudo rpm --import https://zeroc.com/download/GPG-KEY-zeroc-release-B6391CB2CFBA643D
sudo zypper install mcpp-devel

In addition, on Ubuntu and Debian distributions where the Ice for Bluetooth plug-in is supported, you need to install the following packages in order to build the IceBT transport plug-in:

These packages are provided with the system and can be installed with:

sudo apt-get install pkg-config libdbus-1-dev libbluetooth-dev

We have experienced problems with BlueZ versions up to and including 5.39, as well as 5.44 and 5.45. At this time we recommend using the daemon (bluetoothd) from BlueZ 5.43.

macOS

bzip, expat and libedit are included with your system.

You can install LMDB and mcpp using Homebrew:

brew install lmdb mcpp

Windows

ZeroC provides NuGet packages for all these third-party dependencies.

The Ice build system for Windows downloads and installs the NuGet command-line executable and the required NuGet packages when you build Ice for C++. The third-party packages are installed in the ice/cpp/msbuild/packages folder.

Building Ice for AIX, Linux or macOS

Review the top-level config/Make.rules in your build tree and update the configuration if needed. The comments in the file provide more information.

On AIX, add /opt/freeware/bin as the first element of your PATH:

export PATH=/opt/freeware/bin:$PATH

In a command window, change to the cpp subdirectory:

cd cpp

Run make to build the Ice C++ libraries, services and test suite. Set V=1 to get a more detailed build output. You can build only the libraries and services with the srcs target, or only the tests with the tests target. For example:

make V=1 -j8 srcs

The build system supports specifying additional preprocessor, compiler and linker options with the CPPFLAGS, CXXFLAGS and LDFLAGS variables. For example, to build the Ice C++98 mapping with -std=c++11, you can use:

make CXXFLAGS=-std=c++11

To build the test suite using a binary distribution use:

make ICE_BIN_DIST=all

If the binary distribution you are using is not installed in a system wide location where the C++ compiler can automatically find the header and library files, you also need to set ICE_HOME

make ICE_HOME=/opt/Ice-3.7.10 ICE_BIN_DIST=all

Build configurations and platforms

The C++ source tree supports multiple build configurations and platforms. To see the supported configurations and platforms:

make print V=supported-configs
make print V=supported-platforms

To build all the supported configurations and platforms:

make CONFIGS=all PLATFORMS=all -j8

C++11 mapping

The C++ source tree supports two different language mappings (C++98 and C++11). The default build uses the C++98 mapping. The C++11 mapping is a new mapping that uses new language features.

To build the C++11 mapping, use build configurations that are prefixed with cpp11, for example:

make CONFIGS=cpp11-shared -j8

Ice Xcode SDK (macOS only)

The build system supports building Xcode SDKs for Ice. These SDKs allow you to easily develop Ice applications with Xcode. To build Xcode SDKs, use the xcodesdk configurations. The Ice Builder for Xcode must be installed before building the SDKs:

make CONFIGS=xcodesdk -j8 srcs         # Build the C++98 mapping Xcode SDK
make CONFIGS=cpp11-xcodesdk -j8 srcs   # Build the C++11 mapping Xcode SDK

The Xcode SDKs are built into ice/sdk.

Building Ice for Windows

Build Using MSBuild

Open a Visual Studio command prompt. For example, with Visual Studio 2015, you can open one of:

  • VS2015 x86 Native Tools Command Prompt
  • VS2015 x64 Native Tools Command Prompt

Using the first Command Prompt produces Win32 binaries by default, while the second Command Prompt produces x64 binaries by default.

In the Command Prompt, change to the cpp subdirectory:

cd cpp

Now you're ready to build Ice:

msbuild /m msbuild\ice.proj

This builds the Ice for C++ SDK and the Ice for C++ test suite, with Release binaries for the default platform.

Set the MSBuild Configuration property to Debug to build debug binaries instead:

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

The Configuration property may be set to Debug or Release.

Set the MSBuild Platform property to Win32 or x64 to build binaries for a specific platform, for example:

msbuild /m msbuild\ice.proj /p:Configuration=Debug /p:Platform=x64

You can also skip the build of the test suite with the BuildDist target:

msbuild /m msbuild\ice.proj /t:BuildDist /p:Platform=x64

To build the test suite using the NuGet binary distribution use:

msbuild /m msbuild\ice.proj /p:ICE_BIN_DIST=all

You can also sign the Ice binaries with Authenticode, by setting the following environment variables:

  • SIGN_CERTIFICATE to your Authenticode certificate
  • SIGN_PASSWORD to the certificate password
  • SIGN_SHA1 the SHA1 hash of the signing certificate

Build Using Visual Studio

Open the Visual Studio solution that corresponds to the Visual Studio version you are using.

Restore the solution NuGet packages using the NuGet package manager, if the automatic download of packages during build is not enabled.

Using the configuration manager choose the platform and configuration you want to build.

The solution provide a project for each Ice component and each component can be built separately. When you build a component its dependencies are built automatically.

For Visual Studio 2019, Visual Studio 2017 and Visual Studio 2015, the solutions organize the projects in two solution folders, C++11 and C++98, which correspond to the C++11 and C++98 mappings. If you want to build all the C++11 mapping components, build the C++11 solution folder; likewise if you want to build all the C++98 mapping components, build the C++98 solution folder.

For Visual Studio 2013 and Visual Studio 2010. there is no separate solution folder because only the C++98 mapping is supported with these compilers.

The test suite is built using separate Visual Studio solutions:

The solution provides a separate project for each test component, the Cpp11-Release and Cpp11-Debug build configurations are setup to use the C++11 mapping in release and debug mode respectively, and are only supported with Visual Studio 2019, Visual Studio 2017 and Visual Studio 2015. The Release and Debug build configurations are setup to use the C++98 mapping in release and debug mode respectively.

The building of the test uses by default the local source build, and you must have built the Ice source with the same platform and configuration than you are attempting to build the tests.

For example to build the Cpp11-Release/x64 tests you must have built first the C++11 mapping using Release/x64.

It is also possible to build the tests using a C++ binary distribution, to do that you must set the ICE_BIN_DIST environment variable to all before starting Visual Studio.

Then launch Visual Studio and open the desired test solution, you must now use NuGet package manager to restore the NuGet packages, and the build will use Ice NuGet packages instead of your local source build.

Installing a C++ Source Build on AIX, Linux or macOS

Simply run make install. This will install Ice in the directory specified by the <prefix> variable in ../config/Make.rules.

After installation, make sure that the <prefix>/bin directory is in your PATH.

If you choose to not embed a runpath into executables at build time (see your build settings in ../config/Make.rules) or did not create a symbolic link from the runpath directory to the installation directory, you also need to add the library directory to your LD_LIBRARY_PATH (AIX, Linux) or DYLD_LIBRARY_PATH (macOS).

On an AIX system:

  • <prefix>/lib

On a Linux x86_64 system:

  • <prefix>/lib64 (RHEL, SLES, Amazon)
  • <prefix>/lib/x86_64-linux-gnu (Ubuntu)

On macOS:

  • <prefix>/lib

When compiling Ice programs, you must pass the location of the <prefix>/include directory to the compiler with the -I option, and the location of the library directory with the -L option.

If building a C++11 program, you must define the ICE_CPP11_MAPPING macro during compilation with the -D option (c++ -DICE_CPP11_MAPPING) and add the ++11 suffix to the library name when linking (such as -lIce++11).

Creating a NuGet Package on Windows

You can create a NuGet package with the following command:

msbuild msbuild\ice.proj /t:NuGetPack /p:BuildAllConfigurations=yes

This creates zeroc.ice.v100\zeroc.ice.v100.nupkg, zeroc.ice.v120\zeroc.ice.v120.nupkg, zeroc.ice.v140\zeroc.ice.v140.nupkg, zeroc.ice.v141\zeroc.ice.v141.nupkg, zeroc.ice.v142\zeroc.ice.v142.nupkg or zeroc.ice.v143\zeroc.ice.v143.nupkgdepending on the compiler you are using.

Cleaning the source build on AIX, Linux or macOS

Running make clean will remove the binaries created for the default configuration and platform.

To clean the binaries produced for a specific configuration or platform, you need to specify the CONFIGS or PLATFORMS variable. For example, make CONFIGS=cpp11-shared clean will clean the C++11 mapping build.

To clean the build for all the supported configurations and platforms, run make CONFIGS=all PLATFORMS=all clean.

Running make distclean will also clean the build for all the configurations and platforms. In addition, it will also remove the generated files created by the Slice compilers.

Running the Test Suite

AIX, Linux, macOS or Windows

Python is required to run the test suite. Additionally, the Glacier2 tests require the Python module passlib, which you can install with the command:

pip install passlib

After a successful source build, you can run the tests as follows:

python allTests.py # default config (C++98) and platform

For the C++11 mapping, you need to specify a C++11 config:

  • Linux/macOS
 python allTests.py --config=cpp11-shared # cpp11-shared config with the default platform
  • Windows C++11 debug builds
python allTests.py --config Cpp11-Debug
  • Windows C++11 release builds
python allTests.py --config Cpp11-Release

If everything worked out, you should see lots of ok messages. In case of a failure, the tests abort with failed.

iOS

The test scripts require Ice for Python. You can build Ice for Python from the python folder of this source distribution, or install the Python module zeroc-ice, using the following command:

pip install zeroc-ice

In order to run the test suite on iphoneos, you need to build the C++98 Test Controller app or C++11 Test Controller app from Xcode:

  • Build the test suite with make for the xcodedsk or cpp11-xcodesdk configuration, and the iphoneos platform.
  • Open the C++ Test Controller project located in the cpp/test/ios/controller directory.
  • Build the C++98 Test Controller or the C++11 Test Controller app (it must match the configuration(s) selected when building the test suite).

iOS Simulator

  • C++98 controller
python allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app
  • C++11 controller
python allTests.py --config=cpp11-xcodesdk --platform=iphonesimulator --controller-app

iOS Device

  • Start the C++98 Test Controller or the C++11 Test Controller app on your iOS device, from Xcode.

  • Start the C++98 controller on your Mac:

python allTests.py --config=xcodesdk --platform=iphoneos
  • Start the C++11 controller on your Mac:
python allTests.py --config=cpp11-xcodesdk --platform=iphoneos

All the test clients and servers run on the iOS device, not on your Mac computer.