1# Prerequisites 2 3Node v14 or later is required to run tests. We use npm (the Node Package Manager) to install 4test dependencies. Recent installations of Node have npm as well. 5CanvasKit has no other external source dependencies. 6 7To compile CanvasKit, you will first need to [install `emscripten`][1]. This 8will set the environment `EMSDK` (among others) which is required for 9compilation. Which version should you use? [`/infra/wasm-common/docker/emsdk-base/Dockerfile`][2] 10shows the version we build and test with. We try to use as recent a version of emscripten as 11is reasonable. 12 13[1]: https://emscripten.org/docs/getting_started/downloads.html 14[2]: https://github.com/google/skia/blob/main/infra/wasm-common/docker/emsdk-base/Dockerfile 15 16Be sure to both install **and** activate the correct version. For example: 17``` 18 ./emsdk install 2.0.20 19 ./emsdk activate 2.0.20 20``` 21 22This document also assumes you have followed the instructions to download Skia and its deps 23<https://skia.org/user/download>. 24 25## MacOS specific notes 26Make sure you have Python3 installed, otherwise the downloading emscripten toolchain 27can fail with errors about SSL certificates. <https://github.com/emscripten-core/emsdk/pull/273> 28 29See also <https://github.com/emscripten-core/emscripten/issues/9036#issuecomment-532092743> 30for a solution to Python3 using the wrong certificates. 31 32# Compile and Run Local Example 33 34``` 35# The following installs all npm dependencies and only needs to be when setting up 36# or if our npm dependencies have changed (rarely). 37npm ci 38 39make release # make debug is much faster and has better error messages 40make local-example 41``` 42 43This will print a local endpoint for viewing the example. You can experiment 44with the CanvasKit API by modifying `./npm_build/example.html` and refreshing 45the page. For some more experimental APIs, there's also `./npm_build/extra.html`. 46 47For other available build targets, see `Makefile` and `compile.sh`. 48For example, building a stripped-down version of CanvasKit with no text support or 49any of the "extras", one might run: 50 51 ./compile.sh no_skottie no_particles no_font 52 53Such a stripped-down version is about half the size of the default release build. 54 55# Unit tests, performance tests, and coverage. 56 57To run unit tests and compute test coverage on a debug gpu build 58 59``` 60make debug 61make test-continuous 62``` 63 64This reads karma.conf.js, and opens a chrome browser and begins running all the test 65in `test/` it will detect changes to the tests in that directory and automatically 66run again, however it will automatically rebuild and reload canvaskit. Closing the 67chrome window will just cause it to re-opened. Kill the karma process to stop continuous 68monitoring for changes. 69 70The tests are run with whichever build of canvaskit you last made. be sure to also 71test with `release`, `debug_cpu`, and `release_cpu`. testing with release builds will 72expose problems in closure compilation and usually forgotten externs. 73 74## Coverage 75 76Coverage will be automatically computed when running test-continuous locally. Note that 77the results will only be useful when testing a debug build. Open 78`coverage/<browser version>/index.html` For a summary and detailed line-by-line result. 79 80## Measuring Performance 81 82We use puppeteer to run a Chrome browser to gather performance data in a consistent way. 83See //tools/perf-canvaskit-puppeteer for more. 84 85## Adding tests 86 87The tests in `tests/` are grouped into files by topic. 88Within each file there are `describe` blocks further organizing the tests, and within those 89`it()` functions which test particular behaviors. `describe` and `it` are jasmine methods 90which can both be temporarily renamed `fdescribe` and `fit`. Which causes jasmine to only those. 91 92We have also defined `gm` which is a method for defining a test which draws something to a canvas 93that is shapshotted and reported to gold.skia.org, where you can compare it with the snapshot at 94head. 95 96## Testing from Gerrit 97 98When submitting a CL in gerrit, click "choose tryjobs" and type canvaskit to filter them. 99select all of them, which at the time of this writing is four jobs, for each combination 100of perf/test gpu/cpu. 101 102The performance results are reported to perf.skia.org 103gold results are reported to gold.skia.org 104 105Coverage is not measured while running tests this way. 106 107# Inspecting output WASM 108 109The `wasm2wat` tool from [the WebAssembly Binary Toolkit](https://github.com/WebAssembly/wabt) 110can be used to produce a human-readable text version of a `.wasm` file. 111 112The output of `wasm2wat --version` should be `1.0.13 (1.0.17)`. This version has been checked to 113work with the tools in `wasm_tools/SIMD/`. These tools programmatically inspect the `.wasm` output 114of a CanvasKit build to detect the presence of [wasm SIMD](https://github.com/WebAssembly/simd) 115operations. 116 117# Infrastructure Playbook 118 119When dealing with CanvasKit (or PathKit) on our bots, we use Docker. Check out 120$SKIA_ROOT/infra/wasm-common/docker/README.md for more on building/editing the 121images used for building and testing. 122 123## Updating the version of Emscripten we build/test with 124 125This presumes you have updated emscripten locally to a newer version of the 126sdk and verified/fixed any build issues that have arisen. 127 128 1. Edit `$SKIA_ROOT/infra/wasm-common/docker/emsdk-base/Dockerfile` to install 129 and activate the desired version of Emscripten. 130 2. Edit `$SKIA_ROOT/infra/wasm-common/docker/Makefile` to have `EMSDK_VERSION` be 131 set to that desired version. If there is a suffix that is not `_v1`, reset 132 it to be `_v1`. If testing the image later does not work and edits are made 133 to the emsdk-base Dockerfile to correct that, increment to `_v2`,`_v3`, etc 134 to force the bots to pick up the new image. 135 3. In `$SKIA_ROOT/infra/wasm-common/docker/`, run `make publish_emsdk_base` 136 4. Edit `$SKIA_ROOT/infra/canvaskit/docker/canvaskit-emsdk/Dockerfile` to be based 137 off the new version from step 2. CanvasKit has its own docker image because 138 it needs a few extra dependencies to build with font support. 139 5. Edit `$SKIA_ROOT/infra/canvaskit/docker/Makefile` to have the same version 140 from step 2. It's easiest to keep the `emsdk-base` and `canvaskit-emsdk` versions 141 be in lock-step. 142 6. In `$SKIA_ROOT/infra/canvaskit/docker/`, run `make publish_canvaskit_emsdk`. 143 7. In `$SKIA_ROOT/infra/bots/recipe_modules/build/`, update `canvaskit.py` 144 and `pathkit.py` to have `DOCKER_IMAGE` point to the desired tagged Docker 145 containers from steps 2 and 5 (which should be the same). 146 8. In `$SKIA_ROOT/infra/bots/task_drivers/compile_wasm_gm_tests.go`, update dockerImage 147 to refer to the desired Docker containers from steps 2 and 5. 148 9. In `$SKIA_ROOT/infra/bots/`, run `make train` to re-train the recipes. 149 10. Optional: Run something like `git grep 1\\.38\\.` in `$SKIA_ROOT` to see if 150 there are any other references that need updating. 151 11. Upload a CL with all the changes. Run all Test.+CanvasKit, Perf.+Puppeteer, 152 Test.+PathKit, Perf.+PathKit jobs to make sure the new builds pass all 153 tests and don't crash the perf harnesses. 154 12. Send out CL for review. Feel free to point the reviewer at these steps. 155