xref: /aosp_15_r20/external/webrtc/docs/native-code/ios/index.md (revision d9f758449e529ab9291ac668be2861e7a55c2422)
1*d9f75844SAndroid Build Coastguard Worker# WebRTC iOS development
2*d9f75844SAndroid Build Coastguard Worker
3*d9f75844SAndroid Build Coastguard Worker## Development Environment
4*d9f75844SAndroid Build Coastguard Worker
5*d9f75844SAndroid Build Coastguard WorkerIn case you need to build the framework manually or you want to try out the
6*d9f75844SAndroid Build Coastguard Workerdemo application AppRTCMobile, follow the instructions illustrated bellow.
7*d9f75844SAndroid Build Coastguard Worker
8*d9f75844SAndroid Build Coastguard WorkerA macOS machine is required for iOS development. While it's possible to
9*d9f75844SAndroid Build Coastguard Workerdevelop purely from the command line with text editors, it's easiest to use
10*d9f75844SAndroid Build Coastguard WorkerXcode. Both methods will be illustrated here.
11*d9f75844SAndroid Build Coastguard Worker
12*d9f75844SAndroid Build Coastguard Worker_NOTICE:_ You will need to install [Chromium depot_tools][webrtc-prerequisite-sw].
13*d9f75844SAndroid Build Coastguard Worker
14*d9f75844SAndroid Build Coastguard Worker## Getting the Code
15*d9f75844SAndroid Build Coastguard Worker
16*d9f75844SAndroid Build Coastguard WorkerCreate a working directory, enter it, and run:
17*d9f75844SAndroid Build Coastguard Worker
18*d9f75844SAndroid Build Coastguard Worker```
19*d9f75844SAndroid Build Coastguard Worker$ fetch --nohooks webrtc_ios
20*d9f75844SAndroid Build Coastguard Worker$ gclient sync
21*d9f75844SAndroid Build Coastguard Worker```
22*d9f75844SAndroid Build Coastguard Worker
23*d9f75844SAndroid Build Coastguard WorkerThis will fetch a regular WebRTC checkout with the iOS-specific parts
24*d9f75844SAndroid Build Coastguard Workeradded. Notice the size is quite large: about 6GB. The same checkout can be used
25*d9f75844SAndroid Build Coastguard Workerfor both Mac and iOS development, since GN allows you to generate your
26*d9f75844SAndroid Build Coastguard Worker[Ninja][ninja] project files in different directories for each build config.
27*d9f75844SAndroid Build Coastguard Worker
28*d9f75844SAndroid Build Coastguard WorkerYou may want to disable Spotlight indexing for the checkout to speed up
29*d9f75844SAndroid Build Coastguard Workerfile operations.
30*d9f75844SAndroid Build Coastguard Worker
31*d9f75844SAndroid Build Coastguard WorkerNote that the git repository root is in `src`.
32*d9f75844SAndroid Build Coastguard Worker
33*d9f75844SAndroid Build Coastguard WorkerFrom here you can check out a new local branch with:
34*d9f75844SAndroid Build Coastguard Worker
35*d9f75844SAndroid Build Coastguard Worker```
36*d9f75844SAndroid Build Coastguard Worker$ git new-branch <branch name>
37*d9f75844SAndroid Build Coastguard Worker```
38*d9f75844SAndroid Build Coastguard Worker
39*d9f75844SAndroid Build Coastguard WorkerSee [Development][webrtc-development] for generic instructions on how
40*d9f75844SAndroid Build Coastguard Workerto update the code in your checkout.
41*d9f75844SAndroid Build Coastguard Worker
42*d9f75844SAndroid Build Coastguard Worker
43*d9f75844SAndroid Build Coastguard Worker## Generating project files
44*d9f75844SAndroid Build Coastguard Worker
45*d9f75844SAndroid Build Coastguard Worker[GN][gn] is used to generate [Ninja][ninja] project files. In order to configure
46*d9f75844SAndroid Build Coastguard Worker[GN][gn] to generate build files for iOS certain variables need to be set.
47*d9f75844SAndroid Build Coastguard WorkerThose variables can be edited for the various build configurations as needed.
48*d9f75844SAndroid Build Coastguard Worker
49*d9f75844SAndroid Build Coastguard WorkerThe variables you should care about are the following:
50*d9f75844SAndroid Build Coastguard Worker
51*d9f75844SAndroid Build Coastguard Worker* `target_os`:
52*d9f75844SAndroid Build Coastguard Worker  - To build for iOS this should be set as `target_os="ios"` in your `gn args`.
53*d9f75844SAndroid Build Coastguard Worker  The default is whatever OS you are running the script on, so this can be
54*d9f75844SAndroid Build Coastguard Worker  omitted when generating build files for macOS.
55*d9f75844SAndroid Build Coastguard Worker* `target_cpu`:
56*d9f75844SAndroid Build Coastguard Worker  - For builds targeting iOS devices, this should be set to either `"arm"` or
57*d9f75844SAndroid Build Coastguard Worker  `"arm64"`, depending on the architecture of the device. For builds to run in
58*d9f75844SAndroid Build Coastguard Worker  the simulator, this should be set to `"x64"`.
59*d9f75844SAndroid Build Coastguard Worker* `is_debug`:
60*d9f75844SAndroid Build Coastguard Worker  - Debug builds are the default. When building for release, specify `false`.
61*d9f75844SAndroid Build Coastguard Worker
62*d9f75844SAndroid Build Coastguard WorkerThe component build is the default for Debug builds, which are also enabled by
63*d9f75844SAndroid Build Coastguard Workerdefault unless `is_debug=false` is specified.
64*d9f75844SAndroid Build Coastguard Worker
65*d9f75844SAndroid Build Coastguard WorkerThe [GN][gn] command for generating build files is `gn gen <output folder>`.
66*d9f75844SAndroid Build Coastguard Worker
67*d9f75844SAndroid Build Coastguard WorkerAfter you've generated your build files once, subsequent invocations of `gn gen`
68*d9f75844SAndroid Build Coastguard Workerwith the same output folder will use the same arguments as first supplied.
69*d9f75844SAndroid Build Coastguard WorkerTo edit these at any time use `gn args <output folder>`. This will open up
70*d9f75844SAndroid Build Coastguard Workera file in `$EDITOR` where you can edit the arguments. When you've made
71*d9f75844SAndroid Build Coastguard Workerchanges and save the file, `gn` will regenerate your project files for you
72*d9f75844SAndroid Build Coastguard Workerwith the new arguments.
73*d9f75844SAndroid Build Coastguard Worker
74*d9f75844SAndroid Build Coastguard Worker### Examples
75*d9f75844SAndroid Build Coastguard Worker
76*d9f75844SAndroid Build Coastguard Worker```
77*d9f75844SAndroid Build Coastguard Worker$ # debug build for 64-bit iOS
78*d9f75844SAndroid Build Coastguard Worker$ gn gen out/ios_64 --args='target_os="ios" target_cpu="arm64"'
79*d9f75844SAndroid Build Coastguard Worker
80*d9f75844SAndroid Build Coastguard Worker$ # debug build for simulator
81*d9f75844SAndroid Build Coastguard Worker$ gn gen out/ios_sim --args='target_os="ios" target_cpu="x64"'
82*d9f75844SAndroid Build Coastguard Worker```
83*d9f75844SAndroid Build Coastguard Worker
84*d9f75844SAndroid Build Coastguard Worker## Compiling with ninja
85*d9f75844SAndroid Build Coastguard Worker
86*d9f75844SAndroid Build Coastguard WorkerTo compile, just run ninja on the appropriate target. For example:
87*d9f75844SAndroid Build Coastguard Worker
88*d9f75844SAndroid Build Coastguard Worker```
89*d9f75844SAndroid Build Coastguard Worker$ ninja -C out/ios_64 AppRTCMobile
90*d9f75844SAndroid Build Coastguard Worker```
91*d9f75844SAndroid Build Coastguard Worker
92*d9f75844SAndroid Build Coastguard WorkerReplace `AppRTCMobile` in the command above with the target you
93*d9f75844SAndroid Build Coastguard Workerare interested in.
94*d9f75844SAndroid Build Coastguard Worker
95*d9f75844SAndroid Build Coastguard WorkerTo see a list of available targets, run `gn ls out/<output folder>`.
96*d9f75844SAndroid Build Coastguard Worker
97*d9f75844SAndroid Build Coastguard Worker## Using Xcode
98*d9f75844SAndroid Build Coastguard Worker
99*d9f75844SAndroid Build Coastguard WorkerXcode is the default and preferred IDE to develop for the iOS platform.
100*d9f75844SAndroid Build Coastguard Worker
101*d9f75844SAndroid Build Coastguard Worker*Generating an Xcode project*
102*d9f75844SAndroid Build Coastguard Worker
103*d9f75844SAndroid Build Coastguard WorkerTo have GN generate Xcode project files, pass the argument `--ide=xcode`
104*d9f75844SAndroid Build Coastguard Workerwhen running `gn gen`. This will result in a file named `all.xcodeproj`
105*d9f75844SAndroid Build Coastguard Workerplaced in your specified output directory.
106*d9f75844SAndroid Build Coastguard Worker
107*d9f75844SAndroid Build Coastguard WorkerExample:
108*d9f75844SAndroid Build Coastguard Worker
109*d9f75844SAndroid Build Coastguard Worker```
110*d9f75844SAndroid Build Coastguard Worker$ gn gen out/ios --args='target_os="ios" target_cpu="arm64"' --ide=xcode
111*d9f75844SAndroid Build Coastguard Worker$ open -a Xcode.app out/ios/all.xcodeproj
112*d9f75844SAndroid Build Coastguard Worker```
113*d9f75844SAndroid Build Coastguard Worker
114*d9f75844SAndroid Build Coastguard Worker*Compile and run with Xcode*
115*d9f75844SAndroid Build Coastguard Worker
116*d9f75844SAndroid Build Coastguard WorkerCompiling with Xcode is not supported! What we do instead is compile using a
117*d9f75844SAndroid Build Coastguard Workerscript that runs ninja from Xcode. This is done with a custom _run script_
118*d9f75844SAndroid Build Coastguard Workeraction in the build phases of the generated project. This script will simply
119*d9f75844SAndroid Build Coastguard Workercall ninja as you would when building from the command line.
120*d9f75844SAndroid Build Coastguard Worker
121*d9f75844SAndroid Build Coastguard WorkerThis gives us access to the usual deployment/debugging workflow iOS developers
122*d9f75844SAndroid Build Coastguard Workerare used to in Xcode, without sacrificing the build speed of Ninja.
123*d9f75844SAndroid Build Coastguard Worker
124*d9f75844SAndroid Build Coastguard Worker## Running the tests
125*d9f75844SAndroid Build Coastguard Worker
126*d9f75844SAndroid Build Coastguard WorkerThere are several test targets in WebRTC. To run the tests, you must deploy the
127*d9f75844SAndroid Build Coastguard Worker`.app` bundle to a device (see next section) and run them from there.
128*d9f75844SAndroid Build Coastguard WorkerTo run a specific test or collection of tests, normally with gtest one would pass
129*d9f75844SAndroid Build Coastguard Workerthe `--gtest_filter` argument to the test binary when running. To do this when
130*d9f75844SAndroid Build Coastguard Workerrunning the tests from Xcode, from the targets menu, select the test bundle
131*d9f75844SAndroid Build Coastguard Workerand press _edit scheme..._ at the bottom of the target dropdown menu. From there
132*d9f75844SAndroid Build Coastguard Workerclick _Run_ in the sidebar and add `--gtest_filter` to the _Arguments passed on
133*d9f75844SAndroid Build Coastguard WorkerLaunch_ list.
134*d9f75844SAndroid Build Coastguard Worker
135*d9f75844SAndroid Build Coastguard WorkerIf deploying to a device via the command line using [`ios-deploy`][ios-deploy],
136*d9f75844SAndroid Build Coastguard Workeruse the `-a` flag to pass arguments to the executable on launch.
137*d9f75844SAndroid Build Coastguard Worker
138*d9f75844SAndroid Build Coastguard Worker## Deploying to Device
139*d9f75844SAndroid Build Coastguard Worker
140*d9f75844SAndroid Build Coastguard WorkerIt's easiest to deploy to a device using Xcode. Other command line tools exist
141*d9f75844SAndroid Build Coastguard Workeras well, e.g. [`ios-deploy`][ios-deploy].
142*d9f75844SAndroid Build Coastguard Worker
143*d9f75844SAndroid Build Coastguard Worker**NOTICE:** To deploy to an iOS device you must have a valid signing identity
144*d9f75844SAndroid Build Coastguard Workerset up. You can verify this by running:
145*d9f75844SAndroid Build Coastguard Worker
146*d9f75844SAndroid Build Coastguard Worker```
147*d9f75844SAndroid Build Coastguard Worker$ xcrun security find-identity -v -p codesigning
148*d9f75844SAndroid Build Coastguard Worker```
149*d9f75844SAndroid Build Coastguard Worker
150*d9f75844SAndroid Build Coastguard WorkerIf you don't have a valid signing identity, you can still build for ARM,
151*d9f75844SAndroid Build Coastguard Workerbut you won't be able to deploy your code to an iOS device. To do this,
152*d9f75844SAndroid Build Coastguard Workeradd the flag `ios_enable_code_signing=false` to the `gn gen` args when you
153*d9f75844SAndroid Build Coastguard Workergenerate the build files.
154*d9f75844SAndroid Build Coastguard Worker
155*d9f75844SAndroid Build Coastguard Worker## Using WebRTC in your app
156*d9f75844SAndroid Build Coastguard Worker
157*d9f75844SAndroid Build Coastguard WorkerTo build WebRTC for use in a native iOS app, it's easiest to build
158*d9f75844SAndroid Build Coastguard Worker`WebRTC.framework`. This can be done with ninja as follows, replacing `ios`
159*d9f75844SAndroid Build Coastguard Workerwith the actual location of your generated build files.
160*d9f75844SAndroid Build Coastguard Worker
161*d9f75844SAndroid Build Coastguard Worker```
162*d9f75844SAndroid Build Coastguard Workerninja -C out/ios framework_objc
163*d9f75844SAndroid Build Coastguard Worker```
164*d9f75844SAndroid Build Coastguard Worker
165*d9f75844SAndroid Build Coastguard WorkerThis should result in a `.framework` bundle being generated in `out/ios`.
166*d9f75844SAndroid Build Coastguard WorkerThis bundle can now be directly included in another app.
167*d9f75844SAndroid Build Coastguard Worker
168*d9f75844SAndroid Build Coastguard WorkerIf you need a FAT `.framework`, that is, a binary that contains code for
169*d9f75844SAndroid Build Coastguard Workermultiple architectures, and will work both on device and in the simulator,
170*d9f75844SAndroid Build Coastguard Workera script is available [here][framework-script]
171*d9f75844SAndroid Build Coastguard Worker
172*d9f75844SAndroid Build Coastguard WorkerThe resulting framework can be found in out_ios_libs/.
173*d9f75844SAndroid Build Coastguard Worker
174*d9f75844SAndroid Build Coastguard WorkerPlease note that you can not ship the FAT framework binary with your app
175*d9f75844SAndroid Build Coastguard Workerif you intend to distribute it through the app store.
176*d9f75844SAndroid Build Coastguard WorkerTo solve this either remove "x86-64" from the list of architectures in
177*d9f75844SAndroid Build Coastguard Workerthe [build script][framework-script] or split the binary and recreate it without x86-64.
178*d9f75844SAndroid Build Coastguard WorkerFor instructions on how to do this see [here][strip-arch].
179*d9f75844SAndroid Build Coastguard Worker
180*d9f75844SAndroid Build Coastguard Worker
181*d9f75844SAndroid Build Coastguard Worker[cocoapods]: https://cocoapods.org/pods/GoogleWebRTC
182*d9f75844SAndroid Build Coastguard Worker[webrtc-prerequisite-sw]: https://webrtc.googlesource.com/src/+/main/docs/native-code/development/prerequisite-sw/index.md
183*d9f75844SAndroid Build Coastguard Worker[webrtc-development]: https://webrtc.googlesource.com/src/+/main/docs/native-code/development/index.md
184*d9f75844SAndroid Build Coastguard Worker[framework-script]: https://webrtc.googlesource.com/src/+/main/tools_webrtc/ios/build_ios_libs.py
185*d9f75844SAndroid Build Coastguard Worker[ninja]: https://ninja-build.org/
186*d9f75844SAndroid Build Coastguard Worker[gn]: https://gn.googlesource.com/gn/+/main/README.md
187*d9f75844SAndroid Build Coastguard Worker[ios-deploy]: https://github.com/phonegap/ios-deploy
188*d9f75844SAndroid Build Coastguard Worker[strip-arch]: http://ikennd.ac/blog/2015/02/stripping-unwanted-architectures-from-dynamic-libraries-in-xcode/
189