Developer Guide

This guide covers the development environment, common commands, documentation, CI/CD pipelines, and troubleshooting notes for Tramex.

Development Setup

Install rustup, the recommended installer for the Rust compiler (rustc) and the Cargo package manager.

Add the WebAssembly target:

rustup target add wasm32-unknown-unknown

Install cargo-hack and trunk. Trunk builds, bundles, and optimizes the WebAssembly application.

cargo install cargo-hack
cargo install trunk

Clone the repository:

git clone git@github.com:tramex/tramex.git

Development Commands

Run the web application:

trunk serve

Run the desktop application:

cargo run

Check the code with Clippy:

cargo clippy

Run the application with the debug features enabled in tramex and tramex-tools:

cargo run --features debug

Enable backtraces and more detailed logs:

RUST_BACKTRACE=1 RUST_LOG=debug cargo run --features debug

Documentation

The project uses mdBook to generate HTML documentation from Markdown files.

Install mdBook:

cargo install mdbook

Start the documentation development server from the repository root:

mdbook serve docs/

The latest generated crate documentation is available at:

• tramex: https://tramex.github.io/tramex/crates/tramex/
• tramex-tools: https://tramex.github.io/tramex/crates/tramex_tools

CI/CD

Continuous Integration and Continuous Delivery automate tests and deployment throughout the application lifecycle. Tramex uses GitHub Actions for deployment and testing. The principal workflows are:

• deploy.yml
• tests.yml
• wasm.yml

Each YAML workflow defines its execution context and a sequence of named actions or commands.

Deployment

The deployment workflow runs for pushes to the main branch and can also be started manually from the Actions tab. It configures GitHub Pages, Cargo caching, and mdBook before building coverage, the application, and the documentation.

The web application is built with Trunk in release mode. The --public-url option accounts for the application being hosted below the /tramex/ path, and all generated files are collected in dist.

Coverage is generated and moved into dist. mdBook transforms the Markdown files under docs according to docs/book.toml, and its output is also placed in dist. The entire directory is then deployed to GitHub Pages.

Deployment outputs are available at:

• https://tramex.github.io/tramex/ — browser application
• https://tramex.github.io/tramex/docs/ — project documentation
• https://tramex.github.io/tramex/coverage/ — code coverage
• https://tramex.github.io/tramex/crates/tramex/ — tramex crate documentation
• https://tramex.github.io/tramex/crates/tramex_tools/ — tramex-tools crate documentation

Tests

The tests workflow runs for pushes and pull requests targeting the main branch. It configures the Cargo cache, builds the workspace, and runs its test suite with verbose output to make failures easier to diagnose.

WebAssembly

The WASM workflow runs for pushes and pull requests targeting the main branch. In addition to the native workspace checks, it verifies that the Rust WebAssembly target builds successfully with Trunk.

Spelling

typos.yml checks documentation spelling for pushes and pull requests targeting the main branch. False positives can be added to typos.toml at the repository root.

Troubleshooting and Knowledge Base

Browser Copy and Paste

Older versions of eframe required --cfg=web_sys_unstable_apis to enable browser clipboard access. This was fixed in eframe 0.29: https://github.com/emilk/egui/pull/4980#pullrequestreview-2260129833.

Related resources:

• https://docs.rs/web-sys/0.3.69/web_sys/struct.Clipboard.html
• https://rustwasm.github.io/docs/wasm-bindgen/web-sys/unstable-apis.html
• https://github.com/emilk/eframe_template/blob/main/.cargo/config.toml#L6

Coverage

Code coverage generated by cargo-llvm-cov is available at https://tramex.github.io/tramex/coverage/.

Secure WebSocket Connections

When the website runs over HTTPS, browsers block connections to insecure endpoints such as ws://. Possible solutions include:

• Add an SSL certificate to the WebSocket server.
• Use a WebSocket proxy to translate ws connections to wss.
• Use a local WebSocket proxy so the application connects through a local address.
• Disable the browser restriction during local development.

Example local proxy with an origin header:

npx @n4n5/proxy-ws -t ws://10.0.0.1:9001 -h '{"origin":"toto"}'
# Redirects ws://127.0.0.1:9001 to ws://10.0.0.1:9001

Limiting Compilation Resources

Cargo can use all available CPU cores during compilation. Limit the number of parallel jobs from the command line:

cargo build --jobs 10
# or
cargo build -j 10

To make the limit persistent, add the following to ~/.cargo/config.toml:

[build]
jobs = 10

On Linux, nproc reports the number of available CPUs.

Changing the File List from a URL

Use the files_url query parameter to provide a different file list:

https://tramex.github.io/tramex/?files_url=https://example.com/