Skip to content

Getting started

Jump to bottom
Diggory Hardy edited this page Jun 3, 2022 · 3 revisions

Dependencies

KAS requires a Rust compiler, version (MSRV) 1.58 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

Install dependencies (glslc and harfbuzz are optional):

# 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

(Note: this advice may be outdated.)

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