Snap for 8191477 from a1f37d7e15e391e1973053f8d58f07e4d240f1b4 to tm-frc-networking-releaset_frc_net_330443000android13-frc-networking-release

Change-Id: Iff62f16fb0e7cc82eb21181ef3077fa745bcbb75

6 files changed, 123 insertions, 50 deletions

diff --git a/docs/advanced_gerrit.md b/docs/advanced_gerrit.md
index 790ee359..7b14d922 100644
--- a/docs/advanced_gerrit.md
+++ b/docs/advanced_gerrit.md
@@ -26,58 +26,18 @@ following command:
   chmod a+x .git/hooks/commit-msg
 ```
 
-### Uploading a new patch for review 
+### Uploading a new patch for review
 
-You should run `PRESUBMIT.sh` in the root of the repository before pushing for
+You should run `git cl presubmit --upload` in the root of the repository before pushing for
 review (which primarily checks formatting).
 
-There is official [Gerrit
-documentation](https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.7/user-upload.html#push_create)
-for this which essentially amounts to:
+After verifying that presubmission works correctly, you can then execute:
+`git cl upload`, which will prompt you to verify the commit message and check
+for owners.
 
-``` bash
-  git push origin HEAD:refs/for/master
-```
-
-Gerrit keeps track of changes using a [Change-Id
-line](https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.7/user-changeid.html)
-in each commit.
-
-When there is no `Change-Id` line, Gerrit creates a new `Change-Id` for the
-commit, and therefore a new change.  Gerrit's documentation for
-[replacing a change](https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.7/user-upload.html#push_replace)
-describes this.  So if you want to upload a new patchset to an existing review,
-it should contain the matching `Change-Id` line in the commit message.
-
-### Adding a new patchset to an existing change
-
-By default, each commit to your local branch will get its own Gerrit change when
-pushed, unless it has a `Change-Id` corresponding to an existing review.
-
-If you need to modify commits on your local branch to ensure they have the
-correct `Change-Id`, you can do one of two things:
-
-After committing to the local branch, run:
-
-```bash
-  git commit --amend
-  git show
-```
-
-to attach the current `Change-Id` to the most recent commit. Check that the
-correct one was inserted by comparing it with the one shown on
-`chromium-review.googlesource.com` for the existing review.
-
-If you have made multiple local commits, you can squash them all into a single
-commit with the correct Change-Id:
-
-```bash
-  git rebase -i HEAD~4
-  git show
-```
-
-where '4' means that you want to squash three additional commits onto an
-existing commit that has been uploaded for review.
+The first time you upload an issue, the issue number is associated with the
+current branch. If you upload again, it uploads on the same issue (which is tied
+to the branch, not the commit). See the [git-cl](https://chromium.googlesource.com/chromium/tools/depot_tools.git/+/HEAD/README.git-cl.md) documentation for more information.
 
 ## Uploading a new dependent change
 
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..53c68e21
--- /dev/null
+++ b/docs/continuous_build.md
@@ -0,0 +1,28 @@
+# 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 |
+| linux64_cast_e2e     | x86-64 | Ubuntu Linux 18.04     | clang     | debug   | Builds cast standalone |
+| 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
+```
diff --git a/docs/style_guide.md b/docs/style_guide.md
index dfc6ab1a..2174411e 100644
--- a/docs/style_guide.md
+++ b/docs/style_guide.md
@@ -1,6 +1,6 @@
 # Open Screen Library Style Guide
 
-The Open Screen Library follows the [Chromium C++ coding style](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md)
+The Open Screen Library follows the [Chromium C++ coding style](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md)
 which, in turn, defers to the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
 We also follow the [Chromium C++ Do's and Don'ts](https://sites.google.com/a/chromium.org/dev/developers/coding-style/cpp-dos-and-donts).
 
@@ -188,4 +188,4 @@ not explicitly sprinkle "#if OSP_DCHECK_IS_ON()" guards all around any
 functions, variables, etc. that will be unused in "DCHECK off" builds.
 
 Use OSP_DCHECK and OSP_CHECK in accordance with the
-[Chromium guidance for DCHECK/CHECK](https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md#check_dcheck_and-notreached).
+[Chromium guidance for DCHECK/CHECK](https://chromium.googlesource.com/chromium/src/+/main/styleguide/c++/c++.md#check_dcheck_and-notreached).