Flags for the fuzzer can be passed directly to fossil,
e.g. <tt>-jobs=4</tt> to start four fuzzer jobs in parallel, but doing
so may cause the fuzzer to <em>strip the --fuzztype flag</em>, leading
to it testing the wrong thing. When passing on fuzzer-specific flags
along with <tt>--fuzztype</tt>, be sure to check your system's process
list to ensure that your <tt>--fuzztype</tt> flag is there.


<a id='wasm'></a>
<h2>Building WebAssembly Components</h2>

As of version 2.19, fossil uses one component built as
[https://developer.mozilla.org/en-US/docs/WebAssembly | WebAssembly]
a.k.a. WASM. Because compiling WASM code requires non-trivial
client-side tooling, the repository includes compiled copies of these
pieces. Most Fossil hackers should never need to concern themselves
with the WASM parts, but this section describes how to for those who
want or need to do so.

<strong>The bits described in this section are necessary when updating
<tt>extsrc/pikchr.c</tt></strong> from the upstream source, or the
fossil binary will use a different version of pikchr than
[/pikchrshow] does (as the latter runs the WASM build of pikchr).

These instructions have only ever been tested on Linux systems. They
"should" work on any Unix-like system supported by Emscripten. The
fossil makefiles for Windows builds <em>do not</em> include any of the
WASM-related components (patches to add that would be welcomed, of
course).

The first step is to configure the tree with support for
[https://emscripten.org/|Emscripten]. This requires that the system
has the Emscripten SDK (a.k.a. emsdk) installed, as documented at:

[https://emscripten.org/docs/getting_started/downloads.html]

    Sidebar: getting Emscripten up and running is trivial and
    painless, at least on Linux systems, but the installer
    downloads many hundreds of megabytes of tools and dependencies,
    all of which will be installed under the single SDK directory (as
    opposed to being installed at the system level).

After installing the SDK, configure the fossil tree with emsdk
support:

<pre><code>$ ./configure --with-emsdk=/path/to/emsdk ...other options...
</code></pre>

If the <tt>--with-emsdk</tt> flag is not provided, the configure
script will check for the environment variable <tt>EMSDK</tt>, which
is one of the standard variables the SDK environment uses. If that
variable is found, its value will implicitly be used in place of the
missing <tt>--with-emsdk</tt> flag. Thus, if the <tt>emsdk_env.sh</tt>
script is sourced into the shell before running the configure script,
the SDK will be detected even without the config flag.

The configure script installs some makefile variables which tell the
build where to find the SDK and it generates a script named
<tt>tools/emcc.sh</tt> (from the template file
<tt>[/file/tools/emcc.sh.in|/tools/emcc.sh.in]</tt>), which is a
wrapper around the Emscripten C compiler (<tt>emcc</tt>). The wrapper
script uses the configure-time state to attempt to set up the various
environment variables which are required by <tt>emcc</tt> and will
fail if it cannot do so. Once it's set up the environment, it passes
on all of its arguments to <tt>emcc</tt>.

The WASM-related build parts are set up such that none of them should
ever trigger implicity (e.g. via dependencies resolution) in a normal
build cycle. They are instead explicitly built as described below.

From the top of the source tree, all WASM-related components can be
built with:

<pre><code>$ make wasm</code></pre>

As of this writing, those parts include:

   *  <tt>extsrc/pikchr.wasm</tt> is a WASM-compiled form of
      <tt>extsrc/pikchr.c</tt>.
   *  <tt>extsrc/pikchr.js</tt> is JS/WASM glue code generated by Emscripten
      to give JS code access to the API exported by the WASM file.

    Sidebar: The file
    <tt>[/file/extsrc/pikcher-worker.js|extsrc/pikcher-worker.js]</tt>
    is hand-coded and intended to be loaded as a "Worker" in
    JavaScript. That file loads the main module and provides an
    interface via which a main JavaScript thread can communicate with
    pikchr running in a Worker thread. The file
    <tt>[/file/src/fossil.page.pikchrshowasm.js|src/fossil.page.pikchrshowasm.js]</tt>
    implements the [/pikchrshow] app and demonstrates how
    <tt>pikchr-worker.js</tt> is used.

When a new version of <tt>extsrc/pikchr.c</tt> is installed, the
files <tt>pikchr.{js,wasm}</tt> will need to be recompiled to account
for that. Running <tt>make wasm</tt> will, if the build is set up for
the emsdk, recompile those:

<pre><code>$ make wasm
./tools/emcc.sh -o extsrc/pikchr.js ...
$ ls -la extsrc/pikchr.{js,wasm}
-rw-rw-r-- 1 stephan stephan 17263 Jun  8 03:59 extsrc/pikchr.js
-rw-rw-r-- 1 stephan stephan 97578 Jun  8 03:59 extsrc/pikchr.wasm
</code></pre>

Then run the normal build so that those files can be compiled in to
the fossil binary, accessible via the [/help?cmd=/builtin|/builtin page]:

<pre><code>$ make</code></pre>

Before checking in those newly-built files, they need to be tested by
running the [/pikchrshow] page. If that page loads, the compilation
process fundamentally worked (a load failure will be made obvious to
the viewer). If it fails to load then the browser's dev tools console
likely provides at least a small hint (and <em>sometimes</em> a useful
hint) about the nature of the problem. Don't check those files in
until [/pikchrshow] runs, though!

Should pikchr's C interface ever changes, <tt>pikchr-worker.js</tt>
will need to be updated to accommodate it, but such modification is
typically trivial.