Move docs about native code development into a repo directory.
No-Try: True
Bug: None
Change-Id: I4a7f3df3547beb85eaabe90a9d059da32cc64261
Reviewed-on: https://webrtc-review.googlesource.com/c/src/+/151303
Commit-Queue: Mirko Bonadei <mbonadei@webrtc.org>
Reviewed-by: Patrik Höglund <phoglund@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#29129}
diff --git a/docs/OWNERS b/docs/OWNERS
new file mode 100644
index 0000000..72e8ffc
--- /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 0000000..ee4e9e8
--- /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.<Cr-Commit-Position>`. 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 0000000..01914bc
--- /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 <ip>`,
+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 <hash>
+$ 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 0000000..866f585
--- /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 0000000..91d024f
--- /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 0000000..7defd37
--- /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 <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.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/