Build and test¶
Use CMake 3.15 or newer and a C++20 compiler for native builds. Use Emscripten for the browser application.
Native build¶
Build the CLI and run the tests from the repository root:
git submodule update --init --recursive
cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON
cmake --build build/debug -j
ctest --test-dir build/debug --output-on-failure
The executable is build/debug/facs. CMake enables FACS_BUILD_CLI for native
builds and FACS_BUILD_WEB for Emscripten builds. To build only the library:
cmake -S . -B build/lib -DFACS_BUILD_CLI=OFF -DFACS_BUILD_WEB=OFF \
-DBUILD_TESTING=OFF
cmake --build build/lib
Debug and RelWithDebInfo builds enable AddressSanitizer when supported. Unoptimized Debug integration has extra cost from instrumented stage copies. The Debug parallel regression has a six-minute timeout with AddressSanitizer; other configurations use two minutes.
Native binary output requires the NetCDF C library with NetCDF-4 support. See output formats for detection and options, and the library guide for CMake consumers.
Browser build¶
Activate Emscripten 5.0.7 or newer, then run ./build_web.sh. The browser
target uses -pthread for the shared C++ radial scheduler. See Emscripten's
pthreads documentation.
Serve the files in build/pages/ with COOP and COEP headers to
enable shared memory. The page preloads a bounded pthread pool and reuses it
across calculations.
The first web build downloads pinned zlib 1.3.1, HDF5 1.14.6, and NetCDF-C
4.9.3 sources and compiles a separate serial file exporter. Later builds reuse
them. The page loads that exporter in a worker only when a NetCDF or HDF5
download is requested. The calculation runtime does not link those libraries.
For an existing serial Emscripten build, FACS_WASM_IO_ROOT can point to a
prefix containing include/, lib/, and licenses/. The last directory must
contain the five notices listed in web/cmake/scientific_io.cmake.
The webui/ submodule supplies controls, fonts, styles, and theme handling.
Initialize it with git submodule update --init --recursive. Both web build
directories include its src/ and styles/ trees; no JavaScript package
manager is needed.
The HTML template loads FACS's theme.js and webui's theme_boot.js before
the styles to restore the saved palette and mode. appearance.js binds the
shared theme controls and saves palette choices. ui.js imports the shared
APIs, then loads classic app.js
and the generated solver script in order. FACS keeps the solver, canvases,
workspace layout, and scientific plot rules. Shared controls and page styles
come from webui. The figures window borrows the same DOM nodes and loads the
same styles, including relative imports, before drawing.
After configuration, cmake --build build/web builds the browser target and,
when BUILD_TESTING=ON, the tests. Run the tests with
ctest --test-dir build/web --output-on-failure; Emscripten runs them in Node.js.
Web main and pthread stacks use 1 MiB for coupled root searches.
Worker pool¶
The browser uses the radial scheduler through
Emscripten pthreads. Its default
pool has at most eight threads, limited by the browser's reported hardware
concurrency. --threads cannot exceed that pool; change the build limit with
-DFACS_WASM_MAX_THREADS=N. The pool includes the coordinator, which also
calculates surfaces. Each thread has a 1 MiB stack. The UI polls progress and
completion without waiting for a worker. Hosting still requires COOP and COEP
headers for shared Wasm memory.
Bundled equilibria¶
For local builds, place the g-files in web/equilibria/ and edit
web/equilibria/index.json:
[
{"name": "My display name", "file": "actual-filename.g"}
]
name sets the label on the page; file is the actual filename in that
directory, without a path. Each file loads when selected. Uploads remain
available, and exports record the actual filename. Rebuild with
./build_web.sh to include catalog changes and added or removed files.
The supplied circular equilibrium is synthetic, generated from the analytic
fixture in test/gfile-fixture.mjs. See the
equilibrium picker and its
mobile view.
Documentation build¶
Install the pinned tools and build the public documentation:
python3 -m pip install -r requirements-docs.txt
python3 script/build_docs.py
The builder stages the Markdown sources in build/docs-src/ and writes
the site to build/pages/docs/. It checks the site with MkDocs strict
mode and removes links to private source files from the public pages.
See deployment to publish the app with its documentation.
Browser validation¶
The numerical guide lists native
regressions. The WebGPU guide lists shader,
worker, and rendering checks. Browser smoke checks use the forwarded
Chrome DevTools endpoint at http://localhost:9333.
The visual integration check covers desktop and mobile controls, five color palettes, light and dark modes, saved preferences, denied storage, failed startup dependencies, licenses, and documentation search. Build the app and docs first, then run:
node test/web-ui-smoke.mjs APP_URL APP_DIR OUTPUT_DIR [CHROME_URL]
Use the explicit index.html URL for APP_URL. The shared library also has
Node and browser suites; see webui's guide.
The foldable layout check covers continuous screen widths, both hinge orientations, touch scrolling, focus, compact view, and retained GPU results. Run it against the staged app:
node test/web-fold-layout-smoke.mjs APP_URL APP_DIR OUTPUT_DIR [CHROME_URL]
The multiple-window check runs a WebGPU calculation in a separate figures window. It checks mixed display scaling, keyboard controls, zoom, Floquet completion with the solver window minimized, compact and fold scroll restoration, and window closure and reload. It tests the permission explanation, retry and dismissal, and negative monitor coordinates. It uses real monitor placement when the connected browser reports multiple screens. It restores the test origin's screen permission after that check. Display scaling uses Chrome emulation; the same-size density check dispatches a resolution change event because DevTools may change the density without sending that event.
node test/web-window-layout-smoke.mjs APP_URL APP_DIR OUTPUT_DIR [CHROME_URL]