2020-08-13 07:59:03 +00:00
# Installing Linux dependencies
This page lists the required dependencies to build a Bevy project on your Linux machine.
If you don't see your distro present in the list, feel free to add the instructions in this document.
2022-05-30 18:13:36 +00:00
## [Ubuntu](https://ubuntu.com/)
2020-10-21 22:57:03 +00:00
2020-08-23 20:18:46 +00:00
```bash
2023-12-21 23:14:05 +00:00
sudo apt-get install g++ pkg-config libx11-dev libasound2-dev libudev-dev libxkbcommon-x11-0
2020-08-23 20:18:46 +00:00
```
2021-02-22 04:50:05 +00:00
2021-12-09 20:14:00 +00:00
if using Wayland, you will also need to install
```bash
sudo apt-get install libwayland-dev libxkbcommon-dev
```
2021-03-07 19:17:25 +00:00
Depending on your graphics card, you may have to install one of the following:
`vulkan-radeon` , `vulkan-intel` , or `mesa-vulkan-drivers`
2021-04-14 22:02:52 +00:00
Compiling with clang is also possible - replace the `g++` package with `clang` .
2020-12-15 07:10:58 +00:00
2023-09-20 12:10:56 +00:00
## Windows Subsystem for Linux (WSL 2)
2020-10-29 01:51:51 +00:00
2023-09-20 12:10:56 +00:00
Up-to-date WSL Installs for Windows 10 & 11 include WSLg, which provides
necessary servers for passing graphics and audio between Windows and the WSL instance.
With WSLg, a user's WSL instance can use X11 as well as Wayland.
For more information, see WSLg [documentation ](https://github.com/microsoft/wslg#wslg-architecture-overview ).
Prior to the release of [WSL Gui (WSLg) ](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux#WSLg )
around 4/20/2021, users had to [manually set up servers ](https://wiki.ubuntu.com/WSL#Advanced_Topics ) on windows for graphic and audio.
Make note of the date for documentation found across the internet.
Following advice from before WSLg's release can lead to additional conflicts.
2020-08-13 23:45:43 +00:00
2022-05-30 18:13:36 +00:00
## [Fedora](https://getfedora.org/)
2020-10-21 22:57:03 +00:00
2020-08-23 20:18:46 +00:00
```bash
2022-01-02 20:36:41 +00:00
sudo dnf install gcc-c++ libX11-devel alsa-lib-devel systemd-devel
2020-08-23 20:18:46 +00:00
```
2022-01-17 22:22:16 +00:00
if using Wayland, you will also need to install
```bash
sudo dnf install wayland-devel libxkbcommon-devel
```
2021-04-27 02:41:34 +00:00
If there are errors with linking during the build process such as:
```bash
= note: /usr/bin/ld: skipping incompatible /usr/lib/libasound.so when searching for -lasound
/usr/bin/ld: skipping incompatible /usr/lib/libasound.so when searching for -lasound
/usr/bin/ld: skipping incompatible /usr/lib/gcc/x86_64-redhat-linux/10/../../../libasound.so when searching for -lasound
/usr/bin/ld: skipping incompatible /lib/libasound.so when searching for -lasound
/usr/bin/ld: skipping incompatible /usr/lib/libasound.so when searching for -lasound
/usr/bin/ld: cannot find -lasound
```
Add your arch to the end of the package to remove the linker error. For example:
```bash
sudo dnf install alsa-lib-devel.x86_64
```
2022-08-29 23:16:43 +00:00
Or if there are errors such as:
```txt
--- stderr
thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: "`\"pkg-config\" \"--libs\" \"--cflags\" \"libudev\"` did not exit successfully: exit status: 1\n--- stderr\nPackage libudev was not found in the pkg-config search path.\nPerhaps you should add the directory containing ` libudev.pc'\nto the PKG_CONFIG_PATH environment variable\nNo package 'libudev' found\n"', /home/< user > /.cargo/registry/src/github.com-1ecc6299db9ec823/libudev-sys-0.1.4/build.rs:38:41
stack backtrace:
0: rust_begin_unwind
at /rustc/9bb77da74dac4768489127d21e32db19b59ada5b/library/std/src/panicking.rs:517:5
1: core::panicking::panic_fmt
at /rustc/9bb77da74dac4768489127d21e32db19b59ada5b/library/core/src/panicking.rs:96:14
2: core::result::unwrap_failed
at /rustc/9bb77da74dac4768489127d21e32db19b59ada5b/library/core/src/result.rs:1617:5
3: core::result::Result< T , E > ::unwrap
at /rustc/9bb77da74dac4768489127d21e32db19b59ada5b/library/core/src/result.rs:1299:23
4: build_script_build::main
at ./build.rs:38:5
5: core::ops::function::FnOnce::call_once
at /rustc/9bb77da74dac4768489127d21e32db19b59ada5b/library/core/src/ops/function.rs:227:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.
warning: build failed, waiting for other jobs to finish...
error: build failed
```
Set the `PKG_CONFIG_PATH` env var to `/usr/lib/<target>/pkgconfig/` . For example on an x86_64 system:
```txt
export PKG_CONFIG_PATH="/usr/lib/x86_64-linux-gnu/pkgconfig/"
```
2020-08-23 20:18:46 +00:00
## Arch / Manjaro
2020-10-21 22:57:03 +00:00
2020-08-23 20:18:46 +00:00
```bash
sudo pacman -S libx11 pkgconf alsa-lib
```
2020-08-25 23:50:44 +00:00
2022-01-05 23:28:30 +00:00
Install `pipewire-alsa` or `pulseaudio-alsa` depending on the sound server you are using.
2022-12-11 19:24:18 +00:00
Depending on your graphics card, you may have to install one of the following:
`vulkan-radeon` , `vulkan-intel` , or `mesa-vulkan-drivers`
2022-09-28 20:38:43 +00:00
2020-10-08 17:28:56 +00:00
## Void
2020-10-21 22:57:03 +00:00
2020-10-08 17:28:56 +00:00
```bash
sudo xbps-install -S pkgconf alsa-lib-devel libX11-devel eudev-libudev-devel
```
2022-12-29 21:37:27 +00:00
## [Nix](https://nixos.org)
2020-08-29 00:09:44 +00:00
Documentation: simplify NixOS dependencies (#3527)
# Objective
The description of NixOS dependencies is extremely long and spends entire paragraphs just for simple line changes.
With this PR it should be much simpler.
## Solution
- Linking Vulkan in `build.rs` is less effective than adding it in LD_LIBRARY_PATH, so I removed the former (related to #1992);
- I put a simple comment explaining the line in the list of dependencies, instead of making entire paragraphs;
- Clang is not in an absolute path in `.cargo/config_fast_builds` anymore, so that there is no need to specify it in `docs/linux_dependencies.md` (didn't test if this breaks other distros, though I doubt it. Also, maybe it could also be done on Darwin for consistency?);
- Also added optional wayland dependencies.
A few notes:
- The x11 libraries will be linked only during the compilation phase. This means that if you use the `x11` feature without these libraries in the environment (for example because you forget to enter the nix shell before compiling), the program will still compile successfully but won't run. You'll have to `cargo clean` and recompile with the x11 libraries in the environment. I don't know if this is important enough to be added to the documentation, but it's not specified anywhere, though I don't think it's specific to NixOS;
- The wayland dependencies need to be put in LD_LIBRARY_PATH only in certain conditions (IIRC, only if using the `dynamic` feature) and the text doesn't specify it. Because putting them there doesn't increase the number of dependencies (they are already in buildInputs) or alter the performance, I doubt anyone will care;
- Should I comment out what isn't needed by default?
- ~I removed `cargo` from buildInputs. Ignoring the fact that it should be in nativeBuildInputs, having it in `shell.nix` allows to use stable Rust in case it's not in the system environment, but maybe the user wanted to use the version that was already in the system environment and will be caught by surprise. In my opinion, if someone is looking at a Bevy's documentation on NixOS, that user will either have Rust already in the system environment (eg. via rustup) or is capable to add the toolchain they want on shell.nix by themselves. This isn't exactly the place to explain how this works.~ ~EDIT: I replaced `cargo` with Rust from the [Oxalica overlay](https://github.com/oxalica/rust-overlay) in order to have the latest nightly.~ EDIT: Removed `cargo` from dependencies. See comments for details.
2022-01-10 17:05:13 +00:00
Add a `shell.nix` file to the root of the project containing:
2020-09-14 21:34:43 +00:00
```nix
2022-12-29 21:37:27 +00:00
{ pkgs ? import < nixpkgs > { } }:
with pkgs;
mkShell rec {
Documentation: simplify NixOS dependencies (#3527)
# Objective
The description of NixOS dependencies is extremely long and spends entire paragraphs just for simple line changes.
With this PR it should be much simpler.
## Solution
- Linking Vulkan in `build.rs` is less effective than adding it in LD_LIBRARY_PATH, so I removed the former (related to #1992);
- I put a simple comment explaining the line in the list of dependencies, instead of making entire paragraphs;
- Clang is not in an absolute path in `.cargo/config_fast_builds` anymore, so that there is no need to specify it in `docs/linux_dependencies.md` (didn't test if this breaks other distros, though I doubt it. Also, maybe it could also be done on Darwin for consistency?);
- Also added optional wayland dependencies.
A few notes:
- The x11 libraries will be linked only during the compilation phase. This means that if you use the `x11` feature without these libraries in the environment (for example because you forget to enter the nix shell before compiling), the program will still compile successfully but won't run. You'll have to `cargo clean` and recompile with the x11 libraries in the environment. I don't know if this is important enough to be added to the documentation, but it's not specified anywhere, though I don't think it's specific to NixOS;
- The wayland dependencies need to be put in LD_LIBRARY_PATH only in certain conditions (IIRC, only if using the `dynamic` feature) and the text doesn't specify it. Because putting them there doesn't increase the number of dependencies (they are already in buildInputs) or alter the performance, I doubt anyone will care;
- Should I comment out what isn't needed by default?
- ~I removed `cargo` from buildInputs. Ignoring the fact that it should be in nativeBuildInputs, having it in `shell.nix` allows to use stable Rust in case it's not in the system environment, but maybe the user wanted to use the version that was already in the system environment and will be caught by surprise. In my opinion, if someone is looking at a Bevy's documentation on NixOS, that user will either have Rust already in the system environment (eg. via rustup) or is capable to add the toolchain they want on shell.nix by themselves. This isn't exactly the place to explain how this works.~ ~EDIT: I replaced `cargo` with Rust from the [Oxalica overlay](https://github.com/oxalica/rust-overlay) in order to have the latest nightly.~ EDIT: Removed `cargo` from dependencies. See comments for details.
2022-01-10 17:05:13 +00:00
nativeBuildInputs = [
Update linux_dependencies.md (#6205)
for nix build, pkgconfig has been renamed to pkg-config. Very small fix :>
# Objective
- Describe the objective or issue this PR addresses.
- If you're fixing a specific issue, say "Fixes #X".
## Solution
- Describe the solution used to achieve the objective above.
---
## Changelog
> This section is optional. If this was a trivial fix, or has no externally-visible impact, you can delete this section.
- What changed as a result of this PR?
- If applicable, organize changes under "Added", "Changed", or "Fixed" sub-headings
- Stick to one or two sentences. If more detail is needed for a particular change, consider adding it to the "Solution" section
- If you can't summarize the work, your change may be unreasonably large / unrelated. Consider splitting your PR to make it easier to review and merge!
## Migration Guide
> This section is optional. If there are no breaking changes, you can delete this section.
- If this PR is a breaking change (relative to the last release of Bevy), describe how a user might need to migrate their code to support these changes
- Simply adding new functionality is not a breaking change.
- Fixing behavior that was definitely a bug, rather than a questionable design choice is not a breaking change.
2022-10-10 16:34:24 +00:00
pkg-config
2020-09-14 21:34:43 +00:00
];
2021-09-06 19:16:09 +00:00
buildInputs = [
2022-12-26 16:52:17 +00:00
udev alsa-lib vulkan-loader
2022-12-29 21:37:27 +00:00
xorg.libX11 xorg.libXcursor xorg.libXi xorg.libXrandr # To use the x11 feature
libxkbcommon wayland # To use the wayland feature
2021-09-06 19:16:09 +00:00
];
2022-12-29 21:37:27 +00:00
LD_LIBRARY_PATH = lib.makeLibraryPath buildInputs;
Documentation: simplify NixOS dependencies (#3527)
# Objective
The description of NixOS dependencies is extremely long and spends entire paragraphs just for simple line changes.
With this PR it should be much simpler.
## Solution
- Linking Vulkan in `build.rs` is less effective than adding it in LD_LIBRARY_PATH, so I removed the former (related to #1992);
- I put a simple comment explaining the line in the list of dependencies, instead of making entire paragraphs;
- Clang is not in an absolute path in `.cargo/config_fast_builds` anymore, so that there is no need to specify it in `docs/linux_dependencies.md` (didn't test if this breaks other distros, though I doubt it. Also, maybe it could also be done on Darwin for consistency?);
- Also added optional wayland dependencies.
A few notes:
- The x11 libraries will be linked only during the compilation phase. This means that if you use the `x11` feature without these libraries in the environment (for example because you forget to enter the nix shell before compiling), the program will still compile successfully but won't run. You'll have to `cargo clean` and recompile with the x11 libraries in the environment. I don't know if this is important enough to be added to the documentation, but it's not specified anywhere, though I don't think it's specific to NixOS;
- The wayland dependencies need to be put in LD_LIBRARY_PATH only in certain conditions (IIRC, only if using the `dynamic` feature) and the text doesn't specify it. Because putting them there doesn't increase the number of dependencies (they are already in buildInputs) or alter the performance, I doubt anyone will care;
- Should I comment out what isn't needed by default?
- ~I removed `cargo` from buildInputs. Ignoring the fact that it should be in nativeBuildInputs, having it in `shell.nix` allows to use stable Rust in case it's not in the system environment, but maybe the user wanted to use the version that was already in the system environment and will be caught by surprise. In my opinion, if someone is looking at a Bevy's documentation on NixOS, that user will either have Rust already in the system environment (eg. via rustup) or is capable to add the toolchain they want on shell.nix by themselves. This isn't exactly the place to explain how this works.~ ~EDIT: I replaced `cargo` with Rust from the [Oxalica overlay](https://github.com/oxalica/rust-overlay) in order to have the latest nightly.~ EDIT: Removed `cargo` from dependencies. See comments for details.
2022-01-10 17:05:13 +00:00
}
2021-09-06 19:16:09 +00:00
```
2022-12-29 21:37:27 +00:00
And enter it by just running `nix-shell` .
You should be able compile Bevy programs using `cargo run` within this nix-shell.
You can do this in one line with `nix-shell --run "cargo run"` .
This is also possible with [Nix flakes ](https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html ).
Instead of creating `shell.nix` , you just need to add the derivation (`mkShell`)
to your `devShells` in `flake.nix` . Run `nix develop` to enter the shell and
`nix develop -c cargo run` to run the program. See
[Nix's documentation ](https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-develop.html )
for more information about `devShells` .
Note that this template does not add Rust to the environment because there are many ways to do it.
For example, to use stable Rust from nixpkgs, you can add `cargo` and `rustc` to `nativeBuildInputs` .
2021-09-06 19:16:09 +00:00
2022-12-29 21:37:27 +00:00
[Here ](https://github.com/NixOS/nixpkgs/blob/master/pkgs/games/jumpy/default.nix )
is an example of packaging a Bevy program in nix.
2021-09-06 19:16:09 +00:00
2022-05-30 18:13:36 +00:00
## [OpenSUSE](https://www.opensuse.org/)
2021-07-05 22:35:50 +00:00
```bash
2022-05-01 01:00:27 +00:00
sudo zypper install libudev-devel gcc-c++ alsa-lib-devel
2021-07-05 22:35:50 +00:00
```
2022-03-21 04:15:37 +00:00
## Gentoo
```bash
sudo emerge --ask libX11 pkgconf alsa-lib
```
2022-05-30 18:13:36 +00:00
2022-11-28 13:54:15 +00:00
When using an AMD Radeon GPU, you may also need to emerge `amdgpu-pro-vulkan` to get Bevy to find the GPU.
2022-12-11 18:46:48 +00:00
When using a NVIDIA GPU with the proprietary driver (eg. `x11-drivers/nvidia-drivers` ), you may also need to emerge `media-libs/vulkan-loader` to get Bevy to find the GPU. NVIDIA Vulkan driver is included in `nvidia-driver` , but may need the loader to find the correct driver. See Gentoo [Documentation ](https://wiki.gentoo.org/wiki/Vulkan ) for details.
2022-05-30 18:13:36 +00:00
## [Clear Linux OS](https://clearlinux.org/)
```bash
sudo swupd bundle-add devpkg-alsa-lib
sudo swupd bundle-add devpkg-libgudev
```
2023-02-20 04:31:49 +00:00
## [Alpine Linux](https://alpinelinux.org/)
Run the following command to install `GNU C compiler, standard C development libraries, pkg-config, X11 development libraries, ALSA development libraries, eudev development libraries` :
```sh
sudo apk add gcc libc-dev pkgconf libx11-dev alsa-lib-dev eudev-dev
```
Install a GPU renderer for you graphics card. For Intel integrated GPUs:
```sh
sudo apk add mesa-vulkan-intel
```
If you have issues with `winit` such as `Failed to initialize backend!` or similar, try adding the following to your `~/.cargo/config.toml` (more information at the [issue #1818 ](https://github.com/rust-windowing/winit/issues/1818 ) of the [winit repository ](https://github.com/rust-windowing/winit ):
```toml
[build]
rustflags = ["-C", "target-feature=-crt-static"]
```
2023-12-17 00:46:50 +00:00
## [Solus](https://getsol.us)
```sh
sudo eopkg it -c system.devel
sudo eopkg it g++ libx11-devel alsa-lib-devel
```
If using Wayland, you may also need to install
```sh
sudo eopkg it wayland-devel libxkbcommon-devel
```
Compiling with clang is also possible - replace the `g++` package with `llvm-clang`
2024-09-16 23:18:14 +00:00
## [FreeBSD](https://www.freebsd.org/)
It is necessary to have the hgame module loaded in order to satisfy gli-rs. It will still throw an error, but the program should run successfully. You can make sure the kernel module is loaded on start up by adding the following line to /boot/loader.conf:
```sh
hgame_load="YES"
```
