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