Skip to content

Commit

Permalink
add FAQ entry on how to run non-nix executables
Browse files Browse the repository at this point in the history
  • Loading branch information
tejing1 committed Dec 7, 2023
1 parent 3569f20 commit b32c6e6
Showing 1 changed file with 49 additions and 0 deletions.
49 changes: 49 additions & 0 deletions source/guides/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,55 @@ See <https://github.com/nix-community/home-manager>
## 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 traditional linux standard for where program files are stored on the filesystem.

:::{note}
The NixOS community uses the term "FHS" for traditional linux environments, which is short for "[Filesystem Hierarchy Standard](https://refspecs.linuxfoundation.org/FHS_3.0/fhs/index.html)".
:::

There are a few ways to bridge this gap in environment expectations:

- Use the version packaged in nixpkgs, if there is one.
You can search available packages at <https://search.nixos.org/packages>.

- 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).
- Set the program's ELF metadata 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.
If the program downloads and runs other executables, for example.

- 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
];
```

Run `nixos-rebuild switch`, then 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 <command>"
```

### How to build my own ISO?

See <http://nixos.org/nixos/manual/index.html#sec-building-image>
Expand Down

0 comments on commit b32c6e6

Please sign in to comment.