Merge master into staging-next

This chapter describes several special build helpers.

```{=include=} sections

special/fakenss.section.md

special/fhs-environments.section.md

special/makesetuphook.section.md

special/mkshell.section.md

# fakeNss {#sec-fakeNss}

Provides `/etc/passwd` and `/etc/group` files that contain `root` and `nobody`, allowing user/group lookups to work in binaries that insist on doing those.

This might be a better choice than a custom script running `useradd` and related utilities if you only need those files to exist with some entries.

`fakeNss` also provides `/etc/nsswitch.conf`, configuring NSS host resolution to first check `/etc/hosts` before checking DNS, since the default in the absence of a config file (`dns [!UNAVAIL=return] files`) is quite unexpected.

It also creates an empty directory at `/var/empty` because it uses that as the home directory for the `root` and `nobody` users.

The `/var/empty` directory can also be used as a `chroot` target to prevent file access in processes that do not need to access files, if your container runs such processes.

The user entries created by `fakeNss` use the `/bin/sh` shell, which is not provided by `fakeNss` because in most cases it won't be used.

If you need that to be available, see [`dockerTools.binSh`](#sssec-pkgs-dockerTools-helpers-binSh) or provide your own.

## Inputs {#sec-fakeNss-inputs}

`fakeNss` is made available in Nixpkgs as a package rather than a function, but it has two attributes that can be overridden and might be useful in particular cases.

For more details on how overriding works, see [](#ex-fakeNss-overriding) and [](#sec-pkg-override).

`extraPasswdLines` (List of Strings; _optional_)

: A list of lines that will be added to `/etc/passwd`.

  Useful if extra users need to exist in the output of `fakeNss`.

  If `extraPasswdLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.

  Those entries will always exist.

  Lines specified here must follow the format in {manpage}`passwd(5)`.

  _Default value:_ `[]`.

`extraGroupLines` (List of Strings; _optional_)

: A list of lines that will be added to `/etc/group`.

  Useful if extra groups need to exist in the output of `fakeNss`.

  If `extraGroupLines` is specified, it will **not** override the `root` and `nobody` entries created by `fakeNss`.

  Those entries will always exist.

  Lines specified here must follow the format in {manpage}`group(5)`.

  _Default value:_ `[]`.

## Examples {#sec-fakeNss-examples}

:::{.example #ex-fakeNss-dockerTools-buildImage}

# Using `fakeNss` with `dockerTools.buildImage`

This example shows how to use `fakeNss` as-is.

It is useful with functions in `dockerTools` to allow building Docker images that have the `/etc/passwd` and `/etc/group` files.

This example includes the `hello` binary in the image so it can do something besides just have the extra files.

```nix

{ dockerTools, fakeNss, hello }:

dockerTools.buildImage {

  name = "image-with-passwd";

  tag = "latest";

  copyToRoot = [ fakeNss hello ];

  config = {

    Cmd = [ "/bin/hello" ];

  };

}

```

:::

:::{.example #ex-fakeNss-overriding}

# Using `fakeNss` with an override to add extra lines

The following code uses `override` to add extra lines to `/etc/passwd` and `/etc/group` to create another user and group entry.

```nix

{ fakeNss }:

fakeNss.override {

  extraPasswdLines = ["newuser:x:9001:9001:new user:/var/empty:/bin/sh"];

  extraGroupLines = ["newuser:x:9001:"];

}

```

:::

This hook helps with installing manpages and shell completion files. It exposes 2 shell functions `installManPage` and `installShellCompletion` that can be used from your `postInstall` hook.

The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct directory.

The `installManPage` function takes one or more paths to manpages to install. The manpages must have a section suffix, and may optionally be compressed (with `.gz` suffix). This function will place them into the correct `share/man/man<section>/` directory, in [`outputMan`](#outputman).

The `installShellCompletion` function takes one or more paths to shell completion files. By default it will autodetect the shell type from the completion file extension, but you may also specify it by passing one of `--bash`, `--fish`, or `--zsh`. These flags apply to all paths listed after them (up until another shell flag is given). Each path may also have a custom installation name provided by providing a flag `--name NAME` before the path. If this flag is not provided, zsh completions will be renamed automatically such that `foobar.zsh` becomes `_foobar`. A root name may be provided for all paths using the flag `--cmd NAME`; this synthesizes the appropriate name depending on the shell (e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for zsh). The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which case the shell and name must be provided.

To package Dotnet applications, you can use `buildDotnetModule`. This has similar arguments to `stdenv.mkDerivation`, with the following additions:

* `projectFile` is used for specifying the dotnet project file, relative to the source root. These have `.sln` (entire solution) or `.csproj` (single project) file extensions. This can be a list of multiple projects as well. When omitted, will attempt to find and build the solution (`.sln`). If running into problems, make sure to set it to a file (or a list of files) with the `.csproj` extension - building applications as entire solutions is not fully supported by the .NET CLI.

* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. This file can also be generated manually using `nuget-to-nix` tool, which is available in nixpkgs. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.

* `nugetDeps` takes either a path to a `deps.nix` file, or a derivation. The `deps.nix` file can be generated using the script attached to `passthru.fetch-deps`. If the argument is a derivation, it will be used directly and assume it has the same output as `mkNugetDeps`.

::: {.note}

For more detail about managing the `deps.nix` file, see [Generating and updating NuGet dependencies](#generating-and-updating-nuget-dependencies)

:::

* `packNupkg` is used to pack project as a `nupkg`, and installs it to `$out/share`. If set to `true`, the derivation can be used as a dependency for another dotnet project by adding it to `projectReferences`.

* `projectReferences` can be used to resolve `ProjectReference` project items. Referenced projects can be packed with `buildDotnetModule` by setting the `packNupkg = true` attribute and passing a list of derivations to `projectReferences`. Since we are sharing referenced projects as NuGets they must be added to csproj/fsproj files as `PackageReference` as well.

 For example, your project has a local dependency:

}

```

Keep in mind that you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.

## Dotnet global tools {#dotnet-global-tools}

[.NET Global tools](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools) are a mechanism provided by the dotnet CLI to install .NET binaries from Nuget packages.

  };

}

```

## Generating and updating NuGet dependencies {#generating-and-updating-nuget-dependencies}

First, restore the packages to the `out` directory, ensure you have cloned

the upstream repository and you are inside it.

```bash

$ dotnet restore --packages out

  Determining projects to restore...

  Restored /home/lychee/Celeste64/Celeste64.csproj (in 1.21 sec).

```

Next, use `nuget-to-nix` tool provided in nixpkgs to generate a lockfile to `deps.nix` from

the packages inside the `out` directory.

```bash

$ nuget-to-nix out > deps.nix

```

Which `nuget-to-nix` will generate an output similar to below

```

{ fetchNuGet }: [

  (fetchNuGet { pname = "FosterFramework"; version = "0.1.15-alpha"; sha256 = "0pzsdfbsfx28xfqljcwy100xhbs6wyx0z1d5qxgmv3l60di9xkll"; })

  (fetchNuGet { pname = "Microsoft.AspNetCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1gjz379y61ag9whi78qxx09bwkwcznkx2mzypgycibxk61g11da1"; })

  (fetchNuGet { pname = "Microsoft.NET.ILLink.Tasks"; version = "8.0.1"; sha256 = "1drbgqdcvbpisjn8mqfgba1pwb6yri80qc4mfvyczqwrcsj5k2ja"; })

  (fetchNuGet { pname = "Microsoft.NETCore.App.Runtime.linux-x64"; version = "8.0.1"; sha256 = "1g5b30f4l8a1zjjr3b8pk9mcqxkxqwa86362f84646xaj4iw3a4d"; })

  (fetchNuGet { pname = "SharpGLTF.Core"; version = "1.0.0-alpha0031"; sha256 = "0ln78mkhbcxqvwnf944hbgg24vbsva2jpih6q3x82d3h7rl1pkh6"; })

  (fetchNuGet { pname = "SharpGLTF.Runtime"; version = "1.0.0-alpha0031"; sha256 = "0lvb3asi3v0n718qf9y367km7qpkb9wci38y880nqvifpzllw0jg"; })

  (fetchNuGet { pname = "Sledge.Formats"; version = "1.2.2"; sha256 = "1y0l66m9rym0p1y4ifjlmg3j9lsmhkvbh38frh40rpvf1axn2dyh"; })

  (fetchNuGet { pname = "Sledge.Formats.Map"; version = "1.1.5"; sha256 = "1bww60hv9xcyxpvkzz5q3ybafdxxkw6knhv97phvpkw84pd0jil6"; })

  (fetchNuGet { pname = "System.Numerics.Vectors"; version = "4.5.0"; sha256 = "1kzrj37yzawf1b19jq0253rcs8hsq1l2q8g69d7ipnhzb0h97m59"; })

]

```

Finally, you move the `deps.nix` file to the appropriate location to be used by `nugetDeps`, then you're all set!

If you ever need to update the dependencies of a package, you instead do

* `nix-build -A package.fetch-deps` to generate the update script for `package`

* Run `./result deps.nix` to regenerate the lockfile to `deps.nix`, keep in mind if a location isn't provided, it will write to a temporary path instead

* Finally, move the file where needed and look at its contents to confirm it has updated the dependencies.

When packaging a new .NET application in nixpkgs, you can tag the [`@NixOS/dotnet`](https://github.com/orgs/nixos/teams/dotnet) team for help and code review.