docs: document the .NET plugin (#723)

docs/common/craft-parts/reference/plugins/dotnet_plugin.rst

@@ -0,0 +1,89 @@
+.. _craft_parts_dotnet_plugin:
+
+.NET plugin
+===========
+
+The ``dotnet`` plugin builds .NET projects using the ``dotnet`` tool.
+
+Keywords
+--------
+
+In addition to the common :ref:`plugin <part-properties-plugin>` and
+:ref:`sources <part-properties-sources>` keywords, this plugin provides the following
+plugin-specific keywords:
+
+dotnet-build-configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Type:** string
+
+The dotnet build configuration to use. The default value is ``"Release"``.
+
+dotnet-self-contained-runtime-identifier
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Type:** string
+
+Create a self contained .NET application using the specified Runtime Identifier.
+See the `Runtime Identifier catalogue`_ for a list of possible values. This
+property has no default value, meaning that it won't create self-contained
+executables unless set.
+
+
+.. _dotnet-details-begin:
+
+Dependencies
+------------
+
+The .NET plugin needs the ``dotnet`` executable to build programs but does not
+provision it by itself, to allow flexibility in the choice of compiler version.
+
+Some common means of providing ``dotnet`` are:
+
+* The ``dotnet8`` Ubuntu package, declared as a ``build-package``.
+* The ``dotnet-sdk`` snap, declared as a ``build-snap`` from the desired channel.
+
+Another alternative is to define another part with the name ``dotnet-deps``, and
+declare that the part using the ``dotnet`` plugin comes :ref:`after <after>` the
+``dotnet-deps`` part. In this case, the plugin will assume that this new part will
+stage the ``dotnet`` executable to be used in the build step. This can be useful,
+for example, in cases where a specific, unreleased version of ``dotnet`` is desired
+but unavailable as a snap or an Ubuntu package.
+
+Finally, whether the resulting built artefact will need the presence of the .NET
+runtime to execute depends on the value of the
+``dotnet-self-contained-runtime-identifier`` property: self-contained builds
+bundle the necessary portions of the runtime in the generated executable.
+
+.. _dotnet-details-end:
+
+How it works
+------------
+
+During the build step the plugin performs the following actions:
+
+* Call ``dotnet build -c <config>`` where ``<config>`` is the value of the
+  ``dotnet-build-configuration`` property.
+* Call ``dotnet publish`` to install the generated assets into ``${CRAFT_PART_INSTALL}``,
+  optionally passing the value of ``dotnet-self-contained-runtime-identifier`` if
+  set.
+
+
+Examples
+--------
+
+The following example uses the ``dotnet-sdk`` snap to build an application in
+``Debug`` configuration, generating assets that are self-contained to execute on
+``linux-x64`` environments.
+
+
+.. code-block:: yaml
+
+    parts:
+      my-dotnet-part:
+        source: .
+        plugin: dotnet
+        build-snaps: [dotnet-sdk]
+        dotnet-build-configuration: Debug
+        dotnet-self-contained-runtime-identifier: linux-x64
+
+
+.. _Runtime Identifier catalogue: https://learn.microsoft.com/en-us/dotnet/core/rid-catalog

docs/reference/plugins.rst

@@ -10,6 +10,7 @@ lifecycle.
 .. toctree::
    :maxdepth: 1
 
+   /common/craft-parts/reference/plugins/dotnet_plugin.rst
    /common/craft-parts/reference/plugins/autotools_plugin.rst
    /common/craft-parts/reference/plugins/cmake_plugin.rst
    /common/craft-parts/reference/plugins/dump_plugin.rst