1# Building Ice for C++ 2 3This file describes how to build Ice for C++ from source and how to test the 4resulting build. 5 6ZeroC provides [Ice binary distributions][1] for many platforms and compilers, 7including Windows and Visual Studio, so building Ice from source is usually 8unnecessary. 9 10* [C++ Build Requirements](#c-build-requirements) 11 * [Operating Systems and Compilers](#operating-systems-and-compilers) 12 * [Third-Party Libraries](#third-party-libraries) 13 * [Linux](#linux) 14 * [macOS](#macos) 15 * [Windows](#windows) 16* [Building Ice for Linux or macOS](#building-ice-for-linux-or-macos) 17 * [Build configurations and platforms](#build-configurations-and-platforms) 18 * [C++11 mapping](#c11-mapping) 19 * [Ice Xcode SDK (macOS only)](#ice-xcode-sdk-macos-only) 20* [Building Ice for Windows](#building-ice-for-windows) 21* [Building Ice for Universal Windows (UWP)](#building-ice-for-universal-windows-uwp) 22* [Installing a C++ Source Build on Linux or macOS](#installing-a-c-source-build-on-linux-or-macos) 23* [Creating a NuGet Package on Windows](#creating-a-nuget-package-on-windows) 24* [Running the Test Suite](#running-the-test-suite) 25 * [Linux, macOS or Windows](#linux-macos-or-windows) 26 * [iOS](#ios) 27 * [Universal Windows](#universal-windows) 28 29## C++ Build Requirements 30 31### Operating Systems and Compilers 32 33Ice was extensively tested using the operating systems and compiler versions 34listed on [supported platforms][2]. 35 36On Windows, the build requires a recent version of Visual Studio, and the 37Windows 10 SDK (10.0.14393.0) component when building with Visual Studio 2017. 38 39### Third-Party Libraries 40 41Ice has dependencies on a number of third-party libraries: 42 43 - [bzip][3] 1.0 44 - [expat][4] 2.1 or later 45 - [LMDB][5] 0.9 (LMDB is not required with the C++11 mapping) 46 - [mcpp][6] 2.7.2 with patches 47 - [OpenSSL][7] 1.0.0 or later (only on Linux) 48 49You do not need to build these packages from source. 50 51#### Linux 52 53Bzip, Expat and OpenSSL are included with most Linux distributions. 54 55ZeroC supplies binary packages for LMDB and mcpp for several Linux distributions 56that do not include them. You can install these packages as shown below: 57 58##### Amazon Linux 59``` 60wget https://zeroc.com/download/GPG-KEY-zeroc-release-B6391CB2CFBA643D 61sudo rpm --import GPG-KEY-zeroc-release-B6391CB2CFBA643D 62cd /etc/yum.repos.d 63sudo wget https://zeroc.com/download/Ice/3.7/amzn1/zeroc-ice3.7.repo 64sudo yum install lmdb-devel mcpp-devel 65``` 66##### RHEL 7 67``` 68wget https://zeroc.com/download/GPG-KEY-zeroc-release-B6391CB2CFBA643D 69sudo rpm --import GPG-KEY-zeroc-release-B6391CB2CFBA643D 70cd /etc/yum.repos.d 71sudo wget https://zeroc.com/download/Ice/3.7/el7/zeroc-ice3.7.repo 72sudo yum install lmdb-devel mcpp-devel 73``` 74##### SLES 12 75``` 76wget https://zeroc.com/download/GPG-KEY-zeroc-release-B6391CB2CFBA643D 77sudo rpm --import GPG-KEY-zeroc-release-B6391CB2CFBA643D 78sudo wget https://zeroc.com/download/Ice/3.7/sles12/zeroc-ice3.7.repo 79sudo zypper ar -f --repo zeroc-ice3.7.repo 80sudo zypper install mcpp-devel 81``` 82 83In addition, on Ubuntu and Debian distributions where the Ice for Bluetooth 84plug-in is supported, you need to install the following packages in order to 85build the IceBT transport plug-in: 86 87 - [pkg-config][8] 0.29 or later 88 - [D-Bus][9] 1.10 or later 89 - [BlueZ][10] 5.37 or later 90 91These packages are provided with the system and can be installed with: 92``` 93sudo apt-get install pkg-config libdbus-1-dev libbluetooth-dev 94``` 95 96> *We have experienced problems with BlueZ versions up to and including 5.39, as 97well as 5.44 and 5.45. At this time we recommend using the daemon (`bluetoothd`) 98from BlueZ 5.43.* 99 100#### macOS 101 102Expat and bzip are included with your system. 103 104You can install LMDB and mcpp using Homebrew: 105``` 106brew install lmdb mcpp 107``` 108 109#### Windows 110 111ZeroC provides NuGet packages for all these third-party dependencies. 112 113The Ice build system for Windows downloads and installs the NuGet command-line 114executable and the required NuGet packages when you build Ice for C++. The 115third-party packages are installed in the `ice/cpp/msbuild/packages` folder. 116 117## Building Ice for Linux or macOS 118 119Review the top-level [config/Make.rules](../config/Make.rules) in your build 120tree and update the configuration if needed. The comments in the file provide 121more information. 122 123In a command window, change to the `cpp` subdirectory: 124``` 125cd cpp 126``` 127Run `make` to build the Ice C++ libraries, services and test suite. Set `V=1` to 128get a more detailed build output. You can build only the libraries and services 129with the `srcs` target, or only the tests with the `tests` target. For example: 130``` 131make V=1 -j8 srcs 132``` 133 134The build system supports specifying additional preprocessor, compiler and 135linker options with the `CPPFLAGS`, `CXXFLAGS` and `LDFLAGS` variables. For 136example, to build the Ice C++98 mapping with `-std=c++11`, you can use: 137``` 138make CXXFLAGS=-std=c++11 139``` 140 141### Build configurations and platforms 142 143The C++ source tree supports multiple build configurations and platforms. To 144see the supported configurations and platforms: 145``` 146make print V=supported-configs 147make print V=supported-platforms 148``` 149To build all the supported configurations and platforms: 150``` 151make CONFIGS=all PLATFORMS=all -j8 152``` 153 154### C++11 mapping 155 156The C++ source tree supports two different language mappings (C++98 and C++11). 157The default build uses the C++98 mapping. The C++11 mapping is a new mapping 158that uses new language features. 159 160To build the C++11 mapping, use build configurations that are prefixed with 161`cpp11`, for example: 162``` 163make CONFIGS=cpp11-shared -j8 164``` 165### Ice Xcode SDK (macOS only) 166 167The build system supports building Xcode SDKs for Ice. These SDKs allow you to 168easily develop Ice applications with Xcode. To build Xcode SDKs, use the 169`xcodesdk` configurations: 170``` 171make CONFIGS=xcodesdk -j8 srcs # Build the C++98 mapping Xcode SDK 172make CONFIGS=cpp11-xcodesdk -j8 srcs # Build the C++11 mapping Xcode SDK 173``` 174The Xcode SDKs are built into `ice/sdk`. 175 176## Building Ice for Windows 177 178### Build Using MSBuild 179 180Open a Visual Studio command prompt. For example, with Visual Studio 2015, you 181can open one of: 182 183- VS2015 x86 Native Tools Command Prompt 184- VS2015 x64 Native Tools Command Prompt 185 186Using the first Command Prompt produces `Win32` binaries by default, while 187the second Command Promt produces `x64` binaries by default. 188 189In the Command Prompt, change to the `cpp` subdirectory: 190``` 191cd cpp 192``` 193 194Now you're ready to build Ice: 195``` 196msbuild /m msbuild\ice.proj 197``` 198 199This builds the Ice for C++ SDK and the Ice for C++ test suite, with 200Release binaries for the default platform. 201 202Set the MSBuild `Configuration` property to `Debug` to build debug binaries 203instead: 204``` 205msbuild /m msbuild\ice.proj /p:Configuration=Debug 206``` 207 208The `Configuration` property may be set to `Debug` or `Release`. 209 210Set the MSBuild `Platform` property to `Win32` or `x64` to build binaries 211for a specific platform, for example: 212``` 213msbuild /m msbuild\ice.proj /p:Configuration=Debug /p:Platform=x64 214``` 215 216You can also skip the build of the test suite with the `BuildDist` target: 217``` 218msbuild /m msbuild\ice.proj /t:BuildDist /p:Platform=x64 219``` 220 221To build the test suite using the NuGet binary distribution use: 222``` 223msbuild /m msbuild\ice.proj /p:ICE_BIN_DIST=all 224``` 225 226You can also sign the Ice binaries with Authenticode, by setting the following 227environment variables: 228 229 - `SIGN_CERTIFICATE` to your Authenticode certificate 230 - `SIGN_PASSWORD` to the certificate password 231 232### Build Using Visual Studio 233 234Open the Visual Studio solution that corresponds to the Visual Studio version you 235are using. 236 237 - For Visual Studio 2017 use [msbuild/ice.v141.sln](./msbuild/ice.v141.sln) 238 - For Visual Studio 2015 use [msbuild/ice.v140.sln](./msbuild/ice.v140.sln) 239 - For Visual Studio 2013 use [msbuild/ice.v120.sln](./msbuild/ice.v120.sln) 240 - For Visual Studio 2010 use [msbuild/ice.v100.sln](./msbuild/ice.v100.sln) 241 242Restore the solution NuGet packages using the NuGet package manager, if the automatic 243download of packages during build is not enabled. 244 245Using the configuration manager choose the platform and configuration you want to build. 246 247The solution provide a project for each Ice component and each component can be built 248separatelly. When you build a component its dependencies are built automatically. 249 250For Visual Studio 2017 and Visual Studio 2015, the solutions organize the projects in two 251solution folders, C++11 and C++98, which correspond to the C++11 and C++98 mappings. If you 252want to build all the C++11 mapping components, build the C++11 solution folder; 253likewise if you want to build all the C++98 mapping components, build the C++98 254solution folder. 255 256For Visual Studio 2013 and Visual Studio 2010. there is no separate solution folder because 257only the C++98 mapping is supported with these compilers. 258 259The test suite is built using separate Visual Studio solutions: 260 261 - Ice Test Suite for Visual Studio 2017, Visual Studio 2015 and Visual Studio 2013 [msbuild/ice.test.sln](./msbuild/ice.test.sln) 262 - Ice Test Suite for Visual Studio 2010 [msbuild/ice.test.v100.sln](./msbuild/ice.test.v100.sln) 263 - Ice OpenSSL Test Suite for Visual Studio 2017, Visual Studio 2015 and Visual Studio 2013 [msbuild/ice.openssl.test.sln](./msbuild/ice.openssl.test.sln) 264 265The solution provides a separate project for each test component, the `Cpp11-Release` and `Cpp11-Debug` build 266configurations are setup to use the C++11 mapping in release and debug mode respectively, and are only supported 267with Visual Studio 2017 and Visual Studio 2015. The `Release` and `Debug` build configurations are setup to 268use the C++98 mapping in release and debug mode respectively. 269 270The building of the test uses by default the local source build, and you must have built the Ice 271source with the same platform and configuration than you are attemping to build the tests. 272 273For example to build the `Cpp11-Release/x64` tests you must have built first the C++11 mapping 274using `Release/x64`. 275 276It is also possible to build the tests using a C++ binary distribution, to do that you must 277set the `ICE_BIN_DIST` environment variable to `all` before starting Visual Studio. 278 279Then launch Visual Studio and open the desired test solution, you must now use NuGet package 280manager to restore the NuGet packages, and the build will use Ice NuGet packages instead of 281your local source build. 282 283## Building Ice for Universal Windows (UWP) 284 285### Build Using MSBuild 286 287The steps are the same as for Building Ice for Windows above, except you must also 288use a `UWP` target. 289 290To build Ice for UWP: 291``` 292msbuild msbuild\ice.proj /t:UWPBuild 293``` 294 295To skip the building of the test suite: 296``` 297msbuild msbuild\ice.proj /t:UWPBuildDist 298``` 299 300To build the test suite using the NuGet binary distribution use: 301``` 302msbuild msbuild\ice.proj /t:UWPBuild /p:ICE_BIN_DIST=all 303``` 304 305### Build Using Visual Studio 306 307Before building Ice for UWP using Visual Studio you must build the slice2cpp compiler 308from the C++98 mapping, refer to [Building Ice for Windows](#building-ice-for-windows). 309 310Using either Visual Studio 2017 or Visual Studio 2015, open the [msbuild/ice.uwp.sln](./msbuild/ice.uwp.sln) 311 312Choose the platform and configuration you want to build using the configuration manager. 313 314The solution provides a project for each Ice component and each component can be built 315separately. When you build a component, its dependencies are built automatically. 316 317The test suite is built using a separate Visual Studio solution [msbuild/ice.testuwp.sln](./msbuild/ice.testuwp.sln). 318This solution includes a project for each test and a project for the UWP test controller 319required to run the test suite. 320 321It is also possible to build the tests using a C++ binary distribution, to do that you must 322set `ICE_BIN_DIST` environment variable to `all` before starting Visual Studio. 323 324Then launch Visual Studio and open the [msbuild/ice.testuwp.sln](./msbuild/ice.testuwp.sln) solution, 325you must now use NuGet package manager to restore the NuGet packages, and the build will use 326Ice NuGet packages instead of your local source build. 327 328## Installing a C++ Source Build on Linux or macOS 329 330Simply run `make install`. This will install Ice in the directory specified by 331the `<prefix>` variable in `../config/Make.rules`. 332 333After installation, make sure that the `<prefix>/bin` directory is in your 334`PATH`. 335 336If you choose to not embed a `runpath` into executables at build time (see your 337build settings in `../config/Make.rules`) or did not create a symbolic link from 338the `runpath` directory to the installation directory, you also need to add the 339library directory to your `LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (macOS). 340 341On a Linux x86_64 system: 342``` 343<prefix>/lib64 (RHEL, SLES, Amazon) 344<prefix>/lib/x86_64-linux-gnu (Ubuntu) 345``` 346 347On macOS: 348``` 349<prefix>/lib 350``` 351 352When compiling Ice programs, you must pass the location of the 353`<prefix>/include` directory to the compiler with the `-I` option, and the 354location of the library directory with the `-L` option. 355 356If building a C++11 program, you must define the `ICE_CPP11_MAPPING` macro 357during compilation with the `-D` option (`c++ -DICE_CPP11_MAPPING`) and add the 358`++11` suffix to the library name when linking (such as `-lIce++11`). 359 360## Creating a NuGet Package on Windows 361 362You can create a NuGet package with the following command: 363``` 364msbuild msbuild\ice.proj /t:NuGetPack /p:BuildAllConfigurations=yes 365``` 366 367This creates `zeroc.ice.v100\zeroc.ice.v100.nupkg`, 368`zeroc.ice.v120\zeroc.ice.v120.nupkg`, `zeroc.ice.v140\zeroc.ice.v140.nupkg` or 369`zeroc.ice.v141\zeroc.ice.v141.nupkg` 370depending on the compiler you are using. 371 372To create UWP NuGet packages, use the `UWPNuGetPack` target instead: 373``` 374msbuild msbuild\ice.proj /t:UWPNuGetPack /p:BuildAllConfigurations=yes 375``` 376 377This creates: `zeroc.ice.uwp.v140\zeroc.ice.uwp.v140.nupkg`, 378`zeroc.ice.uwp.v140.x64\zeroc.ice.uwp.v140.x64.nupkg` and 379`zeroc.ice.uwp.v140.x86\zeroc.ice.uwp.v140.x86.nupkg` for Visual Studio 2015 380builds or `zeroc.ice.uwp.v141\zeroc.ice.uwp.v141.nupkg`, 381`zeroc.ice.uwp.v141.x64\zeroc.ice.uwp.v141.x64.nupkg` and 382`zeroc.ice.uwp.v141.x86\zeroc.ice.uwp.v141.x86.nupkg` for Visual Studio 2017 383builds. 384 385## Cleaning the source build on macOS or Linux 386 387Running `make clean` will remove the binaries created for the default 388configuration and platform. 389 390To clean the binaries produced for a specific configuration or platform, you 391need to specify the `CONFIGS` or `PLATFORMS` variable. For example, 392`make CONFIGS=cpp11-shared clean` will clean the C++11 mapping build. 393 394To clean the build for all the supported configurations and platforms, run 395`make CONFIGS=all PLATFORMS=all clean`. 396 397Running `make distclean` will also clean the build for all the configurations 398and platforms. In addition, it will also remove the generated files created by 399the Slice translators. 400 401## Running the Test Suite 402 403Python is required to run the test suite. Additionally, the Glacier2 tests 404require the Python module `passlib`, which you can install with the command: 405``` 406pip install passlib 407``` 408 409### Linux, macOS or Windows 410 411After a successful source build, you can run the tests as follows: 412``` 413python allTests.py # default config (C++98) and platform 414``` 415 416For the C++11 mapping, you need to specify a C++11 config: 417 418* Linux/macOS 419``` 420 python allTests.py --config=cpp11-shared # cpp11-shared config with the default platform 421``` 422 423* Windows C++11 debug builds 424``` 425python allTests.py --config Cpp11-Debug 426``` 427 428* Windows C++11 release builds 429``` 430python allTests.py --config Cpp11-Release 431``` 432 433If everything worked out, you should see lots of `ok` messages. In case of a 434failure, the tests abort with `failed`. 435 436### iOS 437 438The test scripts require Ice for Python. You can build Ice for Python from 439the [python](../python) folder of this source distribution, or install the 440Python module `zeroc-ice`, using the following command: 441``` 442pip install zeroc-ice 443``` 444 445In order to run the test suite on `iphoneos`, you need to build the 446C++98 Test Controller app or C++11 Test Controller app from Xcode: 447 - Build the test suite with `make` for the `xcodedsk` or `cpp11-xcodesdk` 448 configuration, and the `iphoneos` platform. 449 - Open the C++ Test Controller project located in the 450 `cpp/test/ios/controller` directory. 451 - Build the `C++98 Test Controller` or the `C++11 Test Controller` app (it must 452 match the configuration(s) selected when building the test suite). 453 454#### iOS Simulator 455 - C++98 controller 456``` 457python allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app 458``` 459 - C++11 controller 460``` 461python allTests.py --config=cpp11-xcodesdk --platform=iphonesimulator --controller-app 462``` 463 464#### iOS 465 - Start the `C++98 Test Controller` or the `C++11 Test Controller` app on your 466 iOS device, from Xcode. 467 468 - Start the C++98 controller on your Mac: 469``` 470python allTests.py --config=xcodesdk --platform=iphoneos 471``` 472 - Start the C++11 controller on your Mac: 473``` 474python allTests.py --config=cpp11-xcodesdk --platform=iphoneos 475``` 476 477All the test clients and servers run on the iOS device, not on your Mac computer. 478 479### Universal Windows 480 481The test scripts require Ice for Python. You can build Ice for Python from 482the [python](../python) folder of this source distribution, or install the 483Python module `zeroc-ice`, using the following command: 484``` 485pip install zeroc-ice 486``` 487 488You can run the testsuite from the console using python: 489``` 490python allTests.py --uwp --controller-app --platform x64 --config Release 491``` 492 493If everything worked out, you should see lots of `ok` messages. In case of a 494failure, the tests abort with `failed`. 495 496[1]: https://zeroc.com/distributions/ice 497[2]: https://doc.zeroc.com/display/Rel/Supported+Platforms+for+Ice+3.7.2 498[3]: https://github.com/zeroc-ice/bzip2 499[4]: https://libexpat.github.io 500[5]: https://symas.com/lightning-memory-mapped-database/ 501[6]: https://github.com/zeroc-ice/mcpp 502[7]: https://www.openssl.org/ 503[8]: https://www.freedesktop.org/wiki/Software/pkg-config 504[9]: https://www.freedesktop.org/wiki/Software/dbus 505[10]: http://www.bluez.org 506