diff --git a/README.md b/README.md index 9463c9bd..b349ea1b 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,8 @@ $ cordova plugin add cordova-plugin-iosrtc ## Building -This plugin needs [Swift 2.0](https://developer.apple.com/swift/) support so some steps are needed to get your project working with it. These steps are explained in the [Building](docs/Building.md) documentation, please check it. - -**IMPORTANT:** The currently bundled libWebRTC does not contain bitcode, so you'll need to disable it in your Xcode project settings. +* [Building](docs/Building.md): Guidelines for building a Cordova iOS application including the *cordova-plugin-iosrtc* plugin. +* [Building `libwebrtc`](docs/BuildingLibWebRTC.md): Guidelines for building Google's *libwebrtc* with modifications needed by the *cordova-plugin-iosrtc* plugin. ## Usage diff --git a/docs/Building.md b/docs/Building.md index 829e6e9b..bfe0cbce 100644 --- a/docs/Building.md +++ b/docs/Building.md @@ -1,10 +1,19 @@ # Building + +### Requirements + +* This plugin needs [Swift 2.0](https://developer.apple.com/swift/) so Xcode >= 7.0 is required. +* The currently bundled *libwebrtc* does not contain bitcode, so you need to disable it in your Xcode project settings. + + +### Building Steps + An iOS Cordova application including the *cordova-plugin-iosrtc* plugin can be built using the [cordova-cli](https://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-Line%20Interface) or Xcode. -The plugin provides a ["hook"](../extra/hooks/iosrtc-swift-support.js) to automate required modifications in both *cordova-cli* and Xcode generated projects. These steps must be followed: +The plugin provides a ["hook"](../extra/hooks/iosrtc-swift-support.js) to automate required modifications in both *cordova-cli* and Xcode generated projects. -* Put the hook script under the "hooks/" folder of your Cordova project (or wherever you prefer) and give it execute permission: +* Put the hook script under the "hooks/" folder of your Cordova project (or wherever you prefer) and give it execution permission: ```bash $ chmod +x hooks/iosrtc-swift-support.js ``` @@ -31,7 +40,7 @@ $ cordova build ios ``` -## Bridging Header +#### Bridging Header The plugin is coded in Swift language but it makes use of the Cordova Objective-C headers and the [Google's WebRTC Objective-C wrapper](https://chromium.googlesource.com/external/webrtc/+/master/talk/app/webrtc/objc/) so a [Bridging Header](https://developer.apple.com/library/prerelease/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html) is required. When building (using the provided hook above) our [Bridging Header](../src/cordova-plugin-iosrtc-Bridging-Header.h) file is automatically added into your Cordova project. @@ -50,12 +59,12 @@ It may happen that your Cordova application uses more than a single plugin coded And then set `Unified-Bridging-Header.h` as the value of the "Objective-C Bridging Header" build setting in your Xcode project. For more information check this [issue](https://github.com/eface2face/cordova-plugin-iosrtc/issues/9). -## Xcode +#### Xcode If you still prefer to do it manually open it with Xcode and follow these steps: -- Set "iOS Deployment Target" to `7.0` or higher within your project settings. -- Set "Deployment Target" to `7.0` or higher within the project target settings. -- Within the project "Build Settings" add an entry to the "Runpath Search Paths" setting with value `@executable_path/Frameworks`. -- Within the project "Build Settings" set "Objective-C Bridging Header" to `PROJECT_NAME/Plugins/cordova-plugin-iosrtc/cordova-plugin-iosrtc-Bridging-Header.h` (read more about the "Bridging Header" above). -- Within the project "Build Settings" set "Enable Bitcode" to "No" (this will be addressed soon). +* Set "iOS Deployment Target" to `7.0` or higher within your project settings. +* Set "Deployment Target" to `7.0` or higher within the project target settings. +* Within the project "Build Settings" add an entry to the "Runpath Search Paths" setting with value `@executable_path/Frameworks`. +* Within the project "Build Settings" set "Objective-C Bridging Header" to `PROJECT_NAME/Plugins/cordova-plugin-iosrtc/cordova-plugin-iosrtc-Bridging-Header.h` (read more about the "Bridging Header" above). +* Within the project "Build Settings" set "Enable Bitcode" to "No". diff --git a/docs/BuildingLibWebRTC.md b/docs/BuildingLibWebRTC.md new file mode 100644 index 00000000..af7775ae --- /dev/null +++ b/docs/BuildingLibWebRTC.md @@ -0,0 +1,71 @@ +# Build *libwebrtc* for cordova-plugin-iosrtc + + +### Get the *libwebrtc* source code + +There are several ways to get and build the library. We choose a project that performs this task nicely: + +* Clone the [webrtc-build-scripts](https://github.com/pristineio/webrtc-build-scripts) project and enter into it: +```bash +$ git clone https://github.com/pristineio/webrtc-build-scripts +$ cd webrtc-build-scripts +``` + +* Follow the project steps and fetch the *libwebrtc* source code: +```bash +$ source ios/build.sh +$ WEBRTC_RELEASE=true +$ get_webrtc +``` + +* Set a specific *libwebrtc* version: +```bash +$ update2Revision 10800 +``` + + +### Apply `libwebrtc-objc-iosrtc.patch` + +Google's *libwebrtc* Objective-C code lacks of `addtrack` and `removetrack` events in its `RTCMediaStream` class, making imposible to emulate them at JavaScript level. Thus a patch is needed to enable these W3C WebRTC features. + +**eFace2Face** created such a patch and sent it to the Google's *WebRTC* project, but [it was rejected](https://webrtc-codereview.appspot.com/50109004/) by arguing that the future of the WebRTC API is "track based" rather than "stream based". + +Since we live in the present we need those two events to properly implement the W3C WebRTC API in *cordova-plugin-iosrtc*, and hence the [patch](../extra/libwebrtc-objc-iosrtc.patch) is provided in the source code. + +* Apply the patch provided at `extra/libwebrtc-objc-iosrtc.patch` into the Objective-C source code of *libwebrtc*: +```bash +$ cd ios/webrtc/src/talk/app/webrtc/objc +$ patch -p1 < PATH_TO_CORDOVA_PLUGIN_IOSRTC/extra/libwebrtc-objc-iosrtc.patch +``` + + +### Remove iOS native H264 encoder/decoder + +(see issue #92 for details, help welcome!) + +Edit `ios/webrtc/src/webrtc/modules/video_coding/codecs/h264/include/h264.h` by removing the line 21: +```c +#define WEBRTC_VIDEO_TOOLBOX_SUPPORTED 1 // <-- remove this line +``` + + +### Build *libwebrtc* + +* Go back to the `webrtc-build-scripts` root folder and build *libwebrtc*: +```bash +$ cd ../../../../../../../ +$ build_webrtc +``` + +* Copy the *libwebrtc* Objective-C headers to *cordova-plugin-iosrtc*: +```bash +$ rm -f PATH_TO_CORDOVA_PLUGIN_IOSRTC/src/webrtc-headers/* +$ cp ios/webrtc/src/talk/app/webrtc/objc/public/* PATH_TO_CORDOVA_PLUGIN_IOSRTC/src/webrtc-headers/ +``` + +* Copy the *libwebrtc* static library to *cordova-plugin-iosrtc*: +```bash +$ rm -f PATH_TO_CORDOVA_PLUGIN_IOSRTC/lib/* +$ cp ios/webrtc/libWebRTC-LATEST-Universal-Release.a PATH_TO_CORDOVA_PLUGIN_IOSRTC/lib/ +``` + diff --git a/docs/index.md b/docs/index.md index 31f56aab..2b7b84a7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,7 @@ * [`iosrtc` API](iosrtc.md): JavaScript API Documentation. * [Building](Building.md): Guidelines for building a Cordova iOS application including the *cordova-plugin-iosrtc* plugin. +* [Building `libwebrtc`](BuildingLibWebRTC.md): Guidelines for building Google's *libwebrtc* with modifications needed by the *cordova-plugin-iosrtc* plugin. * [`