139 lines
5.9 KiB
Markdown
139 lines
5.9 KiB
Markdown
# Prerequisites
|
|
|
|
Node v14 or later is required to run tests. We use npm (the Node Package Manager) to install
|
|
test dependencies. Recent installations of Node have npm as well.
|
|
CanvasKit has no other external source dependencies.
|
|
|
|
## Compiling with GN
|
|
To build with GN, you need to have followed the instructions to download Skia and its deps
|
|
<https://skia.org/user/download>.
|
|
|
|
To compile CanvasKit, you will first need to [download and activate `emscripten`][1] using the
|
|
script in `//bin/activate-emsdk` (or `//bin/git-sync-deps` which also calls activate-emsdk).
|
|
This places the associated files in `//third_party/externals/emsdk` and the GN[2] build scripts
|
|
will use those by default.
|
|
The compile.sh script automates the default GN settings; users are free to set their own. If users
|
|
want to use their own version of emscripten, they should set the `skia_emsdk_dir` argument
|
|
(see `//skia/gn/toolchain/wasm.gni`). For other available arguments, see
|
|
`//modules/canvaskit/BUILD.gn`.
|
|
|
|
[1]: https://emscripten.org/
|
|
[2]: https://chromium.googlesource.com/chromium/src/tools/gn/+/48062805e19b4697c5fbd926dc649c78b6aaa138/README.md
|
|
|
|
### MacOS specific notes
|
|
Make sure you have Python3 installed, otherwise the downloading emscripten toolchain
|
|
can fail with errors about SSL certificates. <https://github.com/emscripten-core/emsdk/pull/273>
|
|
|
|
See also <https://github.com/emscripten-core/emscripten/issues/9036#issuecomment-532092743>
|
|
for a solution to Python3 using the wrong certificates.
|
|
|
|
# Compile and Run Local Example
|
|
|
|
```
|
|
# The following installs all npm dependencies and only needs to be when setting up
|
|
# or if our npm dependencies have changed (rarely).
|
|
npm ci
|
|
|
|
make release # make debug is much faster and has better error messages
|
|
make local-example
|
|
```
|
|
|
|
This will print a local endpoint for viewing the example. You can experiment
|
|
with the CanvasKit API by modifying `./npm_build/example.html` and refreshing
|
|
the page. For some more experimental APIs, there's also `./npm_build/extra.html`.
|
|
|
|
For other available build targets, see `Makefile` and `compile.sh`.
|
|
For example, building a stripped-down version of CanvasKit with no text support or
|
|
any of the "extras", one might run:
|
|
|
|
./compile.sh no_skottie no_particles no_font
|
|
|
|
Such a stripped-down version is about half the size of the default release build.
|
|
|
|
# Unit tests, performance tests, and coverage.
|
|
|
|
To run unit tests and compute test coverage on a debug gpu build
|
|
|
|
```
|
|
make debug
|
|
make test-continuous
|
|
```
|
|
|
|
This reads karma.conf.js, and opens a Chrome browser and begins running all the test
|
|
in `test/` it will detect changes to the tests in that directory and automatically
|
|
run again, however it will automatically rebuild and reload CanvasKit. Closing the
|
|
chrome window will just cause it to re-opened. Kill the karma process to stop continuous
|
|
monitoring for changes.
|
|
|
|
The tests are run with whichever build of CanvasKit you last made. be sure to also
|
|
test with `release`, `debug_cpu`, and `release_cpu`. testing with release builds will
|
|
expose problems in closure compilation and usually forgotten externs.
|
|
|
|
## Coverage
|
|
|
|
Coverage will be automatically computed when running test-continuous locally. Note that
|
|
the results will only be useful when testing a debug build. Open
|
|
`coverage/<browser version>/index.html` For a summary and detailed line-by-line result.
|
|
|
|
## Measuring Performance
|
|
|
|
We use puppeteer to run a Chrome browser to gather performance data in a consistent way.
|
|
See `//tools/perf-canvaskit-puppeteer` for more.
|
|
|
|
## Adding tests
|
|
|
|
The tests in `tests/` are grouped into files by topic.
|
|
Within each file there are `describe` blocks further organizing the tests, and within those
|
|
`it()` functions which test particular behaviors. `describe` and `it` are jasmine methods
|
|
which can both be temporarily renamed `fdescribe` and `fit`. Which causes jasmine to only those.
|
|
|
|
We have also defined `gm` which is a method for defining a test which draws something to a canvas
|
|
that is shapshotted and reported to gold.skia.org, where you can compare it with the snapshot at
|
|
head.
|
|
|
|
## Testing from Gerrit
|
|
|
|
When submitting a CL in gerrit, click "choose tryjobs" and type CanvasKit to filter them.
|
|
select all of them, which at the time of this writing is four jobs, for each combination
|
|
of perf/test gpu/cpu.
|
|
|
|
The performance results are reported to [perf.skia.org] and correctness results are reported to
|
|
[gold.skia.org].
|
|
|
|
Coverage is not measured while running tests this way.
|
|
|
|
# Inspecting output WASM
|
|
|
|
The `wasm2wat` tool from [the WebAssembly Binary Toolkit](https://github.com/WebAssembly/wabt)
|
|
can be used to produce a human-readable text version of a `.wasm` file.
|
|
|
|
The output of `wasm2wat --version` should be `1.0.13 (1.0.17)`. This version has been checked to
|
|
work with the tools in `wasm_tools/SIMD/`. These tools programmatically inspect the `.wasm` output
|
|
of a CanvasKit build to detect the presence of [wasm SIMD](https://github.com/WebAssembly/simd)
|
|
operations.
|
|
|
|
# Infrastructure Playbook
|
|
|
|
When dealing with CanvasKit (or PathKit) on our bots, we use Docker. Check out
|
|
$SKIA_ROOT/infra/wasm-common/docker/README.md for more on building/editing the
|
|
images used for building and testing.
|
|
|
|
## Updating the version of Emscripten we build/test with
|
|
|
|
This presumes you have updated emscripten locally to a newer version of the
|
|
sdk and verified/fixed any build issues that have arisen.
|
|
|
|
1. Edit `//bin/activate-emsdk` to install and activate the desired version of Emscripten.
|
|
2. Upload a CL with all the changes. Run all Test.+CanvasKit, Perf.+Puppeteer,
|
|
Test.+PathKit, Perf.+PathKit jobs to make sure the new builds pass all
|
|
tests and don't crash the perf harnesses.
|
|
3. Send out CL for review. Feel free to point the reviewer at these steps.
|
|
|
|
## Running Skia's GMs and Unit Tests against wasm+WebGL ##
|
|
TODO(kjlubick)
|
|
|
|
General Tips:
|
|
- Make use of the skip lists and start indexes in the run-wasm-gm-tests.html to focus in on
|
|
problematic tests.
|
|
- `Uncaught (in promise) RuntimeError: function signature mismatch` tends to mean null was
|
|
dereferenced somewhere. Add SkASSERT to verify. |