diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 192 |
1 files changed, 46 insertions, 146 deletions
@@ -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: @@ -21,8 +21,8 @@ To get gclient, run the following command in your terminal: Then add the `depot_tools` folder to your `PATH` environment variable. Note that openscreen does not use other features of `depot_tools` like `repo` or -`drover`. However, some `git-cl` functions *do* work, like `git cl try`, `git cl -lint` and `git cl upload.` +`drover`. However, some `git-cl` functions *do* work, like `git cl try`, +`git cl format`, `git cl lint`, and `git cl upload.` ## Checking out code @@ -44,7 +44,7 @@ and at their appropriate revisions. ## Syncing your local checkout -To update your local checkout from the openscreen master repository, just run +To update your local checkout from the openscreen reference repository, just run ```bash cd ~/my_project_dir/openscreen @@ -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,80 +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 - -openscreen 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 | - -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 -openscreen library code should follow the [Open Screen Library Style +Open Screen library code should follow the [Open Screen Library Style Guide](docs/style_guide.md). -openscreen uses [Chromium Gerrit](https://chromium-review.googlesource.com/) for -patch management and code review (for better or worse). +This library uses [Chromium Gerrit](https://chromium-review.googlesource.com/) for +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 @@ -248,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 @@ -282,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 +# Additional resources -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/)). - -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) |