• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..05-Feb-2019-

config/H05-Feb-2019-656548

doxygen/H05-Feb-2019-4,8813,772

include/H05-Feb-2019-28,14115,312

msbuild/H03-May-2022-13,60513,290

src/H05-Feb-2019-372,525318,698

test/H05-Feb-2019-267,118243,959

.gitignoreH A D05-Feb-20198 32

MakefileH A D05-Feb-20191.5 KiB3817

README.mdH A D05-Feb-201917.6 KiB506387

allTests.pyH A D05-Feb-2019228 124

README.md

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