Environment setup
Install the platform tools required to build Byte Engine applications.
Select your operating system to see every tool and configuration step required to build Byte Engine. Your choice is remembered anywhere these operating system tabs appear in the documentation.
macOS
Set up Apple's SDK and native build tools before you build Byte Engine on macOS.
Minimum macOS version
Byte Engine requires macOS 26 or later.
Install Rust
Install Rust with rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shThe repository pins its nightly toolchain in rust-toolchain.toml, so Cargo
downloads and uses the correct version when you build inside the checkout.
Install Xcode
Install the full Xcode app before building Byte Engine on macOS. Xcode includes the macOS SDK and command-line compiler tools used by the engine.
Why full Xcode is required
Byte Engine's shader build invokes the metal and metallib tools. Apple
offers these tools only through the Metal Toolchain component for the full
Xcode installation, so the standalone Command Line Tools can't build Byte
Engine's Metal shader resources. Other build steps use Xcode's SDK and
command-line tools to compile and link the engine and its applications. The
Xcode user interface isn't part of the build; use it only for tasks such as
GPU capture and debugging.
Select the installed Xcode app and accept its license:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license acceptDownload the Metal compiler component for the selected Xcode installation:
xcodebuild -downloadComponent MetalToolchainVerify that the Metal compiler is available:
xcrun -sdk macosx metal --versionInstall Homebrew packages
Install the native build tools used by Byte Engine's Rust dependencies.
brew install cmake pkg-configLinux
Install the native packages and configure AVX2 before you build Byte Engine on Linux.
Install Rust
Install Rust with rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shThe repository pins its nightly toolchain in rust-toolchain.toml, so Cargo
downloads and uses the correct version when you build inside the checkout.
Install system packages
Install the native build, windowing, audio, and Vulkan packages used by Byte Engine's Linux backend.
sudo apt install -y cmake libwayland-dev libasound2-dev libx11-xcb-dev libxkbcommon-dev libvulkan-dev vulkan-tools vulkan-validationlayersEnable AVX2 on x64
On x64 Linux, enable AVX2 explicitly instead of using target-cpu=native. Add
this configuration to your application's .cargo/config.toml:
[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "target-feature=+avx2"]Optional: Install Mold
Mold is an optional linker that can reduce build times on Linux. Follow the installation steps in the Mold repository.
Optional: Install RenderDoc
Install RenderDoc when you need to capture and inspect rendered frames.
sudo apt install renderdocWindows
Install the Windows development tools and configure AVX2 before you build Byte Engine on Windows.
Install Rust
Download and run the Windows installer from rustup.rs,
then accept the default installation options. The repository pins its nightly
toolchain in rust-toolchain.toml, so Cargo downloads and uses the correct
version when you build inside the checkout.
Install Visual Studio Build Tools
Install the Visual Studio Build Tools with the MSVC C++ toolchain and Windows SDK before building on Windows. Byte Engine's Windows backends use Win32, Direct3D 12, DXGI, and DXC APIs from the Windows SDK.
Enable AVX2 on x64
On x64 Windows, enable AVX2 explicitly instead of using target-cpu=native.
Add this configuration to your application's .cargo/config.toml:
[target.x86_64-pc-windows-msvc]
rustflags = ["-C", "target-feature=+avx2"]