docs: port the how-to/quickstart chapter from discourse (#5176)

Co-authored-by: Callahan <callahan.kovacs@canonical.com>
Co-authored-by: Alex Lowe <alex.lowe@canonical.com>

docs/howto/index.rst

@@ -6,6 +6,8 @@ How-to guides
 .. toctree::
    :maxdepth: 1
 
+   set-up-snapcraft
+   select-a-build-provider
    Craft for platforms <craft-for-platforms/index>
    architectures
    bases

docs/howto/select-a-build-provider.rst

@@ -0,0 +1,93 @@
+.. _select-a-build-provider:
+
+Select a build provider
+=======================
+
+Depending on the core version and platform, there are different default build
+providers and multiple ways to change providers. The following tables are
+ranked by precedence across cores, so for example a provider chosen by the
+first method overrides the second and third method, and so on.
+
+Consult the following tables for different methods of overriding the build
+provider.
+
+
+core22 and higher override methods
+----------------------------------
+
+For core22 and higher, LXD is the default provider on Linux, and Multipass is
+the default on macOS and Windows.
+
+.. list-table::
+  :header-rows: 1
+  :widths: 1 1 1
+
+  * - Provider override for core22 and higher
+    - Priority
+    - Command
+  * - Command-line argument
+    - 1
+    - ``--use-lxd``
+  * - Environmental variable
+    - 2
+    - ``SNAPCRAFT_BUILD_ENVIRONMENT=<provider-name>``
+  * - Snap configuration of Snapcraft
+    - 3
+    - ``snap set snapcraft provider=<provider-name>``
+
+
+core20 override methods
+-----------------------
+
+For core20, Multipass is the default provider on all platforms.
+
+.. list-table::
+  :header-rows: 1
+  :widths: 1 1 1
+
+  * - Provider override for core20
+    - Priority
+    - Command
+  * - Command-line argument
+    - 1
+    - ``--provider=<provider-name>``
+  * - Environmental variable
+    - 2
+    - ``SNAPCRAFT_BUILD_ENVIRONMENT=<provider-name>``
+  * - Command-line argument
+    - 3
+    - ``--use-lxd``
+  * - Snap configuration of Snapcraft
+    - 4
+    - ``snap set snapcraft provider=<provider-name>``
+
+
+Select through the snap configuration
+-------------------------------------
+
+The snap configuration method mentioned in the previous sections is a `feature
+of snapd <https://snapcraft.io/docs/configuration-in-snaps>`_.
+
+Like most snaps, Snapcraft isn't installed with any default configuration
+values. As a result, you won't be able to check the provider programmatically
+if you haven't already set it on the system.
+
+To set the provider, run:
+
+.. code:: bash
+
+  snap set snapcraft provider=<provider-name>
+
+Where ``<provider-name>`` can be ``lxd`` or ``multipass``.
+
+To check the provider after it's been set, run:
+
+.. code:: bash
+
+  snap get snapcraft provider
+
+To unset the provider, run:
+
+.. code:: bash
+
+  snap unset snapcraft provider

docs/howto/set-up-snapcraft.rst

@@ -0,0 +1,185 @@
+.. _install-snapcraft:
+
+Set up Snapcraft
+================
+
+Snapcraft can be installed on all popular Linux distributions with systemd,
+macOS, and Windows.
+
+Before you begin installation and setup, make sure your system meets the
+:ref:`system requirements <system-requirements>`.
+
+
+Install the main components
+---------------------------
+
+A working Snapcraft setup has two components -- Snapcraft itself, and a build
+provider.
+
+
+Install Snapcraft
+~~~~~~~~~~~~~~~~~
+
+.. tabs::
+
+  .. group-tab:: Linux
+
+    If your Linux distribution has snapd installed, the easiest way to install
+    Snapcraft is from the Snap Store:
+
+    .. code:: bash
+
+      sudo snap install snapcraft --classic
+
+
+  .. group-tab:: macOS
+
+    #. `Install Brew <https://brew.sh#install>`_.
+    #. Install Snapcraft:
+
+       .. code:: bash
+
+        brew install snapcraft
+
+  .. group-tab:: Windows
+
+    #. `Install WSL2 with Ubuntu 20.04 or higher
+       <https://learn.microsoft.com/en-us/windows/wsl/install#install-wsl-command>`_.
+    #. In WSL2, install Snapcraft:
+
+       .. code:: bash
+
+         sudo snap install snapcraft
+
+
+Install a build provider
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Snapcraft is compatible with two build providers -- Multipass and LXD. It
+relies on a build provider to host an isolated build environment, like a
+sandbox. Inside this environment, software can be built and packaged as snaps
+without making potentially destructive changes to the host system.
+
+For **core22 and higher**, LXD is the default provider on Linux, and Multipass
+is the default on macOS and Windows.
+
+For **core20**, Multipass is the default provider on all platforms.
+
+
+Choose a build provider
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Before proceeding, you must choose a build provider.
+
+`Multipass <https://multipass.run>`_ creates and manages virtual machine (VM)
+build instances. It automates setup and teardown of cloud-style Ubuntu VMs. It
+can't be used reliably on platforms that don't support nested virtualization.
+For instance, it most likely won't itself run inside a VM.
+
+`LXD <https://linuxcontainers.org/lxd/introduction>`_ creates and manages Linux
+container images. It can operate inside VMs.
+
+If the default build provider isn't fit for your snap, you can
+:ref:`switch between them <select-a-build-provider>`.
+
+
+Install Multipass
+^^^^^^^^^^^^^^^^^
+
+If Multipass isn't installed, on first run Snapcraft will ask you'd like to
+automatically install and configure it. If you agree, it will walk you through
+installation.
+
+.. If Multipass isn't installed while running in a non-interactive mode
+.. (running from a CI/CD pipeline), snapcraft will log an error and exit.
+
+To install Multipass on its own, run:
+
+.. code:: bash
+
+  sudo snap install multipass
+
+.. tip::
+
+  With core20 snaps and Multipass, the default virtual machine is assigned 2
+  CPUs and 2GB of RAM. To extend the hardware capacity, you can set the
+  following environment variables to modify CPU and memory allocation, and
+  improve performance:
+
+  .. code:: bash
+
+    export SNAPCRAFT_BUILD_ENVIRONMENT_CPU=8
+    export SNAPCRAFT_BUILD_ENVIRONMENT_MEMORY=16G
+
+
+Install LXD
+^^^^^^^^^^^
+
+To install LXD:
+
+#. Install the app:
+
+   .. code:: bash
+
+     sudo snap install lxd
+
+#. Add your user account to the ``lxd`` group so you can access the tool's
+   resources:
+
+   .. code:: bash
+
+     sudo usermod -a -G lxd $USER
+
+#. Log out and back in to your account for the new group to become
+   active. Then, check that you're a member of the group by running:
+
+   .. code:: bash
+
+     groups $USER
+
+   ``lxd`` should be present in the output.
+
+#. Finally, initialise LXD with a lightweight, default configuration:
+
+   .. code:: bash
+
+     lxd init --minimal
+
+See `How to install LXD
+<https://documentation.ubuntu.com/lxd/en/latest/installing/#installing>`_ in
+the LXD documentation for further installation options and troubleshooting.
+
+
+Install multiple instances of Snapcraft
+---------------------------------------
+
+If you're installing Snapcraft as a snap, you can install multiple concurrent
+versions at the same time. Doing so could come in handy if you want to test new
+features in your snaps, before they arrive in a mainstream release.
+
+To install another instance of Snapcraft:
+
+#. Enable parallel installs in snapd:
+
+   .. code:: bash
+
+     sudo snap set system experimental.parallel-instances=true
+
+#. List all the available versions of Snapcraft. For the version you're
+   interested in, take note of the value in the channel column.
+
+   .. code:: bash
+
+     sudo snap info snapcraft
+
+#. Install Snapcraft using the `instance key naming
+   <https://snapcraft.io/docs/parallel-installs#heading--naming>`_ syntax.
+   Replace ``edge`` with whichever name is appropriate for the instance, and
+   ``latest/edge`` with the target channel and track:
+
+   .. code:: bash
+
+     sudo snap install snapcraft_edge latest/edge --classic
+
+Whenever you want to run this parallel version of Snapcraft, invoke the
+instance name of the command -- in this example, ``snapcraft_edge``.