Get Gentoo!
Development Guide
  1. Master index
  2. Eclass reference

dotnet-pkg.eclass

Name

dotnet-pkg.eclass -- common functions and variables for .NET packages

Description

This eclass is designed to help with building and installing packages that use the .NET SDK. It provides the required phase functions and special variables that make it easier to write ebuilds for .NET packages. If you do not use the exported phase functions, then consider using the "dotnet-pkg-base.eclass" instead.

.NET SDK is a open-source framework from Microsoft, it is a cross-platform successor to .NET Framework.

.NET packages require proper inspection before packaging: - the compatible .NET SDK version has to be declared,

this can be done by inspecting the package's "*.proj" files,
unlike JAVA, .NET packages tend to lock onto one exact selected .NET SDK
version, so building with other .NET versions will be mostly unsupported,

  • Nugets, packages' .NET dependencies, which are similar to JAVA's JARs, have to be listed using either the "NUGETS" variable or bundled inside a "prebuilt" archive, in second case also the "NUGET_PACKAGES" variable has to be explicitly set.

  • the main project file (*.proj) that builds the project has to be specified by the "DOTNET_PROJECT" variable.

Supported EAPIs

8

Transitively Provided Eclasses

  • dotnet-pkg-base

  • nuget

Exported Phases

  • pkg_setup

  • src_unpack

  • src_compile

  • src_test

  • src_install

  • src_prepare

  • src_configure

Functions

dotnet-pkg_force-compat

This function appends special options to all "DOTNET_PKG_*_EXTRA_ARGS" variables in an attempt to force compatibility to the picked "DOTNET_PKG_COMPAT" .NET SDK version.

Call this function post-inherit.

dotnet-pkg_pkg_setup

Default "pkg_setup" for the "dotnet-pkg" eclass. Pre-build configuration and checks.

Calls "dotnet-pkg-base_pkg_setup".

dotnet-pkg_src_unpack

Default "src_unpack" for the "dotnet-pkg" eclass. Unpack the package sources.

Includes a special exception for nugets (".nupkg" files) - they are instead copied into the "NUGET_PACKAGES" directory.

dotnet-pkg_remove-bad <solution>

Remove all projects specified by "DOTNET_PKG_BAD_PROJECTS" from a given solution file.

Used by "dotnet-pkg_src_prepare".

dotnet-pkg_src_prepare

Default "src_prepare" for the "dotnet-pkg" eclass. Prepare the package sources.

Run "dotnet-pkg-base_remove-global-json", "dotnet-pkg-base_remove-bad" for each found solution file and prepare for using Nuget.

dotnet-pkg_foreach-project <args> ...

Run a specified command for each project listed inside the "DOTNET_PKG_PROJECTS" variable.

Used by "dotnet-pkg_src_configure" and "dotnet-pkg_src_compile".

dotnet-pkg_src_configure

Default "src_configure" for the "dotnet-pkg" eclass. Configure the package.

First show information about current .NET SDK that is being used, then restore the project file specified by "DOTNET_PROJECT", afterwards restore any found solutions.

dotnet-pkg_src_compile

Default "src_compile" for the "dotnet-pkg" eclass. Build the package.

Build the package using "dotnet build" in the directory specified by either "DOTNET_PROJECT" or "S" (temporary build directory) variables.

For more info see: "DOTNET_PROJECT" variable and "dotnet-pkg-base_get-project" function.

dotnet-pkg_src_test

Default "src_test" for the "dotnet-pkg" eclass. Test the package.

Test the package by testing any found solutions.

It is very likely that this function will either not execute any tests or will execute wrong or incomplete test suite. Maintainers should inspect if any and/or correct tests are ran.

dotnet-pkg_src_install

Default "src_install" for the "dotnet-pkg" eclass. Install the package.

This is the default package install:

  • install the compiled .NET package artifacts,

for more info see "dotnet-pkg-base_install" and "DOTNET_PKG_OUTPUT", - create launcher from the .NET package directory to "/usr/bin",

phase will detect to choose either executable with capital letter
(common among .NET packages) or not,

  • call "einstalldocs".

It is very likely that this function is either insufficient or has to be redefined in a ebuild.

Variables

DOTNET_PKG_BAD_PROJECTS = ()

List of projects to remove from all found solution (".sln") files. The projects are removed in the "dotnet-pkg_src_prepare" function.

This variable should be set after inheriting "dotnet-pkg.eclass".

Default value is an empty array.

Example:

DOTNET_PKG_BAD_PROJECTS=( "${S}/BrokenTests" )
DOTNET_PKG_PROJECTS=( "${S}/DotnetProject" )

For more info see: "dotnet-pkg_remove-bad" function.

DOTNET_PKG_PROJECTS

Path to the main .NET project files (".csproj", ".fsproj", ".vbproj") used by default by "dotnet-pkg_src_compile" phase function.

In .NET version 6.0 and lower it was possible to build a project solution (".sln") immediately with output to a specified directory ("--output DIR"), but versions >= 7.0 deprecated this behavior. This means that "dotnet-pkg-base_build" will fail when pointed to a solution or a directory containing a solution file.

This variable should be set after inheriting "dotnet-pkg.eclass", it is also advised that it is set after the variable "${S}" is set. "DOTNET_PKG_PROJECTS" can integrate with "S" (see the example below).

Example:

SRC_URI="..."
S="${WORKDIR}/${P}/src"

LICENSE="MIT"
SLOT="0"
KEYWORDS="~amd64"

DOTNET_PKG_PROJECTS=( "${S}/DotnetProject" )

src_prepare() {
    ...
DOTNET_PKG_RESTORE_EXTRA_ARGS = ()

Extra arguments to pass to the package restore, in the "src_configure" phase.

This is passed only when restoring the specified "DOTNET_PROJECT". Other project restorers do not use this variable.

This variable should be set after inheriting "dotnet-pkg.eclass", it is also advised that it is set after the variable "DOTNET_PROJECT" (from "dotnet-pkg-base" eclass) is set.

Default value is an empty array.

For more info see the "DOTNET_PROJECT" variable and "dotnet-pkg_src_configure".

DOTNET_PKG_BUILD_EXTRA_ARGS = ()

Extra arguments to pass to the package build, in the "src_compile" phase.

This is passed only when building the specified "DOTNET_PROJECT". Other project builds do not use this variable.

This variable should be set after inheriting "dotnet-pkg.eclass", it is also advised that it is set after the variable "DOTNET_PROJECT" (from "dotnet-pkg-base" eclass) is set.

Default value is an empty array.

Example:

DOTNET_PKG_BUILD_EXTRA_ARGS=( -p:WarningLevel=0 )

For more info see the "DOTNET_PROJECT" variable and "dotnet-pkg_src_compile".

DOTNET_PKG_TEST_EXTRA_ARGS = ()

Extra arguments to pass to the package test, in the "src_test" phase.

This is passed only when testing found ".sln" solution files (see also "dotnet-pkg-base_foreach-solution"). Other project builds do not use this variable.

This variable should be set after inheriting "dotnet-pkg.eclass", it is also advised that it is set after the variable "DOTNET_PROJECT" (from "dotnet-pkg-base" eclass) is set.

Default value is an empty array.

Example:

DOTNET_PKG_TEST_EXTRA_ARGS=( -p:RollForward=Major )

For more info see the "DOTNET_PROJECT" variable and "dotnet-pkg_src_test".

Authors

Anna Figueiredo Gomes <navi@vlhl.dev>

Maciej Barć <xgqt@gentoo.org>

Maintainers

Gentoo Dotnet project <dotnet@gentoo.org>

Reporting Bugs

Please report bugs via https://bugs.gentoo.org/