From fc0f15f11e3b327c65deaaccf722a8064a1a300b Mon Sep 17 00:00:00 2001 From: SuperSamus Date: Mon, 10 Jan 2022 17:05:13 +0000 Subject: [PATCH] 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. --- .cargo/config_fast_builds | 2 +- docs/linux_dependencies.md | 88 +++++++------------------------------- 2 files changed, 17 insertions(+), 73 deletions(-) diff --git a/.cargo/config_fast_builds b/.cargo/config_fast_builds index eae5a85ea428a..b92e77e95884a 100644 --- a/.cargo/config_fast_builds +++ b/.cargo/config_fast_builds @@ -4,7 +4,7 @@ # If you are using rust stable, remove the "-Zshare-generics=y" below. [target.x86_64-unknown-linux-gnu] -linker = "/usr/bin/clang" +linker = "clang" rustflags = ["-Clink-arg=-fuse-ld=lld", "-Zshare-generics=y"] # NOTE: you must manually install https://github.com/michaeleisel/zld on mac. you can easily do this with the "brew" package manager: diff --git a/docs/linux_dependencies.md b/docs/linux_dependencies.md index 7ebc1e7ee1e59..aabc5835b25b9 100644 --- a/docs/linux_dependencies.md +++ b/docs/linux_dependencies.md @@ -65,88 +65,32 @@ sudo xbps-install -S pkgconf alsa-lib-devel libX11-devel eudev-libudev-devel ## NixOS -Add a `build.rs` file to your project containing: - -```rust -# build.rs - -fn main() { - if cfg!(target_os = "linux") { - println!("cargo:rustc-link-lib=vulkan"); - } -} -``` - -These packages provide the dependencies required to run a bevy project. They can be installed globally or via nix-shell. -Based on your global configuration it also might be necessary to allow unfree packages: - -```bash -nix-shell -p cargo pkgconfig udev alsaLib x11 xorg.libXcursor xorg.libXrandr xorg.libXi vulkan-tools vulkan-headers vulkan-loader vulkan-validation-layers -``` - -Alternatively, you can define `shell.nix` containing: +Add a `shell.nix` file to the root of the project containing: ```nix # shell.nix -{ pkgs ? import { } }: -with pkgs; -mkShell { - buildInputs = [ - cargo - pkgconfig udev alsaLib - x11 xorg.libXcursor xorg.libXrandr xorg.libXi - vulkan-tools vulkan-headers vulkan-loader vulkan-validation-layers +{ pkgs ? import {} }: +with pkgs; mkShell { + nativeBuildInputs = [ + pkgconfig + clang lld # To use lld linker ]; -} -``` - -And enter it by just running `nix-shell`. - -You should be able compile bevy programms using `cargo` within this nix-shell. - -### Fast compilation - -According to the Bevy getting started guide (for v0.5), you can enable fast compilation by add a Cargo config file and by adding `lld` and `clang`. As long as you add `clang` and `lld` to your environment, it should mostly work, but you'll still need to modify the Cargo config file so that it doesn't point to `/usr/bin/clang` anymore. - -Working off the above files, let's make the necessary changes. - -For `.cargo/config.toml`, change the path to the linker from `/usr/bin/clang` to `clang`: - -``` diff - [target.x86_64-unknown-linux-gnu] -- linker = "/usr/bin/clang" -+ linker = "clang" - rustflags = ["-Clink-arg=-fuse-ld=lld", "-Zshare-generics=y"] -``` - -In `shell.nix`, add `lld` and `clang`: - -``` diff buildInputs = [ - cargo - pkgconfig udev alsaLib lutris - x11 xorg.libXcursor xorg.libXrandr xorg.libXi - vulkan-tools vulkan-headers vulkan-loader vulkan-validation-layers -+ clang lld + udev alsaLib vulkan-loader + x11 xorg.libXcursor xorg.libXrandr xorg.libXi # To use x11 feature + libxkbcommon wayland # To use wayland feature ]; + shellHook = ''export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${pkgs.lib.makeLibraryPath [ + udev alsaLib vulkan-loader + libxkbcommon wayland # To use wayland feature + ]}"''; +} ``` -### Building apps and using the GPU - -If you run into issues with building basic apps or activating the GPU ('thread 'main' panicked at 'Unable to find a GPU!'), then you may need to update your environment's `LD_LIBRARY_PATH`. To solve issues relating to missing `libudev.so.1` files, `alsa` drivers, and being unable to find a GPU, try updating the environment variable in your `shell.nix` by creating a `shellHook`: +And enter it by just running `nix-shell`. You should be able compile bevy programms using `cargo` within this nix-shell. -``` diff - { pkgs ? import { } }: - with pkgs; - mkShell { -+ shellHook = ''export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:${pkgs.lib.makeLibraryPath [ -+ pkgs.alsaLib -+ pkgs.udev -+ pkgs.vulkan-loader -+ ]}"''; - buildInputs = [ -``` +Note that this template doesn't add Rust to the environment because there are many ways to do it, each with its pros and cons. For example, to use stable Rust from nixpkgs you can add `cargo` to `nativeBuildInputs`. ## Opensuse Tumbleweed