diff --git a/_redirects b/_redirects index 887e618..ccee6a8 100644 --- a/_redirects +++ b/_redirects @@ -25,3 +25,4 @@ /recipes/direnv /guides/recipes/direnv 301 /tutorials/learning-journey/sharing-dependencies /guides/recipes/sharing-dependencies 301 /tutorials/learning-journey/packaging-existing-software /tutorials/packaging-existing-software 301 +/permalink/stub-ld /guides/faq#how-to-run-non-nix-executables 301 diff --git a/source/guides/faq.md b/source/guides/faq.md index c543b5c..c701cb8 100644 --- a/source/guides/faq.md +++ b/source/guides/faq.md @@ -49,6 +49,54 @@ See ## NixOS +### How to run non-nix executables? + +NixOS cannot run dynamically linked executables intended for generic Linux environments out of the box. +This is because, by design, it does not have a global library path, nor does it follow the [Filesystem Hierarchy Standard](https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html) (FHS). + +There are a few ways to resolve this mismatch in environment expectations: + +- Use the version packaged in Nixpkgs, if there is one. + You can search available packages at . + +- Write a Nix expression for the program to package it in your own configuration. + + There are multiple approaches to this: + - Build from source. + + Many open-source programs are highly flexible at compile time in terms of where their files go. + For an introduction to this, see [](../tutorials/packaging-existing-software). + - Modify the program's [ELF header](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format) to include paths to libraries using [`autoPatchelfHook`](https://nixos.org/manual/nixpkgs/stable/#setup-hook-autopatchelfhook). + + Do this if building from source isn't feasible. + - Wrap the program to run in an FHS-like environment using [`buildFHSEnv`](https://nixos.org/manual/nixpkgs/stable/#sec-fhs-environments). + + This is a last resort, but sometimes necessary, for example if the program downloads and runs other executables. + +- Create a library path that only applies to unpackaged programs by using [`nix-ld`](https://github.com/Mic92/nix-ld). + Add this to your `configuration.nix`: + + ```nix + programs.nix-ld.enable = true; + programs.nix-ld.libraries = with pkgs; [ + # Add any missing dynamic libraries for unpackaged programs + # here, NOT in environment.systemPackages + ]; + ``` + + Then run `nixos-rebuild switch`, and log out and back in again to propagate the new environment variables. + (This is only necessary when enabling `nix-ld`; changes in included libraries take effect immediately on rebuild.) + + :::{note} + `nix-ld` does not work for 32-bit executables on `x86_64` machines. + ::: + +- Run your program in the FHS-like environment made for the Steam package using [`steam-run`](https://nixos.org/manual/nixpkgs/stable/#sec-steam-run): + + ```shell-session + $ nix-shell -p steam-run --run "steam-run " + ``` + ### How to build my own ISO? See