Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 9 commits into from
Jul 15, 2024
71 changes: 71 additions & 0 deletions docs/explanation/bases.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
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
mr-cal marked this conversation as resolved.
Show resolved Hide resolved
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`_.

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
mr-cal marked this conversation as resolved.
Show resolved Hide resolved
transparent to users, but they need to be considered and specified when building
a snap.

Mounting
--------

The base snap mounts itself as the root filesystem within a snap's runtime
mr-cal marked this conversation as resolved.
Show resolved Hide resolved
environment. When an application runs, the base's library paths are searched
directly after the paths for that snap.

Choosing a base
mr-cal marked this conversation as resolved.
Show resolved Hide resolved
---------------

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

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

Base snaps can be either bootable or non-bootable. The former needs to include
``systemd`` while the latter can be leaner.
mr-cal marked this conversation as resolved.
Show resolved Hide resolved


.. _`Ubuntu buildd image server`: https://cloud-images.ubuntu.com/buildd/daily/
.. _`extensions`: https://snapcraft.io/docs/snapcraft-extensions
.. _`supported extensions`: https://snapcraft.io/docs/supported-extensions
1 change: 1 addition & 0 deletions docs/explanation/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Explanation
:maxdepth: 1

architectures
bases
remote-build
/common/craft-parts/explanation/filesets
/common/craft-parts/explanation/parts
Expand Down
151 changes: 151 additions & 0 deletions docs/howto/bases.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
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
mr-cal marked this conversation as resolved.
Show resolved Hide resolved

``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:
mr-cal marked this conversation as resolved.
Show resolved Hide resolved


How to bootstrap a base snap
mr-cal marked this conversation as resolved.
Show resolved Hide resolved
----------------------------

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 for interim releases
-----------------------------------------------

The ``build-base`` keyword is used to build kernel snaps for interim Ubuntu
releases.

To build a kernel snap targeting the Ubuntu 24.10 release, use the following
``snapcraft.yaml`` snippet:

.. code-block:: yaml

name: pc-kernel
type: kernel
base: core24
build-base: ubuntu@24.10

This snippet will do the following:

* create a kernel snap for Ubuntu 24.10
* build the snap inside an Ubuntu 24.10 build environment
* use the ``core24`` feature set and ``snapcraft.yaml`` schema


.. _`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
1 change: 1 addition & 0 deletions docs/howto/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,5 +7,6 @@ How-to guides
:maxdepth: 1

architectures
bases
/common/craft-parts/how-to/include_files
/common/craft-parts/how-to/override_build
114 changes: 114 additions & 0 deletions docs/reference/bases.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
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
mr-cal marked this conversation as resolved.
Show resolved Hide resolved
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 and snapd snaps.
mr-cal marked this conversation as resolved.
Show resolved Hide resolved

``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 defined as ``<distribution>@<series>`` when ``type:
kernel`` is defined.

``<distribution>`` is ``ubuntu`` and ``<series>`` is any `supported LTS or
interim release`_.

See :ref:`How to build a kernel snap for interim releases<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
.. _`core16`: https://snapcraft.io/core16
.. _`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
1 change: 1 addition & 0 deletions docs/reference/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Reference
:maxdepth: 1

architectures
bases
commands
plugins
/common/craft-parts/reference/part_properties
Expand Down
3 changes: 3 additions & 0 deletions docs/reuse/bases-intro.rst
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion docs/reuse/links.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
.. _ROS: https://www.ros.org/
.. _setuptools: https://setuptools.readthedocs.io/en/latest/
.. _`Snapcraft`: https://snapcraft.io/docs/snapcraft
.. _`snapcraft.yaml`: https://snapcraft.io/docs/snapcraft-schema
.. _`snap-channels`: https://snapcraft.io/docs/channels
.. _`Snap Store desktop app`: https://snapcraft.io/snap-store
.. _`Snap Store`: https://snapcraft.io/store
Expand All @@ -18,4 +19,3 @@
.. _`Ubuntu Core`: https://ubuntu.com/core/
.. _vscode: https://code.visualstudio.com/
.. _`YAML specification`: https://yaml.org/spec/

Loading