docs: add explanation, reference, and how to for bases (#4900)

Signed-off-by: Callahan Kovacs <callahan.kovacs@canonical.com>

docs/explanation/bases.rst

@@ -0,0 +1,85 @@
+Bases
+=====
+
+.. include:: /reuse/bases-intro.rst
+
+``base`` and ``build-base``
+---------------------------
+
+If ``build-base`` is defined , then the ``build-base`` will determine the
+environment where the snap is built.
+
+If ``build-base`` is not defined, the ``base`` will determine the
+environment where the snap is built.
+
+For example, ``base: core24`` will build a snap in a Ubuntu 24.04 environment
+with the ``core24`` snap installed. Stage packages will be installed from the
+24.04 repository.
+
+``build-base: devel`` will build a snap using the upcoming Ubuntu release in
+development. This is defined as the Ubuntu image with the ``devel`` alias in
+the `Ubuntu buildd image server`_.
+
+For ``base: bare`` snaps, a ``build-base`` is required to determine the feature
+set, build environment, and ``snapcraft.yaml`` schema.
+
+Base snaps
+----------
+
+A base snap is a special kind of snap that provides a run-time environment with
+a cardinal set of libraries that are common to most applications. They’re
+transparent to users, but they need to be considered and specified when building
+a snap.
+
+Mounting
+--------
+
+For strictly confined snaps, the base snap mounts itself as the root filesystem
+within a snap's runtime environment. When an application runs, the base's
+library paths are searched directly after the paths for that snap.
+
+For classic confined snaps, the base snap is not mounted as the root
+filesystem. The base snap is mounted as ``/snap/<base>/``, so the snap can
+still load libraries from the base snap. For more information, see the
+documentation for `classic confinement`_.
+
+Choosing a base
+---------------
+
+``core24`` is the recommended base for most snaps. Much like choosing a
+distribution base for a project or server, the best base for an application is
+dependent on an application’s requirements and which plugins or extensions a
+base supports. If there are specific dependencies that cannot be easily met
+then the next newest base ``core22`` is a valid and supported alternative.
+
+Snapcraft `extensions`_ enable bundling a set of common requirements into a
+snap, such as for running KDE Plasma or GNOME applications. Extensions support
+specific bases. See `supported extensions`_ for a list of which extensions
+support which bases.
+
+``bare`` is the recommended base for fully statically linked snaps because they
+will not have access to a base snap when running. The snap will have a smaller
+footprint at runtime because it does not require a base snap to be downloaded,
+installed, and mounted.
+
+.. _base-snap-explanation:
+
+Building a base snap
+--------------------
+
+While uncommon, developers can build their own base snap. They are responsible
+for maintenance and updates, in particular:
+
+* bases need to be built from stable packages
+* ABI compatibility cannot broken (ie. never replace symbols or libraries, and
+  be strict)
+* security updates must be proactive
+
+`Ubuntu Core`_ systems need a base snap. These base snaps must be bootable and
+include ``systemd``.
+
+
+.. _`Ubuntu buildd image server`: https://cloud-images.ubuntu.com/buildd/daily/
+.. _`classic confinement`: https://snapcraft.io/docs/classic-confinement
+.. _`extensions`: https://snapcraft.io/docs/snapcraft-extensions
+.. _`supported extensions`: https://snapcraft.io/docs/supported-extensions

docs/explanation/index.rst

@@ -7,6 +7,7 @@ Explanation
    :maxdepth: 1
 
    architectures
+   bases
    components
    remote-build
    /common/craft-parts/explanation/filesets

docs/howto/bases.rst

@@ -0,0 +1,167 @@
+Bases
+=====
+
+.. include:: /reuse/bases-intro.rst
+
+How to use a base
+-----------------
+
+The base a snap will use is defined in the snap's `snapcraft.yaml`_.
+
+To use the ``core24`` base for a snap:
+
+.. code-block:: yaml
+
+   base: core24
+
+
+How to migrate to a newer base
+------------------------------
+
+See `migrating bases`_ for details on migrating to a newer base.
+
+
+How to use a deprecated base
+----------------------------
+
+The latest release of Snapcraft does not support older bases. Prior major
+Snapcraft releases are supported and can be installed from Snapcraft's
+`tracks`_.
+
+See :ref:`base snaps<base-snap-reference>` for a list of which Snapcraft
+major releases support a particular base.
+
+See `Snapcraft and ESM`_ for details on support for deprecated bases.
+
+``core18``
+^^^^^^^^^^
+
+To build ``core18`` snaps, install snapcraft 7 from the *7.x* track:
+
+.. code-block:: shell
+
+   snap install snapcraft --channel 7.x
+
+``core``
+^^^^^^^^
+
+To build ``core`` snaps, install snapcraft 4 from the *4.x* track:
+
+.. code-block:: shell
+
+   snap install snapcraft --channel 4.x
+
+
+The base snap mounts itself as the root filesystem within your snap such that
+when your application runs, the base’s library paths are searched directly
+after the paths for your specific snap.
+
+How to develop supported and deprecated bases
+---------------------------------------------
+
+When developing snaps using supported and deprecated bases at the same time,
+developers must use different versions of Snapcraft. There are a few options:
+
+Refresh channels
+^^^^^^^^^^^^^^^^
+
+Switch between Snapcraft releases by refreshing channels. ``snapd`` retains the
+previously installed snap, so refreshing between two channels should not
+require re-downloading Snapcraft.
+
+.. code-block:: shell
+
+   snap refresh snapcraft --channel 7.x
+   snap refresh snapcraft --channel 8.x
+
+Parallel installs
+^^^^^^^^^^^^^^^^^
+
+Multiple instances of Snapcraft can be installed via ``snapd``'s experimental
+parallel install feature. See the `Parallel installs`_ documentation for
+details.
+
+.. code-block:: shell
+
+   snap install snapcraft snapcraft_7 --channel 7.x
+   snap install snapcraft snapcraft_8 --channel 8.x
+   snapcraft_8 pack
+
+Containers
+^^^^^^^^^^
+
+Isolated development environments allow using different versions of Snapcraft
+simultaneously.
+
+`Snapcraft rocks`_ are the recommended way to build snaps in a container.
+
+
+How to bootstrap a base snap
+----------------------------
+
+The ``build-base`` keyword is used to bootstrap and create new bases.
+
+To bootstrap the ``core26`` base snap, use the following ``snapcraft.yaml``
+snippet:
+
+.. code-block:: yaml
+
+   name: core26
+   type: base
+   build-base: core24
+
+This snippet will do the following:
+
+* ``name: core26`` sets the snap's name to ``core26``.
+* ``type: base`` creates a base snap.
+* ``build-base: core24`` builds the snap inside an Ubuntu 24.04 build
+  environment.
+* ``base`` cannot be set in the ``snapcraft.yaml`` file
+
+
+.. _kernel-snap-how-to:
+
+How to build a kernel snap
+--------------------------
+
+The ``build-base`` keyword is used to build kernel snaps for Ubuntu LTS
+releases.
+
+To build a kernel snap targeting the Ubuntu 22.04 release, use the following
+``snapcraft.yaml`` snippet:
+
+.. code-block:: yaml
+
+   name: pc-kernel
+   type: kernel
+   build-base: core22
+
+This snippet will do the following:
+
+* create a kernel snap for Ubuntu 22.04
+* build the snap inside an Ubuntu 22.04 build environment
+* use the ``core22`` feature set and ``snapcraft.yaml`` schema
+
+How to build a bare base snap
+-----------------------------
+
+Bare base snaps are useful for fully statically linked applications and will
+not have access to a base snap at runtime.
+
+To build a bare base snap, use the following ``snapcraft.yaml`` snippet:
+
+.. code-block:: yaml
+
+   name: my-snap
+   base: bare
+   build-base: core24
+
+This snippet will build a bare base snap inside an Ubuntu 24.04 build
+environment.
+
+
+.. _`Snapcraft and ESM`: https://snapcraft.io/docs/snapcraft-esm
+.. _`Snapcraft rocks`: https://github.com/canonical/snapcraft-rocks
+.. _`migrating bases`: https://snapcraft.io/docs/migrating-bases
+.. _`parallel installs`: https://snapcraft.io/docs/parallel-installs
+.. _`tracks`: https://snapcraft.io/docs/channels#heading--tracks

docs/howto/index.rst

@@ -7,6 +7,7 @@ How-to guides
    :maxdepth: 1
 
    architectures
+   bases
    components
    /common/craft-parts/how-to/include_files
    /common/craft-parts/how-to/override_build

docs/reference/bases.rst

@@ -0,0 +1,110 @@
+Bases
+=====
+
+.. include:: /reuse/bases-intro.rst
+
+.. _base-snap-reference:
+
+Base snaps
+----------
+
+There are six supported base snaps:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Name
+     - Description
+     - Latest snapcraft track with support
+   * - `core24`_
+     - built from `Ubuntu 24.04 LTS`_
+     - 8.x
+   * - `core22`_
+     - built from `Ubuntu 22.04 LTS`_
+     - 8.x
+   * - `core20`_
+     - built from `Ubuntu 20.04 LTS`_
+     - 8.x
+   * - `core18`_
+     - built from `Ubuntu 18.04 ESM`_
+     - 7.x
+   * - `core`_
+     - built from `Ubuntu 16.04 ESM`_, not to be confused with core16 (see
+       below)
+     - 4.x
+   * - `bare`_
+     - an empty base that's useful with fully statically linked snaps and when
+       testing
+     - 8.x
+
+Older releases of core were occasionally referred to as *core 16*, but ``core``
+and ``core16`` are two distinct packages.
+
+.. warning::
+
+   core16 is not a supported base. With no stable release, its beta and
+   candidate releases are classed as experimental.
+
+See `Snapcraft and ESM`_ for details bases built from ESM releases.
+
+``base``
+--------
+
+The ``base`` keyword in a ``snapcraft.yaml`` file:
+
+* defines the feature set used by Snapcraft
+* the ``snapcraft.yaml`` schema
+* the environment where the snap is built if ``build-base`` is not defined
+* and which base snap is used at runtime
+
+``base`` must be defined except for base, snapd, and kernel snaps.
+
+``base`` must be a :ref:`supported base<base-snap-reference>`.
+
+``build-base``
+--------------
+
+The ``build-base`` keyword defines the environment where the snap will be
+built.
+
+``build-base`` can only be defined for the following scenarios:
+
+Bare base snaps
+^^^^^^^^^^^^^^^
+
+``build-base`` must be a :ref:`supported base<base-snap-reference>` when
+``base: bare`` is defined.
+
+Devel builds
+^^^^^^^^^^^^
+
+``build-base`` must be ``devel`` must be defined when ``base`` is unstable.
+
+*Unstable* means that the base snap has not been released to the ``stable``
+channel.
+
+Snaps with a ``devel`` build base must have a ``grade`` of ``devel`` and cannot
+be promoted to ``stable`` or ``candidate`` channels.
+
+Kernel snaps
+^^^^^^^^^^^^
+
+``build-base`` must be a :ref:`supported base<base-snap-reference>` when
+``type: kernel`` is defined.
+
+See :ref:`How to build a kernel snap<kernel-snap-how-to>` for details on how to
+use ``build-base`` for kernel snaps.
+
+.. _`Snapcraft and ESM`: https://snapcraft.io/docs/snapcraft-esm
+.. _`Ubuntu 16.04 ESM`: https://releases.ubuntu.com/16.04/
+.. _`Ubuntu 18.04 ESM`: https://releases.ubuntu.com/18.04/
+.. _`Ubuntu 20.04 LTS`: https://releases.ubuntu.com/20.04/
+.. _`Ubuntu 22.04 LTS`: https://releases.ubuntu.com/22.04/
+.. _`Ubuntu 24.04 LTS`: https://releases.ubuntu.com/24.04/
+.. _`bare`: https://snapcraft.io/bare
+.. _`core18`: https://snapcraft.io/core18
+.. _`core20`: https://snapcraft.io/core20
+.. _`core22`: https://snapcraft.io/core22
+.. _`core24`: https://snapcraft.io/core24
+.. _`core`: https://snapcraft.io/core
+.. _`supported LTS or interim release`: https://ubuntu.com/about/release-cycle

docs/reference/index.rst

@@ -7,6 +7,7 @@ Reference
    :maxdepth: 1
 
    architectures
+   bases
    commands
    components
    plugins

docs/reuse/bases-intro.rst

@@ -0,0 +1,3 @@
+Snaps declare a base in their `snapcraft.yaml`_ file. The base defines the
+feature set used by `Snapcraft`_, the snapcraft.yaml schema, the environment
+where the snap is built, and which base snap is used at runtime.