From 831814bee237e9496ef5521173d00b617889897e Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Mon, 8 Jul 2024 10:52:38 -0500 Subject: [PATCH 1/6] docs: import bases documentation from snapcraft.io/docs/base-snaps Signed-off-by: Callahan Kovacs --- docs/reference/bases.rst | 196 +++++++++++++++++++++++++++++++++++++++ docs/reference/index.rst | 1 + 2 files changed, 197 insertions(+) create mode 100644 docs/reference/bases.rst diff --git a/docs/reference/bases.rst b/docs/reference/bases.rst new file mode 100644 index 0000000000..e0a4cf43ac --- /dev/null +++ b/docs/reference/bases.rst @@ -0,0 +1,196 @@ +Bases +===== + +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. + +Supported base snaps +-------------------- + +There are currently six supported bases: + +* `core24`_: the newest base, built from `Ubuntu 24.04 LTS`_. +* `core22`_: built from `Ubuntu 22.04 LTS`_. +* `core20`_: built from `Ubuntu 20.04 LTS`_. +* `core18`_: the previous standard base for snap building, based on `Ubuntu + 18.04 LTS`_. +* `core`_: based on `Ubuntu 16.04 ESM`_, not to be confused with core16 (see + below). +* `bare`_: an empty base that’s useful with fully statically linked snaps and + when testing. + +Older releases of core were occasionally referred to as *core 16*, but ``core`` +and ``core16`` are now two distinct packages. + +In most Ubuntu bases (except ``core``), snapd and its associated tools are +provided by their relevant snaps. + +.. warning:: + + `core16`_ should no longer be used. With no current stable release, its beta + and candidate releases are classed as experimental, and packages previously + using it should be moved to a more recent base. + +Defining a base +--------------- + +Bases are defined by adding the base keyword to a snap’s `snapcraft.yaml`_ +followed by the base name. + +For example, to specify core20, use the following: + +.. code-block:: yaml + + base: core20 + +To specify core22, use the following: + +.. code-block:: yaml + + base: core22 + +Deprecated base snaps +--------------------- + +The latest releases of Snapcraft do not support older bases. Prior major +Snapcraft releases are still supported and can be installed from Snapcraft’s +`tracks`_. + +``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 + +For snaps using ``core``, we highly recommend reading `Snapcraft and ESM`_ for +essential support details. + +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. + +.. warning:: + + Compatibility mode and ESM Support + + When building a snap with no specified base, `Snapcraft`_ will operate in + compatibility mode. This is essentially a prior (2.43-era) version of + Snapcraft and, consequently, snapcraft will lose the functionality of newer + releases. See `Snapcraft 3`_ release notes for details. + + This compatibility mode is no longer supported starting in Snapcraft 5.0. + Snapcraft 4 can be installed from the 4.x track on the Snap Store (``snap + install snapcraft --channel 4.x``). See `Snapcraft and ESM`_ for essential + support details. + +Choosing a base +--------------- + +``core22`` is the currently recommended base for the majority of snaps. But +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 with ``core22`` then ``core20`` is a valid and supported +alternative. + +Snapcraft `extensions`_ are a great way to easily bundle a set of common +requirements into a snap, such as for running KDE Plasma or GNOME applications, +but you need to select a base that’s supported by the extension you require. +See `supported extensions`_ for a list of which extensions support which bases. + +Base support was added with the release of `Snapcraft 3`_. As noted above, +snaps created before this, and snaps not using the base: keyword, can still be +built but they cannot use specific new features. Instead, snaps built without +bases inherit attributes from their respective build environments. + +Snaps that don’t use bases can often migrate to one without too much +difficulty. See `upgrading snapcraft`_ for more details on potential +differences. + +Building a base snap +-------------------- + +While it is possible to build your own base snap, its publisher needs to take +responsibility for its 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 pro-active + +Base snaps can be either bootable or non-bootable. The former needs to include +systemd while the latter can be leaner. + +build-base +---------- + +The ``base`` keyword on its own does not take into account the creation of +bases. Instead, with older versions of snapcraft, the ``name`` keyword was +arbitrarily used to determine the build environment: + +.. code-block:: yaml + + name: core18 + type: base + # base: is not set elsewhere + +The above example uses ``name`` to specify the creation of an Ubuntu 18.04 +(``core18``) based build environment. + +But the above fails if a base has yet to be bootstrapped, or is otherwise +unavailable. For example, the following will currently generate a ``launch +failed: Unable to find an image matching “futurecore”`` error: + +.. code-block:: yaml + + name: futurecore + type: base + # base: is not set elsewhere + +In snapcraft 7 and newer, a ``build-base`` keyword can be used to explicitly +define the base to use for the build environment where the base has not yet +been bootstrapped. + +To solve the above issue, for example, use the following: + +.. code-block:: yaml + + name: futurecore + type: base + build-base: core24 + # base: is not set elsewhere + + +.. _`Snapcraft 3`: https://snapcraft.io/docs/release-notes-snapcraft-3-0 +.. _`Snapcraft and ESM`: https://snapcraft.io/docs/snapcraft-esm +.. _`Ubuntu 16.04 ESM`: https://releases.ubuntu.com/16.04/ +.. _`Ubuntu 18.04 LTS`: 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 +.. _`extensions`: https://snapcraft.io/docs/snapcraft-extensions +.. _`snapcraft.yaml`: https://snapcraft.io/docs/snapcraft-schema +.. _`supported extensions`: https://snapcraft.io/docs/supported-extensions +.. _`tracks`: https://snapcraft.io/docs/channels#heading--tracks +.. _`upgrading snapcraft`: https://snapcraft.io/docs/upgrading-snapcraft diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 5bafe6f180..8a9423bc7a 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -7,6 +7,7 @@ Reference :maxdepth: 1 architectures + bases commands plugins /common/craft-parts/reference/part_properties From 83f7d4a740ce08779e38bc01cc0bda3355d23c20 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Mon, 8 Jul 2024 17:19:18 -0500 Subject: [PATCH 2/6] docs: add explanation, reference, and how to for bases Signed-off-by: Callahan Kovacs --- docs/explanation/bases.rst | 71 ++++++++++++ docs/explanation/index.rst | 1 + docs/howto/bases.rst | 151 +++++++++++++++++++++++++ docs/howto/index.rst | 1 + docs/reference/bases.rst | 226 ++++++++++++------------------------- docs/reuse/bases-intro.rst | 3 + docs/reuse/links.txt | 2 +- 7 files changed, 300 insertions(+), 155 deletions(-) create mode 100644 docs/explanation/bases.rst create mode 100644 docs/howto/bases.rst create mode 100644 docs/reuse/bases-intro.rst diff --git a/docs/explanation/bases.rst b/docs/explanation/bases.rst new file mode 100644 index 0000000000..3f78bf3633 --- /dev/null +++ b/docs/explanation/bases.rst @@ -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 +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 +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 +environment. When an application runs, the base's library paths are searched +directly after the paths for that snap. + +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. + +.. _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. + + +.. _`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 diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 2368e0e3dd..3bd173c2c3 100644 --- a/docs/explanation/index.rst +++ b/docs/explanation/index.rst @@ -7,6 +7,7 @@ Explanation :maxdepth: 1 architectures + bases remote-build /common/craft-parts/explanation/filesets /common/craft-parts/explanation/parts diff --git a/docs/howto/bases.rst b/docs/howto/bases.rst new file mode 100644 index 0000000000..2de92030c5 --- /dev/null +++ b/docs/howto/bases.rst @@ -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` 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 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 diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 5800799951..89ac06e815 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -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 diff --git a/docs/reference/bases.rst b/docs/reference/bases.rst index e0a4cf43ac..1a95460b0d 100644 --- a/docs/reference/bases.rst +++ b/docs/reference/bases.rst @@ -1,184 +1,106 @@ Bases ===== -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. - -Supported base snaps --------------------- - -There are currently six supported bases: - -* `core24`_: the newest base, built from `Ubuntu 24.04 LTS`_. -* `core22`_: built from `Ubuntu 22.04 LTS`_. -* `core20`_: built from `Ubuntu 20.04 LTS`_. -* `core18`_: the previous standard base for snap building, based on `Ubuntu - 18.04 LTS`_. -* `core`_: based on `Ubuntu 16.04 ESM`_, not to be confused with core16 (see - below). -* `bare`_: an empty base that’s useful with fully statically linked snaps and - when testing. +.. include:: /reuse/bases-intro.rst -Older releases of core were occasionally referred to as *core 16*, but ``core`` -and ``core16`` are now two distinct packages. - -In most Ubuntu bases (except ``core``), snapd and its associated tools are -provided by their relevant snaps. - -.. warning:: - - `core16`_ should no longer be used. With no current stable release, its beta - and candidate releases are classed as experimental, and packages previously - using it should be moved to a more recent base. - -Defining a base ---------------- - -Bases are defined by adding the base keyword to a snap’s `snapcraft.yaml`_ -followed by the base name. - -For example, to specify core20, use the following: - -.. code-block:: yaml - - base: core20 - -To specify core22, use the following: - -.. code-block:: yaml - - base: core22 - -Deprecated base snaps ---------------------- - -The latest releases of Snapcraft do not support older bases. Prior major -Snapcraft releases are still supported and can be installed from Snapcraft’s -`tracks`_. +.. _base-snap-reference: -``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 +Base snaps +---------- -For snaps using ``core``, we highly recommend reading `Snapcraft and ESM`_ for -essential support details. +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 -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. +Older releases of core were occasionally referred to as *core 16*, but ``core`` +and ``core16`` are two distinct packages. .. warning:: - Compatibility mode and ESM Support - - When building a snap with no specified base, `Snapcraft`_ will operate in - compatibility mode. This is essentially a prior (2.43-era) version of - Snapcraft and, consequently, snapcraft will lose the functionality of newer - releases. See `Snapcraft 3`_ release notes for details. - - This compatibility mode is no longer supported starting in Snapcraft 5.0. - Snapcraft 4 can be installed from the 4.x track on the Snap Store (``snap - install snapcraft --channel 4.x``). See `Snapcraft and ESM`_ for essential - support details. - -Choosing a base ---------------- + `core16`_ is not a supported base. With no stable release, its beta and + candidate releases are classed as experimental. -``core22`` is the currently recommended base for the majority of snaps. But -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 with ``core22`` then ``core20`` is a valid and supported -alternative. +See `Snapcraft and ESM`_ for details bases built from ESM releases. -Snapcraft `extensions`_ are a great way to easily bundle a set of common -requirements into a snap, such as for running KDE Plasma or GNOME applications, -but you need to select a base that’s supported by the extension you require. -See `supported extensions`_ for a list of which extensions support which bases. +``base`` +-------- -Base support was added with the release of `Snapcraft 3`_. As noted above, -snaps created before this, and snaps not using the base: keyword, can still be -built but they cannot use specific new features. Instead, snaps built without -bases inherit attributes from their respective build environments. +The ``base`` keyword in a ``snapcraft.yaml`` file: -Snaps that don’t use bases can often migrate to one without too much -difficulty. See `upgrading snapcraft`_ for more details on potential -differences. +* 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 -Building a base snap --------------------- +``base`` must be defined except for base and snapd snaps. -While it is possible to build your own base snap, its publisher needs to take -responsibility for its maintenance and updates. In particular: +``base`` must be a :ref:`supported base`. -* 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 pro-active - -Base snaps can be either bootable or non-bootable. The former needs to include -systemd while the latter can be leaner. - -build-base ----------- +``build-base`` +-------------- -The ``base`` keyword on its own does not take into account the creation of -bases. Instead, with older versions of snapcraft, the ``name`` keyword was -arbitrarily used to determine the build environment: +The ``build-base`` keyword defines the environment where the snap will be +built. -.. code-block:: yaml +``build-base`` can only be defined for the following scenarios: - name: core18 - type: base - # base: is not set elsewhere +Bare base snaps +^^^^^^^^^^^^^^^ -The above example uses ``name`` to specify the creation of an Ubuntu 18.04 -(``core18``) based build environment. +``build-base`` must be a :ref:`supported base` when +``base: bare`` is defined. -But the above fails if a base has yet to be bootstrapped, or is otherwise -unavailable. For example, the following will currently generate a ``launch -failed: Unable to find an image matching “futurecore”`` error: +Devel builds +^^^^^^^^^^^^ -.. code-block:: yaml +``build-base`` must be ``devel`` must be defined when ``base`` is unstable. - name: futurecore - type: base - # base: is not set elsewhere +*Unstable* means that the base snap has not been released to the ``stable`` +channel. -In snapcraft 7 and newer, a ``build-base`` keyword can be used to explicitly -define the base to use for the build environment where the base has not yet -been bootstrapped. +Snaps with a ``devel`` build base must have a ``grade`` of ``devel`` and cannot +be promoted to ``stable`` or ``candidate`` channels. -To solve the above issue, for example, use the following: +Kernel snaps +^^^^^^^^^^^^ -.. code-block:: yaml +``build-base`` must be defined as ``@`` when ``type: +kernel`` is defined. - name: futurecore - type: base - build-base: core24 - # base: is not set elsewhere +```` is ``ubuntu`` and ```` is any `supported LTS or +interim release`_. +See :ref:`How to build a kernel snap for interim releases` +for details on how to use ``build-base`` for kernel snaps. -.. _`Snapcraft 3`: https://snapcraft.io/docs/release-notes-snapcraft-3-0 .. _`Snapcraft and ESM`: https://snapcraft.io/docs/snapcraft-esm .. _`Ubuntu 16.04 ESM`: https://releases.ubuntu.com/16.04/ -.. _`Ubuntu 18.04 LTS`: https://releases.ubuntu.com/18.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/ @@ -189,8 +111,4 @@ To solve the above issue, for example, use the following: .. _`core22`: https://snapcraft.io/core22 .. _`core24`: https://snapcraft.io/core24 .. _`core`: https://snapcraft.io/core -.. _`extensions`: https://snapcraft.io/docs/snapcraft-extensions -.. _`snapcraft.yaml`: https://snapcraft.io/docs/snapcraft-schema -.. _`supported extensions`: https://snapcraft.io/docs/supported-extensions -.. _`tracks`: https://snapcraft.io/docs/channels#heading--tracks -.. _`upgrading snapcraft`: https://snapcraft.io/docs/upgrading-snapcraft +.. _`supported LTS or interim release`: https://ubuntu.com/about/release-cycle diff --git a/docs/reuse/bases-intro.rst b/docs/reuse/bases-intro.rst new file mode 100644 index 0000000000..78c84932f3 --- /dev/null +++ b/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. diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt index a299bf6a1f..dfa7b132db 100644 --- a/docs/reuse/links.txt +++ b/docs/reuse/links.txt @@ -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 @@ -18,4 +19,3 @@ .. _`Ubuntu Core`: https://ubuntu.com/core/ .. _vscode: https://code.visualstudio.com/ .. _`YAML specification`: https://yaml.org/spec/ - From 92822563456d1b73a59c58a24fc79fffc2a9fe2a Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Wed, 10 Jul 2024 14:52:44 -0500 Subject: [PATCH 3/6] chore: feedback from pr Signed-off-by: Callahan Kovacs --- docs/explanation/bases.rst | 23 ++++++++++++++++++----- docs/howto/bases.rst | 31 ++++++++++++++++++++++++------- docs/reference/bases.rst | 10 +++++++--- 3 files changed, 49 insertions(+), 15 deletions(-) diff --git a/docs/explanation/bases.rst b/docs/explanation/bases.rst index 3f78bf3633..e131bc53b4 100644 --- a/docs/explanation/bases.rst +++ b/docs/explanation/bases.rst @@ -20,6 +20,9 @@ with the ``core24`` snap installed. Stage packages will be installed from the 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 ---------- @@ -31,9 +34,13 @@ a snap. Mounting -------- -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 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. Classic snaps can +still load libraries from the base snaps under ``/snap//``. For more +information, see the documentation for `classic confinement`_. Choosing a base --------------- @@ -49,6 +56,11 @@ 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 @@ -62,10 +74,11 @@ for maintenance and updates, in particular: 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. +`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 diff --git a/docs/howto/bases.rst b/docs/howto/bases.rst index 2de92030c5..5259025d1a 100644 --- a/docs/howto/bases.rst +++ b/docs/howto/bases.rst @@ -40,7 +40,7 @@ To build ``core18`` snaps, install snapcraft 7 from the *7.x* track: .. code-block:: shell - $ snap install snapcraft --channel 7.x + snap install snapcraft --channel 7.x ``core`` ^^^^^^^^ @@ -49,7 +49,7 @@ To build ``core`` snaps, install snapcraft 4 from the *4.x* track: .. code-block:: shell - $ snap install snapcraft --channel 4.x + snap install snapcraft --channel 4.x The base snap mounts itself as the root filesystem within your snap such that @@ -71,8 +71,8 @@ require re-downloading Snapcraft. .. code-block:: shell - $ snap refresh snapcraft --channel 7.x - $ snap refresh snapcraft --channel 8.x + snap refresh snapcraft --channel 7.x + snap refresh snapcraft --channel 8.x Parallel installs ^^^^^^^^^^^^^^^^^ @@ -83,9 +83,9 @@ details. .. code-block:: shell - $ snap install snapcraft snapcraft_7 --channel 7.x - $ snap install snapcraft snapcraft_8 --channel 8.x - $ snapcraft_8 pack + snap install snapcraft snapcraft_7 --channel 7.x + snap install snapcraft snapcraft_8 --channel 8.x + snapcraft_8 pack Containers ^^^^^^^^^^ @@ -143,6 +143,23 @@ This snippet will do the following: * build the snap inside an Ubuntu 24.10 build environment * use the ``core24`` 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 diff --git a/docs/reference/bases.rst b/docs/reference/bases.rst index 1a95460b0d..b83bf6c953 100644 --- a/docs/reference/bases.rst +++ b/docs/reference/bases.rst @@ -57,7 +57,7 @@ The ``base`` keyword in a ``snapcraft.yaml`` file: * 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. +``base`` must be defined except for base, snapd, and kernel snaps. ``base`` must be a :ref:`supported base`. @@ -89,12 +89,16 @@ be promoted to ``stable`` or ``candidate`` channels. Kernel snaps ^^^^^^^^^^^^ -``build-base`` must be defined as ``@`` when ``type: -kernel`` is defined. +Kernel snaps can optionally define a base and can use interim build bases. +Interim build bases are defined as ``@`` where ```` is ``ubuntu`` and ```` is any `supported LTS or interim release`_. +If the build base uses the ``@`` naming convention, then +``base`` must be a :ref:`supported base` so that Snapcraft +can determine the correct featureset and ``snapcraft.yaml`` schema. + See :ref:`How to build a kernel snap for interim releases` for details on how to use ``build-base`` for kernel snaps. From 50fb752aa6de6a9c75e3de583fd00b0062ea0275 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Fri, 12 Jul 2024 09:00:43 -0500 Subject: [PATCH 4/6] chore: document current behavior of baseless kernel snaps Signed-off-by: Callahan Kovacs --- docs/howto/bases.rst | 17 ++++++++--------- docs/reference/bases.rst | 15 ++++----------- 2 files changed, 12 insertions(+), 20 deletions(-) diff --git a/docs/howto/bases.rst b/docs/howto/bases.rst index 5259025d1a..b71738ea72 100644 --- a/docs/howto/bases.rst +++ b/docs/howto/bases.rst @@ -121,27 +121,26 @@ This snippet will do the following: .. _kernel-snap-how-to: -How to build a kernel snap for interim releases ------------------------------------------------ +How to build a kernel snap +-------------------------- -The ``build-base`` keyword is used to build kernel snaps for interim Ubuntu +The ``build-base`` keyword is used to build kernel snaps for Ubuntu LTS releases. -To build a kernel snap targeting the Ubuntu 24.10 release, use the following +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 - base: core24 - build-base: ubuntu@24.10 + build-base: core22 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 +* 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 ----------------------------- diff --git a/docs/reference/bases.rst b/docs/reference/bases.rst index b83bf6c953..2364ad6683 100644 --- a/docs/reference/bases.rst +++ b/docs/reference/bases.rst @@ -89,18 +89,11 @@ be promoted to ``stable`` or ``candidate`` channels. Kernel snaps ^^^^^^^^^^^^ -Kernel snaps can optionally define a base and can use interim build bases. - -Interim build bases are defined as ``@`` where -```` is ``ubuntu`` and ```` is any `supported LTS or -interim release`_. - -If the build base uses the ``@`` naming convention, then -``base`` must be a :ref:`supported base` so that Snapcraft -can determine the correct featureset and ``snapcraft.yaml`` schema. +``build-base`` must be a :ref:`supported base` when +``type: kernel`` is defined. -See :ref:`How to build a kernel snap for interim releases` -for details on how to use ``build-base`` for kernel snaps. +See :ref:`How to build a kernel snap` 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/ From ca1be2fa2d17c0b849705aafe339383c31572093 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Fri, 12 Jul 2024 14:55:42 -0500 Subject: [PATCH 5/6] docs: feedback from PR Signed-off-by: Callahan Kovacs --- docs/explanation/bases.rst | 7 ++++--- docs/howto/bases.rst | 2 +- docs/reference/bases.rst | 3 +-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/explanation/bases.rst b/docs/explanation/bases.rst index e131bc53b4..0eef15a419 100644 --- a/docs/explanation/bases.rst +++ b/docs/explanation/bases.rst @@ -38,9 +38,10 @@ 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. Classic snaps can -still load libraries from the base snaps under ``/snap//``. For more -information, see the documentation for `classic confinement`_. +For classic confined snaps, the base snap is not mounted as the root +filesystem. The base snap is mounted like as ``/snap//``, so the snap can +still load libraries from the base snap. For more information, see the +documentation for `classic confinement`_. Choosing a base --------------- diff --git a/docs/howto/bases.rst b/docs/howto/bases.rst index b71738ea72..75da3750c0 100644 --- a/docs/howto/bases.rst +++ b/docs/howto/bases.rst @@ -93,7 +93,7 @@ Containers Isolated development environments allow using different versions of Snapcraft simultaneously. -`Snapcraft rocks`_ are the recommended way to build snaps in a container: +`Snapcraft rocks`_ are the recommended way to build snaps in a container. How to bootstrap a base snap diff --git a/docs/reference/bases.rst b/docs/reference/bases.rst index 2364ad6683..b25cc6ce9c 100644 --- a/docs/reference/bases.rst +++ b/docs/reference/bases.rst @@ -42,7 +42,7 @@ and ``core16`` are two distinct packages. .. warning:: - `core16`_ is not a supported base. With no stable release, its beta and + 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. @@ -102,7 +102,6 @@ use ``build-base`` for kernel snaps. .. _`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 From 92c6da21388383b447e2a60f74cba6e7984e046a Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Fri, 12 Jul 2024 15:01:50 -0500 Subject: [PATCH 6/6] docs: feedback from PR Signed-off-by: Callahan Kovacs --- docs/explanation/bases.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/bases.rst b/docs/explanation/bases.rst index 0eef15a419..ed438272a5 100644 --- a/docs/explanation/bases.rst +++ b/docs/explanation/bases.rst @@ -39,7 +39,7 @@ 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 like as ``/snap//``, so the snap can +filesystem. The base snap is mounted as ``/snap//``, so the snap can still load libraries from the base snap. For more information, see the documentation for `classic confinement`_.