1# Dependencies
2
3## Rust
4
5This project requires the latest stable version of the [Rust toolchain](https://doc.rust-lang.org/book/ch01-01-installation.html) to build.
6
7## SDL3
8
9This project uses [SDL3](https://www.libsdl.org/) for windowing, audio playback, and reading keyboard/gamepad/mouse inputs.
10
11By default, SDL3 is fetched and built from source while building this project, and it is dynamically linked at runtime.
12This behavior is customizable using [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html):
13
14| Feature                  | Description                      | Default |
15|--------------------------|----------------------------------|---------|
16| `sdl3-build-from-source` | Fetch and build SDL3 from source | Yes     |
17| `sdl3-static-link`       | Statically link SDL3             | No      |
18
19Building SDL3 from source requires a C build toolchain. See also:
20* [SDL3 Linux README](https://github.com/libsdl-org/SDL/blob/main/docs/README-linux.md)
21* [SDL3 Windows README](https://github.com/libsdl-org/SDL/blob/main/docs/README-windows.md)
22
23Example command to disable building SDL3 from source:
24
25```shell
26cargo build --no-default-features
27```
28
29Example command to build while statically linking SDL3:
30
31```shell
32cargo build --features sdl3-static-link
33```
34
35If SDL3 is not statically linked, it must be available in the dynamic library path at runtime. `cargo run` handles
36this automatically when the `sdl3-build-from-source` feature is enabled.
37
38If `sdl3-build-from-source` is disabled, SDL3 headers and libraries must be available at build time, e.g. by installing
39the `libsdl3-dev` package on Linux. If they are not in the system library path then you may need to use `RUSTFLAGS` to
40pass `-I` and `-L` arguments to the linker.
41
42## DirectX Shader Compiler (Windows DX12 backend only)
43
44The DirectX 12 wgpu backend is currently configured in such a way that it requires DLLs for Microsoft's DirectX shader compiler. The latest release is available here: <https://github.com/microsoft/DirectXShaderCompiler/releases>
45
46`dxcompiler.dll` must be present in the current working directory for the DirectX 12 backend to work.
47
48# Build & Run
49
50Build and run:
51
52```shell
53cargo run --release
54```
55
56For local development, the `dev-fast` profile has a lower optimization level and should have faster incremental compile times (at the cost of worse runtime performance):
57
58```shell
59cargo run --profile dev-fast
60```
61
62For one-time builds, the `release-lto` profile enables fat LTOs and a few other build settings that improve runtime performance and decrease binary size at the cost of much longer compile times:
63
64```shell
65cargo build --profile release-lto
66```
67
68...After which the binaries will be in `target/release-lto/`.
69
70If you are building for usage solely on your own machine, you can additionally set the compiler flag `-C target-cpu=native` to tell the compiler that it can use any CPU instruction that your computer's CPU supports, which may slightly improve performance:
71
72```shell
73RUSTFLAGS="-C target-cpu=native" cargo build --profile release-lto
74```
75
76`-C target-cpu=native` is not recommended for shared or distributed builds because the binaries may contain instructions that are only supported on recent CPUs, e.g. AVX-512 instructions. For shared/distributed builds it is better to use a specific CPU target such as `-C target-cpu=x86-64-v3` (allows the compiler to use AVX2, FMA, LZCNT, etc).
77
78On Linux, the following command will build AppImage packages (requires a nightly Rust toolchain and [cargo-packager](https://github.com/crabnebula-dev/cargo-packager)):
79
80```shell
81cargo packager --profile release-lto -f appimage
82```