WebAssembly Specifications

This directory contains the source code for the WebAssembly spec documents, as served from the webassembly.github.io/spec pages. It uses Sphinx and Bikeshed.

To install Sphinx:

pip install sphinx

To install Bikeshed, see the instructions here.

To build everything locally (result appears in _build/):

make all

To build everything and update webassembly.github.io/spec with it:

make publish

Please make sure to only use that once a change has approval.

Step by step guide to building the spec

Prerequisites

You will need python3.7, and pip. pip should come with Python, if not follow these installation instructions for pip, or check your system package manager for pip3.

Important: you will need the version of pip that works with python3.7.

Use something like pipenv to keep your system installation of Python clean.

pip install pipenv
pipenv --python 3.7
pipenv shell

Install Python dependencies:

pip install Sphinx==2.4.4

Checking out the repository

Make sure this repository was cloned with --recursive:

git clone --recursive https://github.com/WebAssembly/spec

If you have already cloned but without --recursive, you can delete and re-clone, or cd into spec and run:

git submodule update --init --recursive

The rest of these instructions assume you are in the directory where is README is:

cd spec/document

Building the multi-page HTML document

You can now build the multi-page html document:

make -C core html

Building the single-page HTML document

To build the single-page W3C version, there are more dependencies to install. First, get Bikeshed:

# cd back to root of git directory
git clone https://github.com/tabatkins/bikeshed.git
pip install --editable bikeshed
bikeshed update

You will also need npm and yarn for all the LaTeX goodness. npm might already be available on your system, you can also use something like nvm to prevent messing with system packages:

npm install -g yarn
cd document
make -C core bikeshed

Building the PDF

To build the PDF, you will need texlive-full, install it using your system package manager:

apt install texlive-full
make -C core pdf

Building the JavaScript Embedding API

To build the JavaScript Embedding API, you will need bikeshed as describe in the section Building the single-page HTML document:

make -C js-api

Building the Web Embedding API

To build the Web Embedding API, you will need bikeshed as describe in the section Building the single-page HTML document:

make -C web-api