README.md
1# Building Ice for Objective-C on macOS
2
3This page describes how to build and install Ice for Objective-C from source
4code on macOS. If you prefer, you can install a [Homebrew][1] package instead.
5
6* [Objective\-C Build Requirements](#objective-c-build-requirements)
7 * [Operating Systems and Compilers](#operating-systems-and-compilers)
8* [Building Ice for Objective\-C](#building-ice-for-objective-c)
9 * [Build configurations and platforms](#build-configurations-and-platforms)
10 * [Ice Xcode SDK](#ice-xcode-sdk)
11* [Installing an Objective\-C Source Build](#installing-an-objective-c-source-build)
12* [Building the Test Suite](#building-the-test-suite)
13* [Running the Test Suite](#running-the-test-suite)
14 * [macOS](#macos)
15 * [iOS Simulator](#ios-simulator)
16 * [iOS](#ios)
17
18## Objective-C Build Requirements
19
20### Operating Systems and Compilers
21
22Ice for Objective-C is currently only supported on macOS and iOS, and was
23extensively tested using the operating system and compiler versions listed for
24our [supported platforms][2].
25
26## Building Ice for Objective-C
27
28The build of Ice for Objective-C requires that you first build Ice for C++ in
29the `cpp` subdirectory for the same configuration(s) and platform(s).
30
31Review the top-level [config/Make.rules](../config/Make.rules) in your build
32tree and update the configuration if needed. The comments in the file provide
33more information.
34
35Change to the Ice for Objective-C source subdirectory:
36```
37 cd objective-c
38```
39Run `make` to build the Ice Objective-C libraries and test suite. Set `V=1` to
40get a more detailed build output. You can build only the libraries with the
41`srcs` target, or only the tests with the `tests` target. For example:
42```
43 make V=1 -j8 srcs
44```
45
46### Build configurations and platforms
47
48The Objective-C source tree supports multiple build configurations and
49platforms. To see the supported configurations and platforms:
50```
51 make print V=supported-configs
52 make print V=supported-platforms
53```
54To build all the supported configurations and platforms:
55```
56 make CONFIGS=all PLATFORMS=all -j8
57```
58The `arc-` configurations (for [Automatic Reference Counting][3]) apply only to
59the test suite; the Ice libraries don't use these configurations, and the same
60Ice for Objective-C library can be used with and without ARC.
61
62### Ice Xcode SDK
63
64The build system supports building Xcode SDKs for Ice. These SDKs allow you to
65easily develop Ice applications with Xcode. To build Xcode SDKs, use the
66`xcodesdk` configurations:
67```
68 make CONFIGS=xcodesdk -j8 srcs # Build the Objective-C mapping Xcode SDK
69 # for the default platform
70```
71The Xcode SDKs are built into `ice/sdk`.
72
73## Installing an Objective-C Source Build
74
75Simply run `make install`. This will install Ice in the directory specified by
76the `prefix` variable in `../config/Make.rules`.
77
78When compiling Ice programs, you must pass the location of the
79`<prefix>/include` directory to the compiler with the `-I` option, and the
80location of the library directory with the `-L` option.
81
82## Building the Test Suite
83
84`make all` or `make tests` builds the test suite for the platform(s) and
85configuration(s) you selected.
86
87However, in order to run the test suite on `iphoneos`, you need to build the
88Objective-C Controller app from Xcode:
89 - Open the Objective-C Test Controller project located in the
90 `objective-c/test/ios/controller` directory.
91 - Build the `Objective-C Controller` or `Objective-C ARC Controller` app.
92
93## Cleaning the source build
94
95Running `make clean` will remove the binaries created for the default
96configuration and platform.
97
98To clean the binaries produced for a specific configuration or platform, you
99need to specify the `CONFIGS` or `PLATFORMS` variable. For example,
100`make CONFIGS=xcodesdk clean` will clean the Xcode SDK build.
101
102To clean the build for all the supported configurations and platforms, run
103`make CONFIGS=all PLATFORMS=all clean`.
104
105Running `make distclean` will also clean the build for all the configurations
106and platforms. In addition, it will also remove the generated files created by
107the Slice translators.
108
109## Running the Test Suite
110
111Python is required to run the test suite. After a successful source build, you
112can run the tests as shown below. If everything worked out, you should see lots
113of `ok` messages. In case of a failure, the tests abort with `failed`.
114
115### macOS
116```
117 python3 allTests.py # default config and default platform
118 python3 allTests --config=... --platform=... # use the specified config and platform
119```
120### iOS Simulator
121```
122 python3 allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app
123```
124### iOS
125 - Start the `Objective-C Controller` or `Objective-C ARC Controller` app on
126 your iOS device, from Xcode.
127 - On your Mac:
128 ```
129 python3 allTests.py --config=xcodesdk --platform=iphoneos
130 ```
131 All the test clients and servers run on the iOS device, not on your Mac
132 computer.
133
134[1]: https://doc.zeroc.com/display/Rel/Using+the+macOS+Binary+Distribution+for+Ice+3.7.2
135[2]: https://doc.zeroc.com/display/Rel/Supported+Platforms+for+Ice+3.7.2
136[3]: https://en.wikipedia.org/wiki/Automatic_Reference_Counting
137