1# WebRTC development 2 3The currently supported platforms are Windows, Mac OS X, Linux, Android and 4iOS. See the [Android][webrtc-android-development] and [iOS][webrtc-ios-development] 5pages for build instructions and example applications specific to these mobile platforms. 6 7 8## Before You Start 9 10First, be sure to install the [prerequisite software][webrtc-prerequisite-sw]. 11 12[webrtc-prerequisite-sw]: https://webrtc.googlesource.com/src/+/main/docs/native-code/development/prerequisite-sw/index.md 13 14 15## Getting the Code 16 17For desktop development: 18 191. Create a working directory, enter it, and run `fetch webrtc`: 20 21``` 22$ mkdir webrtc-checkout 23$ cd webrtc-checkout 24$ fetch --nohooks webrtc 25$ gclient sync 26``` 27 28NOTICE: During your first sync, you'll have to accept the license agreement of the Google Play Services SDK. 29 30The checkout size is large due the use of the Chromium build toolchain and many dependencies. Estimated size: 31 32* Linux: 6.4 GB. 33* Linux (with Android): 16 GB (of which ~8 GB is Android SDK+NDK images). 34* Mac (with iOS support): 5.6GB 35 362. Optionally you can specify how new branches should be tracked: 37 38``` 39$ git config branch.autosetupmerge always 40$ git config branch.autosetuprebase always 41``` 42 433. Alternatively, you can create new local branches like this (recommended): 44 45``` 46$ cd src 47$ git checkout main 48$ git new-branch your-branch-name 49``` 50 51See the [Android][webrtc-android-development] and [iOS][webrtc-ios-development] pages for separate instructions. 52 53**NOTICE:** if you get `Remote: Daily bandwidth rate limit exceeded for <ip>`, 54make sure you're logged in. The quota is much larger for logged in users. 55 56## Updating the Code 57 58Update your current branch with: 59 60``` 61$ git checkout main 62$ git pull origin main 63$ gclient sync 64$ git checkout my-branch 65$ git merge main 66``` 67 68## Building 69 70[Ninja][ninja] is the default build system for all platforms. 71 72See the [Android][webrtc-android-development] and [iOS][webrtc-ios-development] pages for build 73instructions specific to those platforms. 74 75## Generating Ninja project files 76 77[Ninja][ninja] project files are generated using [GN][gn]. They're put in a 78directory of your choice, like `out/Debug` or `out/Release`, but you can 79use any directory for keeping multiple configurations handy. 80 81To generate project files using the defaults (Debug build), run (standing in 82the src/ directory of your checkout): 83 84``` 85$ gn gen out/Default 86``` 87 88To generate ninja project files for a Release build instead: 89 90``` 91$ gn gen out/Default --args='is_debug=false' 92``` 93 94To clean all build artifacts in a directory but leave the current GN 95configuration untouched (stored in the args.gn file), do: 96 97``` 98$ gn clean out/Default 99``` 100 101To build the fuzzers residing in the [test/fuzzers][fuzzers] directory, use 102``` 103$ gn gen out/fuzzers --args='use_libfuzzer=true optimize_for_fuzzing=true' 104``` 105Depending on the fuzzer additional arguments like `is_asan`, `is_msan` or `is_ubsan_security` might be required. 106 107See the [GN][gn-doc] documentation for all available options. There are also more 108platform specific tips on the [Android][webrtc-android-development] and 109[iOS][webrtc-ios-development] instructions. 110 111## Compiling 112 113When you have Ninja project files generated (see previous section), compile 114(standing in `src/`) using: 115 116For [Ninja][ninja] project files generated in `out/Default`: 117 118``` 119$ autoninja -C out/Default 120``` 121 122To build everything in the generated folder (`out/Default`): 123 124``` 125$ autoninja all -C out/Default 126``` 127 128`autoninja` is a wrapper that automatically provides optimal values for the arguments passed to `ninja`. 129 130See [Ninja build rules][ninja-build-rules] to read more about difference between `ninja` and `ninja all`. 131 132 133## Using Another Build System 134 135Other build systems are **not supported** (and may fail), such as Visual 136Studio on Windows or Xcode on OSX. GN supports a hybrid approach of using 137[Ninja][ninja] for building, but Visual Studio/Xcode for editing and driving 138compilation. 139 140To generate IDE project files, pass the `--ide` flag to the [GN][gn] command. 141See the [GN reference][gn-doc] for more details on the supported IDEs. 142 143 144## Working with Release Branches 145 146To see available release branches, run: 147 148``` 149$ git branch -r 150``` 151 152To create a local branch tracking a remote release branch (in this example, 153the branch corresponding to Chrome M80): 154 155``` 156$ git checkout -b my_branch refs/remotes/branch-heads/3987 157$ gclient sync 158``` 159 160**NOTICE**: depot_tools are not tracked with your checkout, so it's possible gclient 161sync will break on sufficiently old branches. In that case, you can try using 162an older depot_tools: 163 164``` 165which gclient 166$ # cd to depot_tools dir 167$ # edit update_depot_tools; add an exit command at the top of the file 168$ git log # find a hash close to the date when the branch happened 169$ git checkout <hash> 170$ cd ~/dev/webrtc/src 171$ gclient sync 172$ # When done, go back to depot_tools, git reset --hard, run gclient again and 173$ # verify the current branch becomes REMOTE:origin/main 174``` 175 176The above is untested and unsupported, but it might help. 177 178Commit log for the branch: [https://webrtc.googlesource.com/src/+log/branch-heads/3987][m80-log] 179To browse it: [https://webrtc.googlesource.com/src/+/branch-heads/3987][m80] 180 181For more details, read Chromium's [Working with Branches][chromium-work-branches] and 182[Working with Release Branches][chromium-work-release-branches] pages. 183To find the branch corresponding to a Chrome release check the 184[Chromium Dashboard][https://chromiumdash.appspot.com/branches]. 185 186 187## Contributing Patches 188 189Please see [Contributing Fixes][contributing] for information on how to run 190`git cl upload`, getting your patch reviewed, and getting it submitted. You can also 191find info on how to run trybots and applying for try rights. 192 193[contributing]: https://webrtc.googlesource.com/src/+/refs/heads/main/docs/native-code/development/contributing.md 194 195 196## Chromium Committers 197 198Many WebRTC committers are also Chromium committers. To make sure to use the 199right account for pushing commits to WebRTC, use the `user.email` Git config 200setting. The recommended way is to have the chromium.org account set globally 201as described at the [depot tools setup page][depot-tools] and then set `user.email` 202locally for the WebRTC repos using (change to your webrtc.org address): 203 204``` 205$ cd /path/to/webrtc/src 206$ git config user.email [email protected] 207``` 208 209## Example Applications 210 211WebRTC contains several example applications, which can be found under 212`src/webrtc/examples`. Higher level applications are listed first. 213 214 215### Peerconnection 216 217Peerconnection consist of two applications using the WebRTC Native APIs: 218 219* A server application, with target name `peerconnection_server` 220* A client application, with target name `peerconnection_client` (not currently supported on Mac/Android) 221 222The client application has simple voice and video capabilities. The server 223enables client applications to initiate a call between clients by managing 224signaling messages generated by the clients. 225 226 227#### Setting up P2P calls between peerconnection_clients 228 229Start `peerconnection_server`. You should see the following message indicating 230that it is running: 231 232``` 233Server listening on port 8888 234``` 235 236Start any number of `peerconnection_clients` and connect them to the server. 237The client UI consists of a few parts: 238 239**Connecting to a server:** When the application is started you must specify 240which machine (by IP address) the server application is running on. Once that 241is done you can press **Connect** or the return button. 242 243**Select a peer:** Once successfully connected to a server, you can connect to 244a peer by double-clicking or select+press return on a peer's name. 245 246**Video chat:** When a peer has been successfully connected to, a video chat 247will be displayed in full window. 248 249**Ending chat session:** Press **Esc**. You will now be back to selecting a 250peer. 251 252**Ending connection:** Press **Esc** and you will now be able to select which 253server to connect to. 254 255 256#### Testing peerconnection_server 257 258Start an instance of `peerconnection_server` application. 259 260Open `src/webrtc/examples/peerconnection/server/server_test.html` in your 261browser. Click **Connect**. Observe that the `peerconnection_server` announces 262your connection. Open one more tab using the same page. Connect it too (with a 263different name). It is now possible to exchange messages between the connected 264peers. 265 266### STUN Server 267 268Target name `stunserver`. Implements the STUN protocol for Session Traversal 269Utilities for NAT as documented in [RFC 5389][rfc-5389]. 270 271 272### TURN Server 273 274Target name `turnserver`. Used for unit tests. 275 276 277[ninja]: https://ninja-build.org/ 278[ninja-build-rules]: https://gn.googlesource.com/gn/+/master/docs/reference.md#the-all-and-default-rules 279[gn]: https://gn.googlesource.com/gn/+/master/README.md 280[gn-doc]: https://gn.googlesource.com/gn/+/master/docs/reference.md#IDE-options 281[webrtc-android-development]: https://webrtc.googlesource.com/src/+/main/docs/native-code/android/index.md 282[webrtc-ios-development]: https://webrtc.googlesource.com/src/+/main/docs/native-code/ios/index.md 283[chromium-work-branches]: https://www.chromium.org/developers/how-tos/get-the-code/working-with-branches 284[chromium-work-release-branches]: https://www.chromium.org/developers/how-tos/get-the-code/working-with-release-branches 285[depot-tools]: http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up 286[rfc-5389]: https://tools.ietf.org/html/rfc5389 287[rfc-5766]: https://tools.ietf.org/html/rfc5766 288[m80-log]: https://webrtc.googlesource.com/src/+log/branch-heads/3987 289[m80]: https://webrtc.googlesource.com/src/+/branch-heads/3987 290[fuzzers]: https://webrtc.googlesource.com/src/+/main/test/fuzzers/ 291