diff options
Diffstat (limited to 'third_party/libwebrtc/docs/native-code/ios/index.md')
| -rw-r--r-- | third_party/libwebrtc/docs/native-code/ios/index.md | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/third_party/libwebrtc/docs/native-code/ios/index.md b/third_party/libwebrtc/docs/native-code/ios/index.md new file mode 100644 index 0000000000..307379f17f --- /dev/null +++ b/third_party/libwebrtc/docs/native-code/ios/index.md @@ -0,0 +1,188 @@ +# WebRTC iOS development + +## Development Environment + +In case you need to build the framework manually or you want to try out the +demo application AppRTCMobile, follow the instructions illustrated bellow. + +A macOS machine is required for iOS development. While it's possible to +develop purely from the command line with text editors, it's easiest to use +Xcode. Both methods will be illustrated here. + +_NOTICE:_ You will need to install [Chromium depot_tools][webrtc-prerequisite-sw]. + +## Getting the Code + +Create a working directory, enter it, and run: + +``` +$ fetch --nohooks webrtc_ios +$ gclient sync +``` + +This will fetch a regular WebRTC checkout with the iOS-specific parts +added. Notice the size is quite large: about 6GB. The same checkout can be used +for both Mac and iOS development, since GN allows you to generate your +[Ninja][ninja] project files in different directories for each build config. + +You may want to disable Spotlight indexing for the checkout to speed up +file operations. + +Note that the git repository root is in `src`. + +From here you can check out a new local branch with: + +``` +$ git new-branch <branch name> +``` + +See [Development][webrtc-development] for generic instructions on how +to update the code in your checkout. + + +## Generating project files + +[GN][gn] is used to generate [Ninja][ninja] project files. In order to configure +[GN][gn] to generate build files for iOS certain variables need to be set. +Those variables can be edited for the various build configurations as needed. + +The variables you should care about are the following: + +* `target_os`: + - To build for iOS this should be set as `target_os="ios"` in your `gn args`. + The default is whatever OS you are running the script on, so this can be + omitted when generating build files for macOS. +* `target_cpu`: + - For builds targeting iOS devices, this should be set to either `"arm"` or + `"arm64"`, depending on the architecture of the device. For builds to run in + the simulator, this should be set to `"x64"`. +* `is_debug`: + - Debug builds are the default. When building for release, specify `false`. + +The component build is the default for Debug builds, which are also enabled by +default unless `is_debug=false` is specified. + +The [GN][gn] command for generating build files is `gn gen <output folder>`. + +After you've generated your build files once, subsequent invocations of `gn gen` +with the same output folder will use the same arguments as first supplied. +To edit these at any time use `gn args <output folder>`. This will open up +a file in `$EDITOR` where you can edit the arguments. When you've made +changes and save the file, `gn` will regenerate your project files for you +with the new arguments. + +### Examples + +``` +$ # debug build for 64-bit iOS +$ gn gen out/ios_64 --args='target_os="ios" target_cpu="arm64"' + +$ # debug build for simulator +$ gn gen out/ios_sim --args='target_os="ios" target_cpu="x64"' +``` + +## Compiling with ninja + +To compile, just run ninja on the appropriate target. For example: + +``` +$ ninja -C out/ios_64 AppRTCMobile +``` + +Replace `AppRTCMobile` in the command above with the target you +are interested in. + +To see a list of available targets, run `gn ls out/<output folder>`. + +## Using Xcode + +Xcode is the default and preferred IDE to develop for the iOS platform. + +*Generating an Xcode project* + +To have GN generate Xcode project files, pass the argument `--ide=xcode` +when running `gn gen`. This will result in a file named `all.xcodeproj` +placed in your specified output directory. + +Example: + +``` +$ gn gen out/ios --args='target_os="ios" target_cpu="arm64"' --ide=xcode +$ open -a Xcode.app out/ios/all.xcodeproj +``` + +*Compile and run with Xcode* + +Compiling with Xcode is not supported! What we do instead is compile using a +script that runs ninja from Xcode. This is done with a custom _run script_ +action in the build phases of the generated project. This script will simply +call ninja as you would when building from the command line. + +This gives us access to the usual deployment/debugging workflow iOS developers +are used to in Xcode, without sacrificing the build speed of Ninja. + +## Running the tests + +There are several test targets in WebRTC. To run the tests, you must deploy the +`.app` bundle to a device (see next section) and run them from there. +To run a specific test or collection of tests, normally with gtest one would pass +the `--gtest_filter` argument to the test binary when running. To do this when +running the tests from Xcode, from the targets menu, select the test bundle +and press _edit scheme..._ at the bottom of the target dropdown menu. From there +click _Run_ in the sidebar and add `--gtest_filter` to the _Arguments passed on +Launch_ list. + +If deploying to a device via the command line using [`ios-deploy`][ios-deploy], +use the `-a` flag to pass arguments to the executable on launch. + +## Deploying to Device + +It's easiest to deploy to a device using Xcode. Other command line tools exist +as well, e.g. [`ios-deploy`][ios-deploy]. + +**NOTICE:** To deploy to an iOS device you must have a valid signing identity +set up. You can verify this by running: + +``` +$ xcrun security find-identity -v -p codesigning +``` + +If you don't have a valid signing identity, you can still build for ARM, +but you won't be able to deploy your code to an iOS device. To do this, +add the flag `ios_enable_code_signing=false` to the `gn gen` args when you +generate the build files. + +## Using WebRTC in your app + +To build WebRTC for use in a native iOS app, it's easiest to build +`WebRTC.framework`. This can be done with ninja as follows, replacing `ios` +with the actual location of your generated build files. + +``` +ninja -C out/ios framework_objc +``` + +This should result in a `.framework` bundle being generated in `out/ios`. +This bundle can now be directly included in another app. + +If you need a FAT `.framework`, that is, a binary that contains code for +multiple architectures, and will work both on device and in the simulator, +a script is available [here][framework-script] + +The resulting framework can be found in out_ios_libs/. + +Please note that you can not ship the FAT framework binary with your app +if you intend to distribute it through the app store. +To solve this either remove "x86-64" from the list of architectures in +the [build script][framework-script] or split the binary and recreate it without x86-64. +For instructions on how to do this see [here][strip-arch]. + + +[cocoapods]: https://cocoapods.org/pods/GoogleWebRTC +[webrtc-prerequisite-sw]: https://webrtc.googlesource.com/src/+/main/docs/native-code/development/prerequisite-sw/index.md +[webrtc-development]: https://webrtc.googlesource.com/src/+/main/docs/native-code/development/index.md +[framework-script]: https://webrtc.googlesource.com/src/+/main/tools_webrtc/ios/build_ios_libs.py +[ninja]: https://ninja-build.org/ +[gn]: https://gn.googlesource.com/gn/+/main/README.md +[ios-deploy]: https://github.com/phonegap/ios-deploy +[strip-arch]: http://ikennd.ac/blog/2015/02/stripping-unwanted-architectures-from-dynamic-libraries-in-xcode/ |