Caspian

[TOC]

What is it?

Caspian is the name for the WebAssembly portion of the SuperSize Tiger Viewer. It also contains a Linux command-line test binary.

Building the WASM Module

Install Emscripten

This step needs to be only once. Docs: https://emscripten.org/docs/getting_started/downloads.html

cd /usr/local/google/code
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install 4.0.9
./emsdk activate 4.0.9
source emsdk_env.sh

Build

# Omit is_official_build=true if developing locally.
gn gen out/caspian --args='enable_caspian=true is_official_build=true treat_warnings_as_errors=false fatal_linker_warnings=false emscripten_path="/usr/local/google/code/emsdk/upstream/emscripten"'
# Build and copy into static/ directory:
( cd out/caspian; autoninja caspian_web && cp wasm/caspian_web.* ../../tools/binary_size/libsupersize/viewer/static/ )

Building the Linux Test App & Unit Tests

There is a test and a binary that you can run to help with development (and allows debugging outside of the browser).

OUT=$out/linux_debug
autoninja -C $OUT caspian_cli caspian_unittests
$OUT/caspian_cli --help
$OUT/caspian_unittests
# To debug a crash:
lldb $OUT/caspian_cli validatediff supersize_diff.sizediff

Debugging WASM

Based on this article: https://developer.chrome.com/blog/wasm-debugging-2020/

The one-time setup steps are:

• On the same machine as your source code:
  • Install Chrome Canary (sudo apt-get install google-chrome-unstable)
  • Open Chrome Canary
• Install the Chrome extension: https://goo.gle/wasm-debugging-extension
• Enable DWARF debugging in DevTools' experiments panel
  • Gears button in top right, then "experiments" on left nav, then filter for "dwarf".

The every-time steps are:

• Start server: tools/binary_size/libsupersize/viewer/upload_html_viewer.py --local
• Open viewer.html and load a file.
• Open DevTools to the "Sources" panel.
• Look for tree-worker-wasm.js > file://
• Find the .cc files within it and set breakpoints.

Updating Emscripten Version

1. Run:
   Copy

   cd $PATH_TO_EMSDK
   git pull origin main --tags
   ./emsdk install latest
   ./emsdk activate latest
   source ./emsdk_env.sh
   

2. Update this README's Emscripten version above, then follow its steps.

Code Overview

Caspian is a port of the Python implementation, and tries as much as possible to follow the same patterns and names as the Python. Keeping them as similar as possible makes it easier to keep them in sync.

Code Style

Follow Chrome's C++ styleguide where possible. One notable exception is that Caspian does not use //base due to the current lack of WASM support in it.