Skip to content

Latest commit

 

History

History
421 lines (295 loc) · 12.7 KB

BUILDING.md

File metadata and controls

421 lines (295 loc) · 12.7 KB
Raw

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 Visual Studio 2022.

Third-Party Libraries

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

You do not need to build these packages from source.

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 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.

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.

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.8.0 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

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++ 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 2022, you can open one of:

  • VS2022 x86 Native Tools Command Prompt
  • VS2022 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.

The test suite is built using separate Visual Studio solutions:

The solution provides a separate project for each test component. the Release and Debug build configurations are setup build 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 Release/x64 tests you must have built the C++ 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 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 (Linux) or DYLD_LIBRARY_PATH (macOS).

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.

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.v143\zeroc.ice.v143.nupkg.

Cleaning the source build on 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=static clean will clean the static configuration 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

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:

python3 -m pip install passlib

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

python allTests.py # default config and platform

### iOS

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

```shell
python3 -m pip install zeroc-ice

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

  • Build the test suite with make for the xcodedsk configuration, and the iphoneos platform.
  • Open the C++ Test Controller project located in the cpp/test/ios/controller directory.
  • Build the C++ Test Controller app.

iOS Simulator

  • C++ controller
python3 allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app

iOS Device

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

  • Start the C++ controller on your Mac:

python3 allTests.py --config=xcodesdk --platform=iphoneos

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