Merge pull request #235041 from mdarocha/dotnet-tools

* `runtimeDeps` is used to wrap libraries into `LD_LIBRARY_PATH`. This is how dotnet usually handles runtime dependencies.

* `buildType` is used to change the type of build. Possible values are `Release`, `Debug`, etc. By default, this is set to `Release`.

* `selfContainedBuild` allows to enable the [self-contained](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-self-contained) build flag. By default, it is set to false and generated applications have a dependency on the selected dotnet runtime. If enabled, the dotnet runtime is bundled into the executable and the built app has no dependency on Dotnet.

* `useAppHost` will enable creation of a binary executable that runs the .NET application using the specified root. More info in [Microsoft docs](https://learn.microsoft.com/en-us/dotnet/core/deploying/#publish-framework-dependent). Enabled by default.

* `useDotnetFromEnv` will change the binary wrapper so that it uses the .NET from the environment. The runtime specified by `dotnet-runtime` is given as a fallback in case no .NET is installed in the user's environment. This is most useful for .NET global tools and LSP servers, which often extend the .NET CLI and their runtime should match the users' .NET runtime.

* `dotnet-sdk` is useful in cases where you need to change what dotnet SDK is being used. You can also set this to the result of `dotnetSdkPackages.combinePackages`, if the project uses multiple SDKs to build.

* `dotnet-runtime` is useful in cases where you need to change what dotnet runtime is being used. This can be either a regular dotnet runtime, or an aspnetcore.

* `dotnet-test-sdk` is useful in cases where unit tests expect a different dotnet SDK. By default, this is set to the `dotnet-sdk` attribute.

  runtimeDeps = [ ffmpeg ]; # This will wrap ffmpeg's library path into `LD_LIBRARY_PATH`.

}

```

## 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.

They can be installed either as a global tool for the entire system, or as a local tool specific to project.

The local installation is the easiest and works on NixOS in the same way as on other Linux distributions.

[See dotnet documention](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-local-tool) to learn more.

[The global installation method](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools#install-a-global-tool)

should also work most of the time. You have to remember to update the `PATH`

value to the location the tools are installed to (the CLI will inform you about it during installation) and also set

the `DOTNET_ROOT` value, so that the tool can find the .NET SDK package.

You can find the path to the SDK by running `nix eval --raw nixpkgs#dotnet-sdk` (substitute the `dotnet-sdk` package for

another if a different SDK version is needed).

This method is not recommended on NixOS, since it's not declarative and involves installing binaries not made for NixOS,

which will not always work.

The third, and preferred way, is packaging the tool into a Nix derivation.

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

Dotnet global tools are standard .NET binaries, just made available through a special

NuGet package. Therefore, they can be built and packaged like every .NET application,

using `buildDotnetModule`.

If however the source is not available or difficult to build, the

`buildDotnetGlobalTool` helper can be used, which will package the tool

straight from its NuGet package.

This helper has the same arguments as `buildDotnetModule`, with a few differences:

* `pname` and `version` are required, and will be used to find the NuGet package of the tool

* `nugetName` can be used to override the NuGet package name that will be downloaded, if it's different from `pname`

* `nugetSha256` is the hash of the fetched NuGet package. Set this to `lib.fakeHash256` for the first build, and it will error out, giving you the proper hash. Also remember to update it during version updates (it will not error out if you just change the version while having a fetched package in `/nix/store`)

* `dotnet-runtime` is set to `dotnet-sdk` by default. When changing this, remember that .NET tools fetched from NuGet require an SDK.

Here is an example of packaging `pbm`, an unfree binary without source available:

```nix

{ buildDotnetGlobalTool, lib }:

buildDotnetGlobalTool {

  pname = "pbm";

  version = "1.3.1";

  nugetSha256 = "sha256-ZG2HFyKYhVNVYd2kRlkbAjZJq88OADe3yjxmLuxXDUo=";

  meta = with lib; {

    homepage = "https://cmd.petabridge.com/index.html";

    changelog = "https://cmd.petabridge.com/articles/RELEASE_NOTES.html";

    license = licenses.unfree;

    platforms = platforms.linux;

  };

}

```

{ buildDotnetModule, emptyDirectory, mkNugetDeps, dotnet-sdk }:

{ pname

, version

  # Name of the nuget package to install, if different from pname

, nugetName ? pname

  # Hash of the nuget package to install, will be given on first build

, nugetSha256 ? ""

  # Additional nuget deps needed by the tool package

, nugetDeps ? (_: [])

  # Executables to wrap into `$out/bin`, same as in `buildDotnetModule`, but with

  # a default of `pname` instead of null, to avoid auto-wrapping everything

, executables ? pname

  # The dotnet runtime to use, dotnet tools need a full SDK to function

, dotnet-runtime ? dotnet-sdk

, ...

} @ args:

buildDotnetModule (args // {

  inherit pname version dotnet-runtime executables;

  src = emptyDirectory;

  nugetDeps = mkNugetDeps {

    name = pname;

    nugetDeps = { fetchNuGet }: [

      (fetchNuGet { pname = nugetName; inherit version; sha256 = nugetSha256; })

    ] ++ (nugetDeps fetchNuGet);

  };

  projectFile = "";

  useDotnetFromEnv = true;

  dontBuld = true;

  installPhase = ''

    runHook preInstall

    dotnet tool install --tool-path $out/lib/${pname} ${nugetName}

    # remove files that contain nix store paths to temp nuget sources we made

    find $out -name 'project.assets.json' -delete

    find $out -name '.nupkg.metadata' -delete

    runHook postInstall

  '';

})

, nuget-to-nix

, cacert

, coreutils

, runtimeShellPackage

}:

{ name ? "${args.pname}-${args.version}"

, buildType ? "Release"

  # If set to true, builds the application as a self-contained - removing the runtime dependency on dotnet

, selfContainedBuild ? false

  # Whether to explicitly enable UseAppHost when building

  # Whether to use an alternative wrapper, that executes the application DLL using the dotnet runtime from the user environment. `dotnet-runtime` is provided as a default in case no .NET is installed

  # This is useful for .NET tools and applications that may need to run under different .NET runtimes

, useDotnetFromEnv ? false

  # Whether to explicitly enable UseAppHost when building. This is redundant if useDotnetFromEnv is enabledz

, useAppHost ? true

  # The dotnet SDK to use.

, dotnet-sdk ? dotnetCorePackages.sdk_6_0

  # gappsWrapperArgs gets included when wrapping for dotnet, as to avoid double wrapping

  dontWrapGApps = args.dontWrapGApps or true;

  inherit selfContainedBuild useAppHost;

  inherit selfContainedBuild useAppHost useDotnetFromEnv;

  passthru = {

    inherit nuget-source;

      writeShellScript "fetch-${pname}-deps" ''

        set -euo pipefail

        export PATH="${lib.makeBinPath [ coreutils dotnet-sdk (nuget-to-nix.override { inherit dotnet-sdk; }) ]}"

        export PATH="${lib.makeBinPath [ coreutils runtimeShellPackage dotnet-sdk (nuget-to-nix.override { inherit dotnet-sdk; }) ]}"

        for arg in "$@"; do

            case "$arg" in

        echo "Restoring project..."

        ${dotnet-sdk}/bin/dotnet tool restore

        mv $HOME/.nuget/packages/* $tmp/nuget_pkgs || true

        cp -r $HOME/.nuget/packages/* $tmp/nuget_pkgs || true

        for rid in "${lib.concatStringsSep "\" \"" runtimeIds}"; do

            (( ''${#projectFiles[@]} == 0 )) && dotnetRestore "" "$rid"

                dotnetRestore "$project" "$rid"

            done

        done

        # Second copy, makes sure packages restored by ie. paket are included

        cp -r $HOME/.nuget/packages/* $tmp/nuget_pkgs || true

        echo "Succesfully restored project"

{ lib

, stdenv

, which

, coreutils

, callPackage

, makeSetupHook

, makeWrapper

      substitutions = {

        dotnetRuntime = dotnet-runtime;

        runtimeDeps = libraryPath;

        shell = stdenv.shell;

        which = "${which}/bin/which";

        dirname = "${coreutils}/bin/dirname";

      };

    } ./dotnet-fixup-hook.sh) { };

}

            ${dotnetFlags[@]}

    }

    (( "${#projectFile[@]}" == 0 )) && dotnetRestore

    # Generate a NuGet.config file to make sure everything,

    # including things like <Sdk /> dependencies, is restored from the proper source

cat <<EOF > "./NuGet.config"

</configuration>

EOF

    # Patch paket.dependencies and paket.lock (if found) to use the proper source. This ensures

    # paket restore works correctly

    # We use + instead of / in sed to avoid problems with slashes

    find -name paket.dependencies -exec sed -i 's+source .*+source @nugetSource@/lib+g' {} \;

    find -name paket.lock -exec sed -i 's+remote:.*+remote: @nugetSource@/lib+g' {} \;

    env dotnet tool restore --add-source "@nugetSource@/lib"

    (( "${#projectFile[@]}" == 0 )) && dotnetRestore

    for project in ${projectFile[@]} ${testProjectFile[@]-}; do

        dotnetRestore "$project"

    done