Requirements
- Rust (stable), installed with rustup. The project is developed on
x86_64-pc-windows-gnu; the MSVC toolchain works too. - Git, to clone the repository.
- A GPU supported by
wgpu(Direct3D 12, Vulkan or Metal) for the window. The headless screenshot mode also renders throughwgpu. - System fonts. Project AB discovers installed fonts on Windows, Linux and macOS. It reads TrueType outlines; CFF-only fonts are skipped.
Build and run
-
Clone the repository
git clone https://github.com/SyncWide-Solutions/project-ab project-ab cd project-ab -
Build in release mode
Release builds are much faster than debug builds; layout and image decoding benefit a lot from optimisation.
cargo build --release -
Open a page
cargo run --release -p ab-app -- https://example.com/Leave out the URL to start on the homepage (
about:homeunless changed insettings.ini). The binary is written totarget/release/ab-app(ab-app.exeon Windows), or belowCARGO_TARGET_DIRif you set it. -
Or take a screenshot without a window
cargo run --release -p ab-app -- https://example.com/ --screenshot example.pngSee headless mode for all options.
Windows notes
GNU toolchain needs MinGW-w64 binutils
With the x86_64-pc-windows-gnu toolchain, dlltool.exe and as.exe from MinGW-w64 must be on PATH, because windows-sys uses raw-dylib imports. One way to install them:
winget install --id BrechtSanders.WinLibs.POSIX.MSVCRT -e --scope user
Then add the mingw64\bin directory of that installation to PATH and open a new terminal. Alternatively, use the MSVC toolchain together with the Visual Studio Build Tools.
Building from a network share
If the repository lives on a network drive (SMB), Windows may refuse to run Cargo's build-script binaries from there and fail with Access is denied (os error 5)
. Point Cargo at a local target directory instead. In PowerShell:
$env:CARGO_TARGET_DIR = "$env:LOCALAPPDATA\project-ab-target"
cargo build --release
The built binary is then at %LOCALAPPDATA%\project-ab-target\release\ab-app.exe.
Release builds use the Windows GUI subsystem, so double-clicking ab-app.exe does not open a console. Started from a terminal, it still prints messages there.
Linux and macOS
The primary development platform is Windows; other platforms are not verified regularly. Font discovery covers Linux and macOS paths and winit and wgpu are cross-platform, but some conveniences such as the clipboard integration are Windows-only for now.
On Linux, native-tls uses OpenSSL, so its development headers and pkg-config are needed. On Debian or Ubuntu:
sudo apt install pkg-config libssl-dev
Run the checks
These are the checks every milestone has to pass:
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test --workspace
cargo build --release
A live network test that fetches example.com is ignored by default:
cargo test -p ab-net -- --ignored
Troubleshooting
dlltool.exenot found (Windows, GNU toolchain)- Install MinGW-w64 binutils and put them on
PATH, as described in Windows notes. - Access is denied (os error 5) during the build
- Set
CARGO_TARGET_DIRto a local directory, see Building from a network share. - A page loads slowly or looks wrong
- Run with
AB_TRACE=1to log every fetch and uncaught script errors, see diagnostics. Check the roadmap for known limitations.