Skip to content

Getting started

Jump to bottom
Diggory Hardy edited this page Dec 14, 2023 · 3 revisions

Dependencies

KAS requires a Rust compiler, version (MSRV) 1.66 or greater. Using the nightly channel does have a few advantages:

  • Procedural macros can only emit warnings using nightly rustc. Thus, it is recommended to use nightly for development.
  • The nightly (min_spec) feature allows some visual improvements (see Feature flags).
  • The doc_cfg feature may be used for API docs.

Linux libraries

You don't need to install anything, unless you want to write GLSL shaders or use HarfBuzz. But, in case you do:

# For Ubuntu:
sudo apt-get install build-essential git libxcb-shape0-dev libxcb-xfixes0-dev libharfbuzz-dev

# For Fedora:
sudo dnf install libxcb-devel harfbuzz-devel glslc

Running examples

Clone the repository and run the examples as follows:

git clone https://github.com/kas-gui/kas.git
cd kas
cargo run --example gallery
cd examples/mandlebrot; cargo run

Buliding documentation locally

RUSTDOCFLAGS="--cfg doc_cfg" cargo +nightly doc --features=nightly --all --no-deps --open

Faster builds

People variously complain that Rust / KAS is slow to compile, and they have a point: just recompiling the gallery example takes over six seconds on a 5800X!

There are two strategies we can use to speed this up:

  1. Dynamic linking. I wouldn't recommend shipping code with dynamic linking due to dependency complications (although it is possible and potentially useful, especially within Linux distributions), but during development it can make a lot of sense.

    Enabling dynamic linking is very easy: use --features dynamic.

  2. A faster linker: LLD or better yet mold.

    Using LLD: (1) install (e.g. via Linux distribution packages), (2) create $HOME/.cargo/config, (3) add this:

    [build]
rustflags = ["-C", "link-arg=-fuse-ld=lld"]

    Using Mold: (1) install (see project page), (2) prefix build commands with mold -run.

Here are some crude benchmarks. Method: build the gallery example, touch (or re-save) gallery.rs, and rebuild. Use the Unix time command, run three times, and report the best real time of the three. Machine: 5800X, Fedora 34, SSD.

configuration time version
standard 0m6.124s rustc 1.54.0 (a178d0322 2021-07-26)
dynamic 0m2.275s
lld 0m1.537s LLD 12.0.1 (lld-12.0.1-1.fc34.src.rpm)
lld + dynamic 0m1.061s
mold 0m1.147s mold 0.9.3 (ec3319b37f653dccfa4d1a859a5c687565ab722d)
mold + dynamic 0m0.971s
Clone this wiki locally