From 01e97ae1b071b51975d02b1addbe272f6fbbdb15 Mon Sep 17 00:00:00 2001 From: Mirko Bonadei Date: Thu, 5 Sep 2019 14:36:42 +0200 Subject: [PATCH] Move docs about native code development into a repo directory. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit No-Try: True Bug: None Change-Id: I4a7f3df3547beb85eaabe90a9d059da32cc64261 Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/151303 Commit-Queue: Mirko Bonadei Reviewed-by: Patrik Höglund Cr-Commit-Position: refs/heads/master@{#29129} --- PRESUBMIT.py | 3 +- docs/OWNERS | 1 + docs/native-code/android/index.md | 171 +++++++++++ docs/native-code/development/index.md | 277 ++++++++++++++++++ .../development/prerequisite-sw/index.md | 60 ++++ docs/native-code/index.md | 40 +++ docs/native-code/ios/index.md | 217 ++++++++++++++ 7 files changed, 768 insertions(+), 1 deletion(-) create mode 100644 docs/OWNERS create mode 100644 docs/native-code/android/index.md create mode 100644 docs/native-code/development/index.md create mode 100644 docs/native-code/development/prerequisite-sw/index.md create mode 100644 docs/native-code/index.md create mode 100644 docs/native-code/ios/index.md diff --git a/PRESUBMIT.py b/PRESUBMIT.py index 7edc249ebd..d838bfd42b 100755 --- a/PRESUBMIT.py +++ b/PRESUBMIT.py @@ -910,13 +910,14 @@ def CheckApiDepsFileIsUpToDate(input_api, output_api): deps_content = _ParseDeps(f.read()) include_rules = deps_content.get('include_rules', []) + dirs_to_skip = set(['api', 'docs']) # Only check top level directories affected by the current CL. dirs_to_check = set() for f in input_api.AffectedFiles(): path_tokens = [t for t in f.LocalPath().split(os.sep) if t] if len(path_tokens) > 1: - if (path_tokens[0] != 'api' and + if (path_tokens[0] not in dirs_to_skip and os.path.isdir(os.path.join(input_api.PresubmitLocalPath(), path_tokens[0]))): dirs_to_check.add(path_tokens[0]) diff --git a/docs/OWNERS b/docs/OWNERS new file mode 100644 index 0000000000..72e8ffc0db --- /dev/null +++ b/docs/OWNERS @@ -0,0 +1 @@ +* diff --git a/docs/native-code/android/index.md b/docs/native-code/android/index.md new file mode 100644 index 0000000000..ee4e9e832e --- /dev/null +++ b/docs/native-code/android/index.md @@ -0,0 +1,171 @@ +# WebRTC Android development + +## Prebuilt libraries +The easiest way to get started is using the [official prebuilt libraries][prebuilt-libraries] +available at JCenter. These libraries are compiled from the tip-of-tree and are +meant for development purposes only. + +On Android Studio 3 add to your dependencies: + +``` +implementation 'org.webrtc:google-webrtc:1.0.+' +``` + +On Android Studio 2 add to your dependencies: + +``` +compile 'org.webrtc:google-webrtc:1.0.+' +``` + +The version of the library is `1.0.`. The hash of the commit +can be found in the .pom-file. The third party licenses can be found in the +THIRD_PARTY_LICENSES.md file next to the .aar-file. + +## Getting the Code + +Android development is only supported on Linux. + +1. Install [prerequisite software][webrtc-prerequisite-sw] + +2. Create a working directory, enter it, and run: + +``` +$ fetch --nohooks webrtc_android +$ gclient sync +``` + +This will fetch a regular WebRTC checkout with the Android-specific parts +added. Notice that the Android specific parts like the Android SDK and NDK are +quite large (~8 GB), so the total checkout size will be about 16 GB. +The same checkout can be used for both Linux and Android development since you +can generate your [Ninja][ninja] project files in different directories for each +build config. + +See [Development][webrtc-development] for instructions on how to update +the code, building etc. + +## Compiling + +1. Generate projects using GN. + +Make sure your current working directory is src/ of your workspace. +Then run: + +``` +$ gn gen out/Debug --args='target_os="android" target_cpu="arm"' +``` + +You can specify a directory of your own choice instead of `out/Debug`, +to enable managing multiple configurations in parallel. + +* To build for ARM64: use `target_cpu="arm64"` +* To build for 32-bit x86: use `target_cpu="x86"` +* To build for 64-bit x64: use `target_cpu="x64"` + +2. Compile using: + +``` +$ ninja -C out/Debug +``` + +## Using the Bundled Android SDK/NDK + +In order to use the Android SDK and NDK that is bundled in +`third_party/android_tools`, run this to get it included in your `PATH` (from +`src/`): + +``` +$ . build/android/envsetup.sh +``` + +Then you'll have `adb` and all the other Android tools in your `PATH`. + +## Running the AppRTCMobile App + +AppRTCMobile is an Android application using WebRTC Native APIs via JNI (JNI +wrapper is documented [here][webrtc-jni-doc]). + +For instructions on how to build and run, see +[examples/androidapp/README][apprtc-doc]. + + +## Using Android Studio + +*Note: This is known to be broken at the moment. See bug: +https://bugs.webrtc.org/9282* + +1. Build the project normally (out/Debug should be the directory you used when +generating the build files using GN): + +``` +$ ninja -C out/Debug AppRTCMobile +``` + +2. Generate the project files: + +``` +$ build/android/gradle/generate_gradle.py --output-directory $PWD/out/Debug \ + --target "//examples:AppRTCMobile" --use-gradle-process-resources \ + --split-projects --canary +``` + +3. *Import* the project in Android Studio. (Do not just open it.) The project +is located in `out/Debug/gradle`. If asked which SDK to use, choose to use +Android Studio's SDK. When asked whether to use the Gradle wrapper, press +"OK". + +4. Ensure target `webrtc > examples > AppRTCMobile` is selected and press Run. +AppRTCMobile should now start on the device. + +If you do any changes to the C++ code, you have to compile the project using +ninja after the changes (see step 1). + +*Note: Only "arm" is supported as the target_cpu when using Android Studio. This +still allows you to run the application on 64-bit ARM devices. x86-based devices +are not supported right now.* + + +## Running WebRTC Native Tests on an Android Device + +To build APKs with the WebRTC native tests, follow these instructions. + +1. Ensure you have an Android device set in Developer mode connected via +USB. + +2. Compile as described in the section above. + +3. To see which tests are available: look in `out/Debug/bin`. + +4. Run a test on your device: + +``` +$ out/Debug/bin/run_modules_unittests +``` + +5. If you want to limit to a subset of tests, use the `--gtest_filter flag`, e.g. + +``` +$ out/Debug/bin/run_modules_unittests \ + --gtest_filter=RtpRtcpAPITest.SSRC:RtpRtcpRtcpTest.* +``` + +6. **NOTICE:** The first time you run a test, you must accept a dialog on +the device! + +If want to run Release builds instead; pass `is_debug=false` to GN (and +preferably generate the projects files into a directory like `out/Release`). +Then use the scripts generated in `out/Release/bin` instead. + + +## Running WebRTC Instrumentation Tests on an Android Device + +The instrumentation tests (like AppRTCMobileTest and +libjingle_peerconnection_android_unittest) gets scripts generated in the same +location as the native tests described in the previous section. + +[webrtc-prerequitite-sw]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/prerequisite-sw/index.md +[webrtc-jni-doc]: https://webrtc.googlesource.com/src/+/master/sdk/android/README +[apprtc-doc]: https://webrtc.googlesource.com/src/+/master/examples/androidapp/README +[ninja]: https://ninja-build.org/ +[prebuilt-libraries]: https://bintray.com/google/webrtc/google-webrtc +[webrtc-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/index.md diff --git a/docs/native-code/development/index.md b/docs/native-code/development/index.md new file mode 100644 index 0000000000..01914bc008 --- /dev/null +++ b/docs/native-code/development/index.md @@ -0,0 +1,277 @@ +# WebRTC development + +The currently supported platforms are Windows, Mac OS X, Linux, Android and +iOS. See the [Android][webrtc-android-development] and [iOS][webrtc-ios-development] +pages for build instructions and example applications specific to these mobile platforms. + + +## Before You Start + +First, be sure to install the [prerequisite software][webrtc-prerequisite-sw]. + +[webrtc-prerequitite-sw]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/prerequisite-sw/index.md + + +## Getting the Code + +For desktop development: + +1. Create a working directory, enter it, and run `fetch webrtc`: + +``` +$ mkdir webrtc-checkout +$ cd webrtc-checkout +$ fetch --nohooks webrtc +$ gclient sync +``` + +NOTICE: During your first sync, you'll have to accept the license agreement of the Google Play Services SDK. + +The checkout size is large due the use of the Chromium build toolchain and many dependencies. Estimated size: + +* Linux: 6.4 GB. +* Linux (with Android): 16 GB (of which ~8 GB is Android SDK+NDK images). +* Mac (with iOS support): 5.6GB + +2. Optionally you can specify how new branches should be tracked: + +``` +$ git config branch.autosetupmerge always +$ git config branch.autosetuprebase always +``` + +3. Alternatively, you can create new local branches like this (recommended): + +``` +$ cd src +$ git checkout master +$ git new-branch your-branch-name +``` + +See the [Android][webrtc-android-development] and [iOS][webrtc-ios-development] pages for separate instructions. + +**NOTICE:** if you get `Remote: Daily bandwidth rate limit exceeded for `, +make sure [you're logged in][webrtc-first-patch]. The quota is much larger for logged in users. + +## Updating the Code + +Update your current branch with: + +``` +$ git checkout master +$ git pull origin master +$ gclient sync +$ git checkout my-branch +$ git merge master +``` + +## Building + +[Ninja][ninja] is the default build system for all platforms. + +See the [Android][webrtc-android-development] and [iOS][webrtc-ios-development] pages for build +instructions specific to those platforms. + +## Generating Ninja project files + +[Ninja][ninja] project files are generated using [GN][gn]. They're put in a +directory of your choice, like `out/Debug` or `out/Release`, but you can +use any directory for keeping multiple configurations handy. + +To generate project files using the defaults (Debug build), run (standing in +the src/ directory of your checkout): + +``` +$ gn gen out/Default +``` + +To generate ninja project files for a Release build instead: + +``` +$ gn gen out/Default --args='is_debug=false' +``` + +To clean all build artifacts in a directory but leave the current GN +configuration untouched (stored in the args.gn file), do: + +``` +$ gn clean out/Default +``` + +See the [GN][gn-doc] documentation for all available options. There are also more +platform specific tips on the [Android][webrtc-android-development] and +[iOS][webrtc-ios-development] instructions. + +## Compiling + +When you have Ninja project files generated (see previous section), compile +(standing in `src/`) using: + +For [Ninja][ninja] project files generated in `out/Default`: + +``` +$ ninja -C out/Default +``` + + +## Using Another Build System + +Other build systems are **not supported** (and may fail), such as Visual +Studio on Windows or Xcode on OSX. GN supports a hybrid approach of using +[Ninja][ninja] for building, but Visual Studio/Xcode for editing and driving +compilation. + +To generate IDE project files, pass the `--ide` flag to the [GN][gn] command. +See the [GN reference][gn-doc] for more details on the supported IDEs. + + +## Working with Release Branches + +To see available release branches, run: + +``` +$ git branch -r +``` + +To create a local branch tracking a remote release branch (in this example, +the 43 branch): + +``` +$ git checkout -b my_branch refs/remotes/branch-heads/43 +$ gclient sync +``` + +**NOTICE**: depot_tools are not tracked with your checkout, so it's possible gclient +sync will break on sufficiently old branches. In that case, you can try using +an older depot_tools: + +``` +which gclient +$ # cd to depot_tools dir +$ # edit update_depot_tools; add an exit command at the top of the file +$ git log # find a hash close to the date when the branch happened +$ git checkout +$ cd ~/dev/webrtc/src +$ gclient sync +$ # When done, go back to depot_tools, git reset --hard, run gclient again and +$ # verify the current branch becomes REMOTE:origin/master +``` + +The above is untested and unsupported, but it might help. + +Commit log for the branch: [https://webrtc.googlesource.com/src/+log/branch-heads/43][m43-log] +To browse it: [https://webrtc.googlesource.com/src/+/branch-heads/43][m43] + +For more details, read Chromium's [Working with Branches][chromium-work-branches] and +[Working with Release Branches][chromium-work-release-branches] pages. + + +## Contributing Patches + +Please see [Contributing Fixes][webrtc-contributing] for information on how to run +`git cl upload`, getting your patch reviewed, and getting it submitted. + +This also includes information on how to run tryjobs, if you're a committer. + +## Chromium Committers + +Many WebRTC committers are also Chromium committers. To make sure to use the +right account for pushing commits to WebRTC, use the `user.email` Git config +setting. The recommended way is to have the chromium.org account set globally +as described at the [depot tools setup page][depot-tools] and then set `user.email` +locally for the WebRTC repos using (change to your webrtc.org address): + +``` +$ cd /path/to/webrtc/src +$ git config user.email yourname@webrtc.org +``` + +## Example Applications + +WebRTC contains several example applications, which can be found under +`src/webrtc/examples`. Higher level applications are listed first. + + +### Peerconnection + +Peerconnection consist of two applications using the WebRTC Native APIs: + +* A server application, with target name `peerconnection_server` +* A client application, with target name `peerconnection_client` (not currently supported on Mac/Android) + +The client application has simple voice and video capabilities. The server +enables client applications to initiate a call between clients by managing +signaling messages generated by the clients. + + +#### Setting up P2P calls between peerconnection_clients + +Start `peerconnection_server`. You should see the following message indicating +that it is running: + +``` +Server listening on port 8888 +``` + +Start any number of `peerconnection_clients` and connect them to the server. +The client UI consists of a few parts: + +**Connecting to a server:** When the application is started you must specify +which machine (by IP address) the server application is running on. Once that +is done you can press **Connect** or the return button. + +**Select a peer:** Once successfully connected to a server, you can connect to +a peer by double-clicking or select+press return on a peer's name. + +**Video chat:** When a peer has been successfully connected to, a video chat +will be displayed in full window. + +**Ending chat session:** Press **Esc**. You will now be back to selecting a +peer. + +**Ending connection:** Press **Esc** and you will now be able to select which +server to connect to. + + +#### Testing peerconnection_server + +Start an instance of `peerconnection_server` application. + +Open `src/webrtc/examples/peerconnection/server/server_test.html` in your +browser. Click **Connect**. Observe that the `peerconnection_server` announces +your connection. Open one more tab using the same page. Connect it too (with a +different name). It is now possible to exchange messages between the connected +peers. + +### Relay Server + +Target name `relayserver`. Relays traffic when a direct peer-to-peer +connection can't be established. Can be used with the call application above. + + +### STUN Server + +Target name `stunserver`. Implements the STUN protocol for Session Traversal +Utilities for NAT as documented in [RFC 5389][rfc-5389]. + + +### TURN Server + +Target name `turnserver`. In active development to reach compatibility with +[RFC 5766][rfc-5766]. + + +[ninja]: https://ninja-build.org/ +[gn]: https://gn.googlesource.com/gn/+/master/README.md +[gn-doc]: https://gn.googlesource.com/gn/+/master/docs/reference.md#IDE-options +[webtc-android-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/android/index.md +[webrtc-ios-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/ios/index.md +[chromium-work-branches]: https://www.chromium.org/developers/how-tos/get-the-code/working-with-branches +[chromium-work-release-branches]: https://www.chromium.org/developers/how-tos/get-the-code/working-with-release-branches +[webrtc-contributing]: https://webrtc.org/contributing/ +[depot-tools]: http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up +[rfc-5389]: https://tools.ietf.org/html/rfc5389 +[rfc-5766]: https://tools.ietf.org/html/rfc5766 +[webrtc-first-patch]: https://webrtc.org/native-code/development/#contributing-your-first-patch +[m43-log]: https://webrtc.googlesource.com/src/+log/branch-heads/43 +[m43]: https://webrtc.googlesource.com/src/+/branch-heads/43 diff --git a/docs/native-code/development/prerequisite-sw/index.md b/docs/native-code/development/prerequisite-sw/index.md new file mode 100644 index 0000000000..866f585c48 --- /dev/null +++ b/docs/native-code/development/prerequisite-sw/index.md @@ -0,0 +1,60 @@ +# WebRTC development - Prerequisite software + +## Depot Tools + +1. [Install the Chromium depot tools][depot-tools]. + +2. On Windows, depot tools will download a special version of Git during your +first `gclient sync`. On Mac and Linux, you'll need to install [Git][git] by +yourself. + +## Linux (Ubuntu/Debian) + +A script is provided for Ubuntu, which is unfortunately only available after +your first gclient sync: + +``` +$ ./build/install-build-deps.sh +``` + +Most of the libraries installed with this script are not needed since we now +build using Debian sysroot images in build/linux, but there are still some tools +needed for the build that are installed with +[install-build-deps.sh][install-build-deps]. + +You may also want to have a look at the [Chromium Linux Build +instructions][chromium-linux-build-instructions] if you experience any other problems building. + +## Windows + +Follow the [Chromium's build instructions for Windows][chromium-win-build-instructions]. + +WebRTC requires Visual Studio 2017 to be used. If you only have version 2015 +available, you might be able to keep using it for some time by setting +`GYP_MSVS_VERSION=2015` in your environment. Keep in mind that this is not a +suppported configuration however. + +## macOS + +Xcode 9 or higher is required. Latest Xcode is recommended to be able to build +all code. + +## Android + +You'll need a Linux development machine. WebRTC is using the same Android +toolchain as Chrome (downloaded into `third_party/android_tools`) so you won't +need to install the NDK/SDK separately. + +1. Install Java OpenJDK as described in the +[Chromium Android prerequisites][chromium-android-build-build-instructions] +2. All set! If you don't run Ubuntu, you may want to have a look at +[Chromium's Linux prerequisites][chromium-linux-prerequisites] for distro-specific details. + + +[depot-tools]: http://dev.chromium.org/developers/how-tos/install-depot-tools +[git]: http://git-scm.com +[install-build-deps]: https://cs.chromium.org/chromium/src/build/install-build-deps.sh +[chromium-linux-build-instructions]: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_build_instructions.md +[chromium-win-build-instructions]: https://chromium.googlesource.com/chromium/src/+/master/docs/windows_build_instructions.md +[chromium-linux-prerequisites]: https://chromium.googlesource.com/chromium/src/+/master/docs/linux_build_instructions.md#Install +[chromium-android-build-build-instructions]: https://www.chromium.org/developers/how-tos/android-build-instructions diff --git a/docs/native-code/index.md b/docs/native-code/index.md new file mode 100644 index 0000000000..91d024f2b4 --- /dev/null +++ b/docs/native-code/index.md @@ -0,0 +1,40 @@ +# WebRTC native code + +The WebRTC Native Code package is meant for browser developers who want to +integrate WebRTC. Application developers are encouraged to use the [WebRTC +API][webrtc-api] instead. + +[webrtc-api]: http://dev.w3.org/2011/webrtc/editor/webrtc.html + +The WebRTC native code can be found at +[https://webrtc.googlesource.com/src][webrtc-repo]. + +[webrtc-repo]: https://webrtc.googlesource.com/src/ + +The change log is available at +[https://webrtc.googlesource.com/src/+log][webrtc-change-log] + +[webrtc-change-log]: https://webrtc.googlesource.com/src/+log + +Please read the [License & Rights][webrtc-license] and [FAQ][webrtc-faq] +before downloading the source code. + +[webrtc-license]: https://webrtc.org/license/ +[webrtc-faq]: https://webrtc.org/faq/ + +The WebRTC [issue tracker][webrtc-issue-tracker] can be used for submitting +bugs found in native code. + +[webrtc-issue-tracker]: https://bugs.webrtc.org + +## Subpages + +* [Prerequisite software][webrtc-prerequitite-sw] +* [Development][webrtc-development] +* [Android][webtc-android-development] +* [iOS][webrtc-ios-development] + +[webrtc-prerequitite-sw]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/prerequisite-sw/index.md +[webrtc-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/index.md +[webtc-android-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/android/index.md +[webrtc-ios-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/ios/index.md diff --git a/docs/native-code/ios/index.md b/docs/native-code/ios/index.md new file mode 100644 index 0000000000..7defd379be --- /dev/null +++ b/docs/native-code/ios/index.md @@ -0,0 +1,217 @@ +# WebRTC iOS development + +## Using Cocoapods + +The WebRTC framework is published on [cocoapods.org][cocoapods]. +The framework is built from tip-of-tree. + +_NOTICE_: The pod version of the framework doesn't support bitcode currently. +If you need bitcode support, you'll need to manually build the framework. +The process is described in detail in the following sections. + +To integrate it into your project add the following lines to your Podfile + +``` +source 'https://github.com/CocoaPods/Specs.git' +target 'YOUR_APPLICATION_TARGET_NAME_HERE' do + platform :ios, '9.0' + pod 'GoogleWebRTC' +end +``` + +The versioning system used is *1.1.cr-commit-position*, where *cr-commit-position* can +be used to identify the exact WebRTC revision the pod was built from. You can check the +revision at crrev.com/CR_COMMIT_POSITION_HERE. + +## Development Environment + +In case you need to build the framework manually +(for instance if you need to support bitcode) 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 +``` + +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 `. + +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 `. 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/`. + +## 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.xcworkspace` +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.xcworkspace +``` + +*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`][7], +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] + +To build the framework with bitcode support, pass the `--bitcode` flag to the script like so + +``` +$ python build_ios_libs.py --bitcode +``` +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-prerequitite-sw]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/prerequisite-sw/index.md +[webrtc-development]: https://webrtc.googlesource.com/src/+/refs/heads/master/docs/native-code/development/index.md +[framework-script]: https://chromium.googlesource.com/external/webrtc/+/master/tools_webrtc/ios/build_ios_libs.py +[ninja]: https://ninja-build.org/ +[gn]: https://gn.googlesource.com/gn/+/master/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/