Build and run from source

how-to

This page builds and runs the three hosts from a checkout: the desktop app, the web app and the Android app. Parsers and viewers are not source in this repository. They live in the sibling repositories poka-parsers and poka-viewers, and reach the hosts as built .wasm files, so each section says how to get them in.

Keep poka-interfaces, poka-parsers, poka-viewers and poka-samples checked out side by side under one parent directory. The tooling finds the others through scripts/_poka_paths.py. python3 scripts/dev-setup.py --check (or just setup --check) reports what is missing on your machine and changes nothing.

Before you start

• Rust, with the wasm target: rustup target add wasm32-wasip1.
• Node.js and npm, for the desktop shell and the web tests.
• Python 3, for the install and test scripts.
• Windows: Visual Studio Build Tools with the Desktop development with C++ workload (for link.exe), and WebView2, which is already present on Windows 10 21H2 and later and on Windows 11.
• Linux: dbus. For the Space-key flow under GNOME and Nautilus you also need python3-nautilus.

Do not export CARGO_TARGET_DIR. Each sibling repository pins one shared target directory in its own .cargo/config.toml, and the variable overrides that pin. A per-crate loop then gives every one of the roughly 1,400 parser crates its own copy of the full dependency graph, which has filled a large disk. Run cargo from inside the repository you are building, not with --manifest-path from outside.

Build the parsers and viewers

cd ../poka-parsers && cargo build --release --target wasm32-wasip1
cd ../poka-viewers && cargo build --release --target wasm32-wasip1

To build one parser only, cd into its crate directory and run cargo build --target wasm32-wasip1 --release.

Desktop app

1. Install the dependencies, once:

   cd desktop
   npm install
   

2. Start the app with hot reload:

   npm run dev
   

   just dev does the same from the repository root.

3. Install the parsers and viewers you built into the extensions directory (~/.poka/extensions/ on Linux and macOS, %APPDATA%\Poka\extensions\ on Windows):

   cd ..
   python3 scripts/install-extensions.py
   

   It installs by symlink, so after you rebuild a module the host picks the change up on the next preview. Without this step a fresh checkout shows no previews.

4. To make a release bundle, run npm run build in desktop/. It runs tauri build and copies the result to build/ (.deb, .msi, poka-setup.exe or .dmg, depending on the platform).

The backend alone builds with cd desktop/src-tauri && cargo build, and cargo test --lib runs the host unit tests.

The Space key under Nautilus

npm run dev builds only the desktop shell. The packaged .deb installs the Nautilus extension for you; a development build needs one manual step per machine:

sudo apt install python3-nautilus
mkdir -p ~/.local/share/nautilus-python/extensions
cp desktop/packaging/space-preview.py ~/.local/share/nautilus-python/extensions/
nautilus -q   # restart Nautilus so it picks up the extension

Other desktops (XFCE, KDE and others) have no Space-key trigger yet. Open with and poka <file> work everywhere.

Web app

The web app runs the same engine in the browser. It needs the route table and the built modules from the pinned sibling releases, not from your working tree:

python3 scripts/fetch-extensions.py   # installs the pinned releases into web/extensions (git-ignored)
python3 scripts/gen_formats_json.py   # regenerates the route table (refuses without the step above)
cd web && cargo run                   # serves http://127.0.0.1:21220

Re-run fetch-extensions.py after each bump of web/extension-releases.json. To try modules you have just built, use python3 scripts/install-web-extensions.py instead, which copies your built .wasm files into web/extensions/.

Open http://127.0.0.1:21220 and drop a file. Append ?server=1 to the address to send the file to the Rust server (POST /api/preview) instead of running it in the browser, which is how the two engines are compared side by side. To serve a corpus from outside the repository, set POKA_WEB_EXAMPLES; see Environment variables and file locations and poka-web HTTP API.

The deployed site is a static Cloudflare Worker with no server compute, so ?server=1 and ?src= work only against this local server.

node web/build-dist.mjs builds the static bundle in web/dist that the deployment publishes.

Android app

The Android build uses the same Tauri app in desktop/src-tauri. It builds and packages an APK, but it has not been launched on a device or an emulator, so treat it as unverified at run time. iOS is blocked: the engine embeds Wasmtime, a JIT compiler, and iOS forbids JIT.

You need JDK 17, the Android SDK (command-line tools, platform-tools, build-tools 34, platform 34), the Android NDK 27.x and cargo-ndk.

# 1. Rust targets and the NDK helper
rustup target add aarch64-linux-android armv7-linux-androideabi \
  i686-linux-android x86_64-linux-android
cargo install cargo-ndk

# 2. Point the build at your SDK and NDK
export ANDROID_HOME="$HOME/Android/Sdk"
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/27.2.12479018"
sdkmanager "platform-tools" "platforms;android-34" "build-tools;34.0.0" "ndk;27.2.12479018"

# 3. Initialise and build
cd desktop/src-tauri
npx tauri android init
npx tauri android build --target aarch64 --debug   # drop --debug for a release build

The APK is written under desktop/src-tauri/gen/android/app/build/outputs/apk/universal/debug/. If the build stops with a version mismatch between @tauri-apps/api and the tauri crate, run npm update @tauri-apps/api in desktop/.

Check your setup

python3 scripts/poka-doctor.py   # diagnoses a stale or broken local install (just doctor)