1f8c31b101
These rules can be used to build our GMs on WASM+WebGL and libskia.a with just the CPU backend (and most other features turned off). This can be done with the following commands: - bazel build //modules/canvaskit:gm-bindings-wasm --gpu_backend=gl_backend --with_gl_standard=webgl_standard - bazel build :skia-core --config clang This pivots slightly from http://review.skia.org/463517 by using config_settings [1] instead of platforms for the optional features that we control. This pivot was suggested in [2] We have BUILD.bazel files in many of the subdirectories that specify filegroups for the appropriate files. In an effort to make //BUILD.bazel more readable, it is the responsibility of these subfolders to deal with conditionally including certain .h or .cpp files. This is done using select statements and config_settings or platform constraints as necessary. For example, src/gpu/BUILD.bazel will different private filegroups for each of the supported gpu backends [3] and a more-visible filegroup called "srcs" that has the right selection of the private files to be used for compilation. An effort has been made to avoid using glob() in our BUILD.bazel files. These file lists were made by using `ls -1` and some regex to add in quotes. We might want to make a helper script to assist with that, if necessary. To specify which options we have, the settings in //bazel/common_config_settings/BUILD.bazel have been redesigned. They make use of a macro `string_flag_with_values` that removes the boilerplate. Patchset 36 shows what the file looks like w/o the macro. The top level BUILD.bazel file will still need to use some logic to handle defines, because local_defines is a list of strings, not a list of labels [4]. Suggested Review Order: - WORKSPACE.bazel to see the new dependencies on the emsdk toolchain and bazel_skylib - bazel/common_config_settings/* to see the few settings defined (we have more to define, see BUILD.gn and //gn/skia.gni for ideas) - BUILD.bazel to see the "skia-core" cc_library rule. See also "gms" and "tests" - modules/canvaskit/BUILD.bazel to see the use of the emscripten "wasm_cc_binary" rule, which depends on the "skia-core", "gms", and "tests" rule. Note that it only builds some of the gms as a proof of concept. - The other BUILD.bazel files. Some of these are not platform or feature dependent (e.g. pathops). Others are (e.g. gpu). - All other files. [1] https://docs.bazel.build/versions/4.2.1/skylark/config.html#user-defined-build-settings [2] https://github.com/emscripten-core/emsdk/pull/920 [3] In this CL, that's just the webgl one. [4] https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.local_defines Change-Id: Ieecf9c106d5e3a6ae97d13d66be06b4b3c207089 Reviewed-on: https://skia-review.googlesource.com/c/skia/+/458637 Reviewed-by: Ben Wagner <bungeman@google.com> Reviewed-by: Leandro Lovisolo <lovisolo@google.com> Owners-Override: Kevin Lubick <kjlubick@google.com> |
||
|---|---|---|
| .. | ||
| external_test | ||
| fonts | ||
| future_apis | ||
| htmlcanvas | ||
| npm_build | ||
| tests | ||
| wasm_tools | ||
| .gitignore | ||
| BUILD.bazel | ||
| BUILD.gn | ||
| canvaskit_bindings.cpp | ||
| catchExceptionNop.js | ||
| CHANGELOG.md | ||
| color.js | ||
| compile_gm.sh | ||
| compile.sh | ||
| cpu.js | ||
| debug.js | ||
| externs.js | ||
| font.js | ||
| gm_bindings.cpp | ||
| gm.js | ||
| gpu.js | ||
| interface.js | ||
| karma.conf.js | ||
| karma.google3.conf.js | ||
| Makefile | ||
| matrix.js | ||
| memory.js | ||
| package-lock.json | ||
| package.json | ||
| paragraph_bindings_gen.cpp | ||
| paragraph_bindings.cpp | ||
| paragraph.js | ||
| particles_bindings.cpp | ||
| particles.js | ||
| pathops.js | ||
| postamble.js | ||
| preamble.js | ||
| README.md | ||
| release.js | ||
| rt_shader.js | ||
| skottie_bindings.cpp | ||
| skottie.js | ||
| skp.js | ||
| util.js | ||
| viewer_bindings.cpp | ||
| WasmCommon.h | ||
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.
To compile CanvasKit, you will first need to install emscripten. This
will set the environment EMSDK (among others) which is required for
compilation. Which version should you use? /infra/wasm-common/docker/emsdk-base/Dockerfile
shows the version we build and test with. We try to use as recent a version of emscripten as
is reasonable.
Be sure to both install and activate the correct version. For example:
./emsdk install 2.0.20
./emsdk activate 2.0.20
This document also assumes you have followed the instructions to download Skia and its deps https://skia.org/user/download.
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 gold 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
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
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.
- Edit
$SKIA_ROOT/infra/wasm-common/docker/emsdk-base/Dockerfileto install and activate the desired version of Emscripten. - Edit
$SKIA_ROOT/infra/wasm-common/docker/Makefileto haveEMSDK_VERSIONbe set to that desired version. If there is a suffix that is not_v1, reset it to be_v1. If testing the image later does not work and edits are made to the emsdk-base Dockerfile to correct that, increment to_v2,_v3, etc to force the bots to pick up the new image. - In
$SKIA_ROOT/infra/wasm-common/docker/, runmake publish_emsdk_base - Edit
$SKIA_ROOT/infra/canvaskit/docker/canvaskit-emsdk/Dockerfileto be based off the new version from step 2. CanvasKit has its own docker image because it needs a few extra dependencies to build with font support. - Edit
$SKIA_ROOT/infra/canvaskit/docker/Makefileto have the same version from step 2. It's easiest to keep theemsdk-baseandcanvaskit-emsdkversions be in lock-step. - In
$SKIA_ROOT/infra/canvaskit/docker/, runmake publish_canvaskit_emsdk. - In
$SKIA_ROOT/infra/bots/recipe_modules/build/, updatecanvaskit.pyandpathkit.pyto haveDOCKER_IMAGEpoint to the desired tagged Docker containers from steps 2 and 5 (which should be the same). - In
$SKIA_ROOT/infra/bots/task_drivers/compile_wasm_gm_tests.go, update dockerImage to refer to the desired Docker containers from steps 2 and 5. - In
$SKIA_ROOT/infra/bots/, runmake trainto re-train the recipes. - Optional: Run something like
git grep 1\\.38\\.in$SKIA_ROOTto see if there are any other references that need updating. - 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.
- Send out CL for review. Feel free to point the reviewer at these steps.