Add tools for code coverage support in iOS.

docs/ios/coverage.md

Index: docs/ios/coverage.md
diff --git a/docs/ios/coverage.md b/docs/ios/coverage.md
new file mode 100644
index 0000000000000000000000000000000000000000..e05a844ff0af2c160a2b9700a88f02f3cae1c4fd
--- /dev/null
+++ b/docs/ios/coverage.md
@@ -0,0 +1,56 @@
+# Generate code coverage data
+
+1.  Setup: Code coverage is only supported for Debug-iphonesimulator builds.

[sdefresne, 2017/04/27 08:26:26]

I think you can add a "Coverage" config in src/ios/build/tools/setup-gn.py (as
discussed offline). Once this is done, developer won't have anything to setup,
but instead can just select the correct configuration in Xcode (pro: building
and testing for coverage would not destroy what was previously built).

Note that it would still be good to document the "ios_enable_coverage" variable
here.

[lpromero, 2017/04/27 14:48:00]

Done.
What kind of info about ios_enable_coverage would you see fit here?

+    (gtest_include_ios_coverage, ENABLE_TEST_CODE_COVERAGE?)
+
+1.  Run a test target that supports code coverage, for example
+    `ios_showcase_egtests`. Targets that support test target call
+    `coverage_util::SetupIfNecessary()`.
+
+1.  Find the `coverage.profraw` in the Documents folder of the app. You can look
+    in the console output of the instrumented target. For example:
+
+    ```
+    Coverage data at /Users/johndoe/Library/Developer/CoreSimulator/Devices/
+    82D642FA-FC18-4EDB-AFE0-A17454804BE4/data/Containers/Data/Application/
+    E6B2B898-CE13-4958-93F3-E8B500446381/Documents/coverage.profraw
+    ```
+
+1.  Create a `coverage.profdata` file out of the `coverage.profraw` file:
+
+    `xcrun llvm-profdata merge -o out/Debug-iphonesimulator/coverage.profdata
+    path/to/coverage.profraw`
+
+1.  To see the **line coverage** for *all the instrumented source files*:
+
+    `xcrun llvm-cov show
+    out/Debug-iphonesimulator/ios_showcase_egtests.app/ios_showcase_egtests
+    -instr-profile=path/to/coverage.profdata -arch=x86_64`
+
+    ![](images/llvm-cov_show.png)
+
+    To see the **line coverage** for a *specific instrumented source
+    file/folder* (e.g. `ios/showcase/core/app_delegate.mm`):
+
+    `xcrun llvm-cov show
+    out/Debug-iphonesimulator/ios_showcase_egtests.app/ios_showcase_egtests
+    -instr-profile=path/to/coverage.profdata -arch=x86_64
+    ios/showcase/core/app_delegate.mm`
+
+    ![](images/llvm-cov_show_file.png)
+
+    To see a **complete report**:
+
+    `xcrun llvm-cov report
+    out/Debug-iphonesimulator/ios_showcase_egtests.app/ios_showcase_egtests
+    -instr-profile=path/to/coverage.profdata -arch=x86_64`
+
+    ![](images/llvm-cov_report.png)
+
+    To see a **report** for a *folder/file* (e.g. `ios/showcase/core` folder):
+
+    `xcrun llvm-cov show
+    out/Debug-iphonesimulator/ios_showcase_egtests.app/ios_showcase_egtests
+    -instr-profile=path/to/coverage.profdata -arch=x86_64 ios/showcase/core`
+
+    ![](images/llvm-cov_report_folder.png)