[Open Screen] Update README.md

This updates content in README.md and breaks out some sections into
separate files, to keep the length more manageable.

Change-Id: I236ae43cd7323af8a11086ffe6c56ddb81b67a0c
Reviewed-on: https://chromium-review.googlesource.com/c/openscreen/+/3028486
Reviewed-by: Jordan Bayles <jophba@chromium.org>
Reviewed-by: Ryan Keane <rwkeane@google.com>
Commit-Queue: mark a. foltz <mfoltz@chromium.org>

6 files changed, 158 insertions, 150 deletions

diff --git a/COMMITTERS b/COMMITTERS
index 770a6ccd..30c64fbc 100644
--- a/COMMITTERS
+++ b/COMMITTERS
@@ -1,9 +1,8 @@
-# Primary reviewers
 mfoltz@chromium.org
 btolsch@chromium.org
-
-# Additional reviewers
 jopbha@chromium.org
-miu@chromium.org
-rwkeane@chromium.org
-yakimakha@chromium.org
+rwkeane@google.com
+takumif@chromium.org
+
+# Add for LUCI configuration changes.
+cliffordcheng@chromium.org
diff --git a/README.md b/README.md
index 32db40b0..5e374a0b 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,16 @@
 # Open Screen Library
 
-The openscreen library implements the Open Screen Protocol and the Chromecast
-protocols (both control and streaming).
+The Open Screen Library implements the Open Screen Protocol and the Chromecast
+protocols (discovery, application control, and media streaming).
 
-Information about the protocol and its specification can be found [on
-GitHub](https://github.com/webscreens/openscreenprotocol).
+Information about the Open Screen Protocol and its specification can be found
+[on GitHub](https://w3c.github.io/openscreenprotocol/).
 
 # Getting the code
 
 ## Installing depot_tools
 
-openscreen library dependencies are managed using `gclient`, from the
+Library dependencies are managed using `gclient`, from the
 [depot_tools](https://www.chromium.org/developers/how-tos/depottools) repo.
 
 To get gclient, run the following command in your terminal:
@@ -93,7 +93,8 @@ Setting the `gn` argument "is_gcc=true" on Linux enables building using gcc
 instead.
 
 ```bash
-  gn gen out/Default --args="is_gcc=true"
+  mkdir out/debug-gcc
+  gn gen out/debug-gcc --args="is_gcc=true"
 ```
 
 Note that g++ version 7 or newer must be installed.  On Debian flavors you can
@@ -114,7 +115,7 @@ installed.
 Setting the `gn` argument "is_debug=true" enables debug build.
 
 ```bash
-  gn gen out/Default --args="is_debug=true"
+  gn gen out/debug --args="is_debug=true"
 ```
 
 To install debug information for libstdc++ 8 on Debian flavors, you can run:
@@ -129,30 +130,34 @@ Running `gn args` opens an editor that allows to create a list of arguments
 passed to every invocation of `gn gen`.
 
 ```bash
-  gn args out/Default
+  gn args out/debug
 ```
 
 # Building targets
 
-## Building the OSP demo
+## Cast Streaming sender and receiver
 
-The following commands will build a sample executable and run it.
+TODO(jophba): Fill in details
+
+## OSP demo
+
+The following commands will build the Open Screen Protocol demo and run it.
 
 ``` bash
-  mkdir out/Default
-  gn gen out/Default          # Creates the build directory and necessary ninja files
-  ninja -C out/Default demo   # Builds the executable with ninja
-  ./out/Default/demo          # Runs the executable
+  mkdir out/debug
+  gn gen out/debug             # Creates the build directory and necessary ninja files
+  ninja -C out/debug osp_demo  # Builds the executable with ninja
+  ./out/debug/osp_demo          # Runs the executable
 ```
 
 The `-C` argument to `ninja` works just like it does for GNU Make: it specifies
 the working directory for the build.  So the same could be done as follows:
 
 ``` bash
-  ./gn gen out/Default
-  cd out/Default
-  ninja
-  ./demo
+  ./gn gen out/debug
+  cd out/debug
+  ninja osp_demo
+  ./osp_demo
 ```
 
 After editing a file, only `ninja` needs to be rerun, not `gn`.  If you have
@@ -163,83 +168,41 @@ Unless you like to wait longer than necessary for builds to complete, run
 This will automatically parallelize the build for your system, depending on
 number of processor cores, RAM, etc.
 
-For details on running `demo`, see its [README.md](demo/README.md).
+For details on running `osp_demo`, see its [README.md](osp/demo/README.md).
 
 ## Building other targets
 
-Running `ninja -C out/Default gn_all` will build all non-test targets in the
+Running `ninja -C out/debug gn_all` will build all non-test targets in the
 repository.
 
-`gn ls --type=executable out/Default/` will list all of the executable targets
+`gn ls --type=executable out/debug` will list all of the executable targets
 that can be built.
 
-If you want to customize the build further, you can run `gn args out/Default` to
-pull up an editor for build flags. `gn args --list out/Default` prints all of
+If you want to customize the build further, you can run `gn args out/debug` to
+pull up an editor for build flags. `gn args --list out/debug` prints all of
 the build flags available.
 
 ## Building and running unit tests
 
 ```bash
-  ninja -C out/Default unittests
-  ./out/Default/unittests
-```
-
-## Building and running fuzzers
-
-In order to build fuzzers, you need the GN arg `use_libfuzzer=true`.  It's also
-recommended to build with `is_asan=true` to catch additional problems.  Building
-and running then might look like:
-```bash
-  gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true is_debug=false"
-  ninja -C out/libfuzzer some_fuzz_target
-  out/libfuzzer/some_fuzz_target <args> <corpus_dir> [additional corpus dirs]
+  ninja -C out/debug openscreen_unittests
+  ./out/debug/openscreen_unittests
 ```
 
-The arguments to the fuzzer binary should be whatever is listed in the GN target
-description (e.g. `-max_len=1500`).  These arguments may be automatically
-scraped by Chromium's ClusterFuzz tool when it runs fuzzers, but they are not
-built into the target.  You can also look at the file
-`out/libfuzzer/some_fuzz_target.options` for what arguments should be used.  The
-`corpus_dir` is listed as `seed_corpus` in the GN definition of the fuzzer
-target.
-
-# Continuous build and try jobs
-
-Open Screen uses [LUCI builders](https://ci.chromium.org/p/openscreen/builders)
-to monitor the build and test health of the library.
-
-Current builders include:
-
-| Name                   | Arch   | OS                 | Toolchain | Build   | Notes                  |
-|------------------------|--------|--------------------|-----------|---------|------------------------|
-| linux64_debug          | x86-64 | Ubuntu Linux 16.04 | clang     | debug   | ASAN enabled           |
-| linux64_gcc_debug      | x86-64 | Ubuntu Linux 18.04 | gcc-7     | debug   |                        |
-| linux64_tsan           | x86-64 | Ubuntu Linux 16.04 | clang     | release | TSAN enabled           |
-| mac_debug              | x86-64 | Mac OS X/Xcode     | clang     | debug   |                        |
-| chromium_linux64_debug | x86-64 | Ubuntu Linux 16.04 | clang     | debug   | built within chromium  |
-| chromium_mac_debug     | x86-64 | Mac OS X/Xcode     | clang     | debug   | built within chromium  |
-| linux64_coverage_debug | x86-64 | Ubuntu Linux 16.04 | clang     | debug   | used for code coverage |
-<br />
-
-You can run a patch through the try job queue (which tests it on all
-non-chromium builders) using `git cl try`, or through Gerrit (details below).
-
-The chromium builders compile openscreen HEAD vs. chromium HEAD.  They run as
-experimental trybots and continuous-integration FYI bots.
-
-# Submitting changes
+# Contributing changes
 
 Open Screen library code should follow the [Open Screen Library Style
 Guide](docs/style_guide.md).
 
 This library uses [Chromium Gerrit](https://chromium-review.googlesource.com/) for
-patch management and code review (for better or worse).
+patch management and code review (for better or worse).  You will need to register
+for an account at `chromium-review.googlesource.com` to upload patches for review.
 
 The following sections contain some tips about dealing with Gerrit for code
 reviews, specifically when pushing patches for review, getting patches reviewed,
 and committing patches.
 
-## Uploading a patch for review
+# Uploading a patch for review
 
 The `git cl` tool handles details of interacting with Gerrit (the Chromium code
 review tool) and is recommended for pushing patches for review.  Once you have
@@ -251,7 +214,7 @@ committed changes locally, simply run:
 ```
 
 The first command will will auto-format the code changes. Then, the second
-command runs the `PRESUBMIT.sh` script to check style and, if it passes, a
+command runs the `PRESUBMIT.py` script to check style and, if it passes, a
 newcode review will be posted on `chromium-review.googlesource.com`.
 
 If you make additional commits to your local branch, then running `git cl
@@ -285,82 +248,16 @@ Send your patch to one or more committers in the
 file for code review.  All patches must receive at least one LGTM by a committer
 before it can be submitted.
 
-## Submission
+## Submitting patches
 
 After your patch has received one or more LGTM commit it by clicking the
 `SUBMIT` button (or, confusingly, `COMMIT QUEUE +2`) in Gerrit.  This will run
 your patch through the builders again before committing to the main openscreen
 repository.
 
-<!-- TODO(mfoltz): split up README.md into more manageable files. -->
-## Working with ARM/ARM64/the Raspberry PI
-
-openscreen supports cross compilation for both arm32 and arm64 platforms, by
-using the `gn args` parameter `target_cpu="arm"` or `target_cpu="arm64"`
-respectively. Note that quotes are required around the target arch value.
-
-Setting an arm(64) target_cpu causes GN to pull down a sysroot from openscreen's
-public cloud storage bucket. Google employees may update the sysroots stored
-by requesting access to the Open Screen pantheon project and uploading a new
-tar.xz to the openscreen-sysroots bucket.
-
-NOTE: The "arm" image is taken from Chromium's debian arm image, however it has
-been manually patched to include support for libavcodec and libsdl2. To update
-this image, the new image must be manually patched to include the necessary
-header and library dependencies. Note that if the versions of libavcodec and
-libsdl2 are too out of sync from the copies in the sysroot, compilation will
-succeed, but you may experience issues decoding content.
-
-To install the last known good version of the libavcodec and libsdl packages
-on a Raspberry Pi, you can run the following command:
-
-```bash
-sudo ./cast/standalone_receiver/install_demo_deps_raspian.sh
-```
-
-NOTE: until [Issue 106](http://crbug.com/openscreen/106) is resolved, you may
-experience issues streaming to a Raspberry Pi if multiple network interfaces
-(e.g. WiFi + Ethernet) are enabled. The workaround is to disable either the WiFi
-or ethernet connection.
-
-## Code Coverage
-
-Code coverage can be checked using clang's source-based coverage tools.  You
-must use the GN argument `use_coverage=true`.  It's recommended to do this in a
-separate output directory since the added instrumentation will affect
-performance and generate an output file every time a binary is run.  You can
-read more about this in [clang's
-documentation](http://clang.llvm.org/docs/SourceBasedCodeCoverage.html) but the
-bare minimum steps are also outlined below.  You will also need to download the
-pre-built clang coverage tools, which are not downloaded by default.  The
-easiest way to do this is to set a custom variable in your `.gclient` file.
-Under the "openscreen" solution, add:
-```python
-  "custom_vars": {
-    "checkout_clang_coverage_tools": True,
-  },
-```
-then run `gclient runhooks`.  You can also run the python command from the
-`clang_coverage_tools` hook in `//DEPS` yourself or even download the tools
-manually
-([link](https://storage.googleapis.com/chromium-browser-clang-staging/)).
+# Additional resources
 
-Once you have your GN directory (we'll call it `out/coverage`) and have
-downloaded the tools, do the following to generate an HTML coverage report:
-```bash
-out/coverage/openscreen_unittests
-third_party/llvm-build/Release+Asserts/bin/llvm-profdata merge -sparse default.profraw -o foo.profdata
-third_party/llvm-build/Release+Asserts/bin/llvm-cov show out/coverage/openscreen_unittests -instr-profile=foo.profdata -format=html -output-dir=<out dir> [filter paths]
-```
-There are a few things to note here:
- - `default.profraw` is generated by running the instrumented code, but
- `foo.profdata` can be any path you want.
- - `<out dir>` should be an empty directory for placing the generated HTML
- files.  You can view the report at `<out dir>/index.html`.
- - `[filter paths]` is a list of paths to which you want to limit the coverage
- report.  For example, you may want to limit it to cast/ or even
- cast/streaming/.  If this list is empty, all data will be in the report.
-
-The same process can be used to check the coverage of a fuzzer's corpus.  Just
-add `-runs=0` to the fuzzer arguments to make sure it only runs the existing
-corpus then exits.
+* [Continuous builders](docs/continuous_build.md)
+* [Building and running fuzz tests](docs/fuzzing.md)
+* [Running on a Raspberry PI](docs/raspberry_pi.md)
+* [Unit test code coverage](docs/code_coverage.md)
diff --git a/docs/code_coverage.md b/docs/code_coverage.md
new file mode 100644
index 00000000..1c181ee8
--- /dev/null
+++ b/docs/code_coverage.md
@@ -0,0 +1,41 @@
+# Code Coverage
+
+Code coverage can be checked using clang's source-based coverage tools.  You
+must use the GN argument `use_coverage=true`.  It's recommended to do this in a
+separate output directory since the added instrumentation will affect
+performance and generate an output file every time a binary is run.  You can
+read more about this in [clang's documentation](
+http://clang.llvm.org/docs/SourceBasedCodeCoverage.html) but the
+bare minimum steps are also outlined below.  You will also need to download the
+pre-built clang coverage tools, which are not downloaded by default.  The
+easiest way to do this is to set a custom variable in your `.gclient` file.
+Under the "openscreen" solution, add:
+```python
+  "custom_vars": {
+    "checkout_clang_coverage_tools": True,
+  },
+```
+then run `gclient runhooks`.  You can also run the python command from the
+`clang_coverage_tools` hook in `//DEPS` yourself or even download the tools
+manually
+([link](https://storage.googleapis.com/chromium-browser-clang-staging/)).
+
+Once you have your GN directory (we'll call it `out/coverage`) and have
+downloaded the tools, do the following to generate an HTML coverage report:
+```bash
+out/coverage/openscreen_unittests
+third_party/llvm-build/Release+Asserts/bin/llvm-profdata merge -sparse default.profraw -o foo.profdata
+third_party/llvm-build/Release+Asserts/bin/llvm-cov show out/coverage/openscreen_unittests -instr-profile=foo.profdata -format=html -output-dir=<out dir> [filter paths]
+```
+There are a few things to note here:
+ - `default.profraw` is generated by running the instrumented code, but
+ `foo.profdata` can be any path you want.
+ - `<out dir>` should be an empty directory for placing the generated HTML
+ files.  You can view the report at `<out dir>/index.html`.
+ - `[filter paths]` is a list of paths to which you want to limit the coverage
+ report.  For example, you may want to limit it to cast/ or even
+ cast/streaming/.  If this list is empty, all data will be in the report.
+
+The same process can be used to check the coverage of a fuzzer's corpus.  Just
+add `-runs=0` to the fuzzer arguments to make sure it only runs the existing
+corpus then exits.
diff --git a/docs/continuous_build.md b/docs/continuous_build.md
new file mode 100644
index 00000000..1c38a130
--- /dev/null
+++ b/docs/continuous_build.md
@@ -0,0 +1,27 @@
+# Continuous build and try jobs
+
+Open Screen uses [LUCI builders](https://ci.chromium.org/p/openscreen/builders)
+to monitor the build and test health of the library.
+
+Current builders include:
+
+| Name                   | Arch   | OS                     | Toolchain | Build   | Notes                  |
+|------------------------|--------|------------------------|-----------|---------|------------------------|
+| linux64_debug          | x86-64 | Ubuntu Linux 18.04     | clang     | debug   | ASAN enabled           |
+| linux_arm64_debug      | arm64  | Ubuntu Linux 20.04 [*] | clang     | debug   |                        |
+| linux64_gcc_debug      | x86-64 | Ubuntu Linux 18.04     | gcc-7     | debug   |                        |
+| linux64_tsan           | x86-64 | Ubuntu Linux 18.04     | clang     | release | TSAN enabled           |
+| linux64_coverage_debug | x86-64 | Ubuntu Linux 18.04     | clang     | debug   | used for code coverage |
+| mac_debug              | x86-64 | Mac OS X/Xcode         | clang     | debug   |                        |
+| chromium_linux64_debug | x86-64 | Ubuntu Linux 18.04     | clang     | debug   | built with chromium    |
+| chromium_mac_debug     | x86-64 | Mac OS X 10.15         | clang     | debug   | built with chromium    |
+<br />
+
+[*] Tests run on Ubuntu 20.04, but are cross-compiled to arm64 with a debian stretch sysroot.
+
+The chromium_ builders compile against Chromium top-of-tree to ensure that
+changes can be autorolled into Chromium.
+
+You can run a patch through all builders using `git cl try` or the Gerrit Web
+interface.  All builders are run as part of the commit queue and are also run
+continuously in our CI.
diff --git a/docs/fuzzing.md b/docs/fuzzing.md
new file mode 100644
index 00000000..427165b7
--- /dev/null
+++ b/docs/fuzzing.md
@@ -0,0 +1,19 @@
+# Building and running fuzzers
+
+In order to build fuzzers, you need the GN arg `use_libfuzzer=true`.  It's also
+recommended to build with `is_asan=true` to catch additional problems.  Building
+and running then might look like:
+```bash
+  gn gen out/libfuzzer --args="use_libfuzzer=true is_asan=true is_debug=false"
+  ninja -C out/libfuzzer some_fuzz_target
+  out/libfuzzer/some_fuzz_target <args> <corpus_dir> [additional corpus dirs]
+```
+
+The arguments to the fuzzer binary should be whatever is listed in the GN target
+description (e.g. `-max_len=1500`).  These arguments may be automatically
+scraped by Chromium's ClusterFuzz tool when it runs fuzzers, but they are not
+built into the target.  You can also look at the file
+`out/libfuzzer/some_fuzz_target.options` for what arguments should be used.  The
+`corpus_dir` is listed as `seed_corpus` in the GN definition of the fuzzer
+target.
+
diff --git a/docs/raspberry_pi.md b/docs/raspberry_pi.md
new file mode 100644
index 00000000..b61315cd
--- /dev/null
+++ b/docs/raspberry_pi.md
@@ -0,0 +1,25 @@
+# Working with ARM/ARM64/the Raspberry PI
+
+Open Screen Library supports cross compilation for both arm32 and arm64
+platforms, by using the `gn args` parameter `target_cpu="arm"` or
+`target_cpu="arm64"` respectively. Note that quotes are required around the
+target arch value.
+
+Setting an arm(64) target_cpu causes GN to pull down a sysroot from openscreen's
+public cloud storage bucket. Google employees may update the sysroots stored
+by requesting access to the Open Screen pantheon project and uploading a new
+tar.xz to the openscreen-sysroots bucket.
+
+NOTE: The "arm" image is taken from Chromium's debian arm image, however it has
+been manually patched to include support for libavcodec and libsdl2. To update
+this image, the new image must be manually patched to include the necessary
+header and library dependencies. Note that if the versions of libavcodec and
+libsdl2 are too out of sync from the copies in the sysroot, compilation will
+succeed, but you may experience issues decoding content.
+
+To install the last known good version of the libavcodec and libsdl packages
+on a Raspberry Pi, you can run the following command:
+
+```bash
+sudo ./cast/standalone_receiver/install_demo_deps_raspian.sh
+```