From a7145f74de40e2674f1ac63121ecd28d7192217f Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Mon, 9 Dec 2024 10:49:20 -0800 Subject: [PATCH 1/8] docs: port the how-to/quickstart chapter from discourse --- docs/howto/index.rst | 2 + docs/howto/select-a-build-provider.rst | 88 ++++++ docs/howto/set-up-snapcraft.rst | 211 +++++++++++++ docs/reference/anatomy-of-a-recipe.rst | 329 +++++++++++++++++++++ docs/reference/channels.rst | 61 ++++ docs/reference/code/wethr-recipe.yaml | 44 +++ docs/reference/code/yt-dlp-recipe.yaml | 22 ++ docs/reference/index.rst | 10 +- docs/reference/snap-build-process.rst | 131 ++++++++ docs/reference/snap-publishing-process.rst | 17 ++ docs/reference/system-requirements.rst | 41 +++ 11 files changed, 954 insertions(+), 2 deletions(-) create mode 100644 docs/howto/select-a-build-provider.rst create mode 100644 docs/howto/set-up-snapcraft.rst create mode 100644 docs/reference/anatomy-of-a-recipe.rst create mode 100644 docs/reference/channels.rst create mode 100644 docs/reference/code/wethr-recipe.yaml create mode 100644 docs/reference/code/yt-dlp-recipe.yaml create mode 100644 docs/reference/snap-build-process.rst create mode 100644 docs/reference/snap-publishing-process.rst create mode 100644 docs/reference/system-requirements.rst diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 28e464ffec..7109734511 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -6,6 +6,8 @@ How-to guides .. toctree:: :maxdepth: 1 + set-up-snapcraft + select-a-build-provider Craft for platforms architectures bases diff --git a/docs/howto/select-a-build-provider.rst b/docs/howto/select-a-build-provider.rst new file mode 100644 index 0000000000..4b0a96d320 --- /dev/null +++ b/docs/howto/select-a-build-provider.rst @@ -0,0 +1,88 @@ +.. _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 override methods +----------------------- + +.. 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=`` + * - Snap configuration of Snapcraft + - 3 + - ``snap set snapcraft provider=`` + + +core20 override methods +----------------------- + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Provider override for core20 + - Priority + - Command + * - Command-line argument + - 1 + - ``--provider=`` + * - Environmental variable + - 2 + - ``SNAPCRAFT_BUILD_ENVIRONMENT=`` + * - Command-line argument + - 3 + - ``--use-lxd`` + * - Snap configuration of Snapcraft + - 4 + - ``snap set snapcraft provider=`` + + +Select through the Snapcraft configuration +------------------------------------------ + +The snap configuration method mentioned in the previous sections is a feature +of snapd. + +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= + +Where ```` 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 diff --git a/docs/howto/set-up-snapcraft.rst b/docs/howto/set-up-snapcraft.rst new file mode 100644 index 0000000000..dd176e62ce --- /dev/null +++ b/docs/howto/set-up-snapcraft.rst @@ -0,0 +1,211 @@ +.. _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 `. + + +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 + + If your distribution lacks snapd or access to the Snap Store, but has + access to the Ubuntu or Debian package repository, you can install + Snapcraft as a deb package: + + .. code:: bash + + sudo apt install snapcraft + + .. group-tab:: macOS + + #. `Install Brew `_. + #. Install Snapcraft: + + .. code:: bash + + brew install snapcraft + + .. group-tab:: Windows + + #. `Install WSL2 with Ubuntu 20.04 or higher + `_. + #. 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. + + +Chose a build provider +^^^^^^^^^^^^^^^^^^^^^^ + +Before proceeding, you must choose a build provider. + +`Multipass `_ 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 `_ creates and manages Linux +container images. It can operate inside VMs. + + +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 + +#. Next, add LXD to your system: + + .. code:: bash + + sudo snap install lxd + +#. You also need to add your user account to the ``lxd`` group so you can + access the tool's resources: + + .. code:: bash + + sudo usermod -a -G lxd $USER + +#. Next, 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 +`_ in +the LXD documentation for further installation options and troubleshooting. + + +Install multiple snap instances +------------------------------- + +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 an mainstream release. + +To install another version of Snapcraft as a snap: + +#. First, list all the available versions of Snapcraft, and take note of the + value in the channel column for the version you're interested in. + + .. code:: bash + + sudo snap info snapcraft + +#. Install Snapcraft using the `instance key naming + `_ syntax: + + .. code:: bash + + sudo snap install snapcraft_edge latest/edge --classic + + Replace ``edge`` with whichever name is appropriate for the instance, and + ``latest/edge`` with the target channel and track. + +Whenever you want to run this parallel version of Snapcraft, invoke the +instance name of the command -- in this example, ``snapcraft_edge``. + + +Locate your Snapcraft instances +------------------------------- + +Your system cqn have multiple versions of Snapcraft installed. This situation +is quite common for users who have both apt and snap copies of the tool. + +You can check which Snapcraft installation is selected when running +the ``snapcraft`` command by trying: + +.. code:: bash + + which snapcraft + +The output prints the location of the binary that's available in the +environment. The default snap of Snapcraft is installed in: + +.. terminal:: + + /snap/bin/snapcraft diff --git a/docs/reference/anatomy-of-a-recipe.rst b/docs/reference/anatomy-of-a-recipe.rst new file mode 100644 index 0000000000..c69250e2ab --- /dev/null +++ b/docs/reference/anatomy-of-a-recipe.rst @@ -0,0 +1,329 @@ +.. _anatomy-of-a-recipe: + +Anatomy of a recipe +=================== + +This page provides a break down of the keys in complete Snapcraft recipes, as +declared in ``snapcraft.yaml`` files. + +Two recipes will be examined. The first is a simple recipe from a Python-based +snap called `yt-dlp `_. The second is more +complex and builds the `wethr `_ app, which +is written in Node. + +Each key in the yt-dlp recipe will be covered, and the more advanced keys in +wethr will be examined. + + +Simple recipe +------------- + +yt-dlp is a command line tool for extracting online videos, and is a +self-contained Python project. + +.. collapse:: yt-dlp recipe + + .. literalinclude:: code/yt-dlp-recipe.yaml + :language: yaml + :lines: 2- + + +Top-level directives +~~~~~~~~~~~~~~~~~~~~ + +Several `top-level keys +`_ +define and describe the snap. + + +Metadata +^^^^^^^^ + +For convenience, the first set of keys comprise the snap's metadata, or +manifest. These declare information about the snap itself, such as the snap's +name, version, summary, and description. These identifying keys allow users to +find the snap through the Snap Store. + +The ``name`` key defines the name of the snap. It must start with an ASCII +character and can only use ASCII lowercase letters, numbers, and hyphens. It +must be between 1 and 40 characters in length. It must be unique in the Snap +Store. + +The ``version`` key defines the version of the snap to the user. The maximum +length is 32 characters. + +The ``summary`` key describes the software in brief. It can't exceed 79 +characters. It accepts multi-line YAML syntax. + +The ``description`` key describes the software in full. It also accepts +multi-line syntax. There is no practical limit on the length of this key. + +When the snap is published, this metadata will be made available to users. It +can also be used to pre-populate certain keys in the snap's Snap Store page +during upload. + + +Base +^^^^ + +As part of their security design, snaps can't see the host's root file system +by default. This prevents conflict with other snaps and increases security. +However, apps inside the snap still need some location to act as their root +filesystem. They would also benefit if common libraries were drawn from this +root file system rather than being bundled into each. + +The ``base`` key specifies the `core snap +`_, which provides a minimal set of +libraries common to most snaps. It's mounted and used as the root filesystem +for the apps inside the snap. In essence, this means the snaps behave as though +they were running on a system that matches the base. + +The core24, core22, and core20 bases are available. Bases correspond to Ubuntu +LTS releases. For example, the library set in core24 is equivalent to a subset +found in the Ubuntu 24.04 LTS general release. For most practical purposes, the +use of either core24 and core22 is recommended, depending on the `supported +plugins `_ the snap uses. + + +Confinement +^^^^^^^^^^^ + +Security confinement distinguishes snaps from software distributed using the +traditional repository methods. `Confinement +`_ allows for a high level of +isolation and security, and prevents snaps from being affected by underlying +system changes, snaps affecting each other, or snaps affecting the host. + +The ``confinement`` key describes what type of access the snap's apps will have +once installed on the host. Confinement levels can be treated as filters that +define what type of system resources outside the snap that the app can access. + +Confinement is defined by a *level* and fine-tuned using interfaces. + +There are three confinment levels: + +- ``strict``. This confinement level uses Linux kernel security features to + lock down the apps inside the snap. By default, a strictly-confined app can't + access the network, the users' home directory, any audio subsystems or + webcams, and it can't display any graphical output through X or Wayland. + Interfaces override its access. + + This is the preferred confinement for most apps. +- ``devmode``. This is a debug mode level used by developers as they iterate on + the creation of their snap. This allows developers to troubleshoot apps, + because they may behave differently when confined. + + This confinement is a temporary measure while a snap is being crafted. +- ``classic``. This is a permissive level equivalent to the full system access + that traditional apps have. Classic confinement is often used as a stop-gap + measure to enable developers to publish apps that need more access than the + current set of permissions allow. + + This confinment should be used only when required for functionality, as it + lowers the security of the app. Classically-confined snaps must be approved + by the Snap Store team before publication. Snaps that use classic confinement + may be rejected if they don't meet the necessary requirements. + +Here are the resources the snap is exposed to, across confinement levels: + +.. list-table:: + :header-rows: 1 + + * - Resource + - strict + - devmode + - classic + * - Network + - No + - Yes + - System + * - Home directory + - No + - Yes + - system + * - Audio + - No + - Yes + - System + * - Webcam + - No + - Yes + - System + * - Display + - No + - Yes + - System + +A strictly-confined snap is considered untrusted, and it runs in a restricted +sandbox. By design, untrusted apps: + +- Can freely access their own data. +- Can't access other apps' data. +- Can't access non-app-specific user data. +- Can't access privileged portions of the OS. +- Can't access privileged system APIs. +- May access sensitive APIs under some conditions. + + +Interfaces +^^^^^^^^^^ + +Strictly-confined apps don't always function properly with the default security +policy. For example, a browser without network access or a media player without +audio access don't serve their intended purpose. To that end, snap developers +can use `interfaces `_, a +mechanism of granular resource-level security permissions. These allow +developers to expand on the default security policies and connect apps to +system resources. + +An interface consists of a connection between a slot and a plug. The slot is +the provider of the interface while the plug is the consumer, and a slot can +support multiple plug connections. + +Interfaces can be automatically or manually connected. Some interfaces will be +auto-connected. Others may not, especially if they have access to sensitive +resources, like network control. Users have the option to manually control +interfaces by connecting and disconnecting them using snapd. + + +Parts +~~~~~ + +The `part directives +`_ +define all the pieces of software that will be used to build the apps inside +the snap. It describes how the snap is going to be built. + +The yt-dlp snap only has one part, for the app itself. + +The ``plugin`` key instructs the part to use the Python plugin, which will +build the app's Python code. The plugin automatically handles all building and +dependency installation. + +The ``source`` key specifies the path to the software source or a download URL +to it. It can be a local or remote path, and can refer to a directory tree, a +compressed archive or a revision control repository. In this particular case, +the app is built the project's upstream GitHub repository. + + +Apps +~~~~ + +The `app directives +`_ +define the command path for each app, how it will be run, optional parameters, +and the interface connections that will be established at runtime. + +The yt-dlp recipe declares a single app, which is the main app itself. Other +snaps may have multiple sub-apps or executables. + +The ``command`` key defines the path to the executable -- relative to the snap +-- and arguments to use when the app runs. + +The ``plugs`` key defines the list of interfaces to which the app will have +access to. This enables the intended app functionality. In this specific case, +the yt-dlp snap will be allowed access to the home, network and removable-media +interfaces, which are not available by default under strict confinement. This +will allow the user of the tool to access files in the user's home directory, +from a network connection, or from any mounted removable media locations. + + +Advanced recipe +--------------- + +For a more complex example, there's the recipe for wethr, a CLI command for +retrieving local weather conditions. + +The metadata, base, and confinement declarations are rather similar to the +simple example, but with some notable differences. + +.. collapse:: wethr recipe + + .. literalinclude:: code/wethr-recipe.yaml + :language: yaml + :lines: 2- + +.. note:: + + The recipe shown here has been modified from the actual snap's recipe to + highlight features of Snapcraft. + + +Adopting metadata +~~~~~~~~~~~~~~~~~ + +The ``adopt-info`` key instructs Snapcraft to import metadata from another +source. Such use can be useful for continuous integration and delivery systems, +where the declarations in the recipe can be obtained from scripts rather than +manually. + +There are multiple ways that information can be obtained. For a how-to guide on +bringing in external metadata, see `Using external metadata +`_. + +Multiple metadata fields can be populated using this key. In this recipe, the +snap's version is obtained from the Git repository release tag, which proceeds +in two stages: + +#. The ``adopt-info`` key instructs Snapcraft to populate the metadata fields + that aren't already declared in the recipe. +#. In the parts section at the end of the recipe: + #. A step in the build lifecycle is manually overridden. + #. A custom script is used to derive the version string. + #. The version string is set using the Snapcraftctl scriptlet. + +Alternatively, in this particular example, the version field could also be +manually set with ``version: '1.5'``. + + +Quality grade +~~~~~~~~~~~~~ + +The ``grade`` key defines the quality level of the snap. Two levels are +available, devel and stable. Snaps with the devel grade can't be uploaded to +either of the stable or candidate channels in the Snap Store. + + +Architectures +~~~~~~~~~~~~~ + +The ``architectures`` key defines the target platforms for which the snap +should be built on and built for. It requires the build system that is running +the Snapcraft tool to be able to compile and build the snap for the listed +platforms. + + +Parts +~~~~~ + +Compared to the recipe of yt-dlp, wethr has a part that's notably more +intricate. + +It too has one part, but it's built with the `npm plugin +`_, which is designed to simplify the +building of Node and JavaScript-based apps, and contains custom options for +Node. + +The ``npm-include-node`` key determines whether to download and include a Node +runtime in the snap, which in turn is specified by the ``npm-node-version`` +key. + +The ``source`` key like before defines the URL or a path of the app code that +needs to be downloaded for the build. It points to the original wethr project's +source code. + +The ``override-pull`` key is an inline Bash script that runs during the pull +step of the :ref:`part lifecycle `. It's used to perform operations +that can't be satisfied by the default pull operation in the lifecyele. In the +wethr example, the listed commands are used to derive the correct version of +the app, and set it using the Snapcraftctl scriptlet. More details about +overrides can be found in :ref:`Overriding the default build `. + +The ``build-packages`` key defines the list of tools and libraries required to +successfully build or compile the part. The build packages are obtained from +the repository archives that match the base, and need to be written in the +syntax that can be correctly interpreted by the apt package manager. For +instance, a foo build package from core22 would be installed (``apt install +foo``) in the snap build environment during build. In the case of wethr, the +snap needs Git to retrieve the sources from a remote Git repository and sed +to search and replace the string and yield a Git tag. diff --git a/docs/reference/channels.rst b/docs/reference/channels.rst new file mode 100644 index 0000000000..c6a4848d9b --- /dev/null +++ b/docs/reference/channels.rst @@ -0,0 +1,61 @@ +.. _channels: + +Channels +======== + +Snaps are published on *channels*, which are concurrent versions of the snap, +addressing needs such as preview releases and long-term version support. + +A channel is composed of three components -- a track, a risk, and a branch. + +Briefly, a channel is represented in Snapcraft like this: + + // + +In Snapcraft commands, a typical channel without a branch looks like this: + +.. code:: bash + + --channel=latest/edge + + +Track +------ + +The *track* represents the highest level of organisation for the snap's +release. Typically, it signifies a major release. Authors can use tracks to +maintain different major versions of their software. + +All snaps must have a default track called *latest*. This track is assumed for +most operations with Snapcraft, unless otherwise specified. Aside from latest, +the release convention for tracks is at the author's discretion. A track could, +as examples, be used to track minor updates (2.0.1, 2.0.2), major updates (2.1, +2.2), or releases held for long-term support (3.2, 4.1). + + +Risk +---- + +The *risk* represents the author's confidence in the release, its readiness, +and signals its potential dangers to users. This is the most important +component of a channel. With it, authors can maintain multiple variations of +the same release of the snap under the same name. + +Risk levels are preset by the Snap Store. The available levels are *stable*, +*candidate*, *beta*, and *edge*. Snaps built with the devel grade can't be +released to either the stable or candidate channels. + +Snaps are installed to a user's system with the stable risk level by default. + + +Branch +------ + +The *branch* represents the smallest meaningful unit of history in the +project's development. It's an optional component intended to distinguish +short-lived or on-demand releases for bug-fixing, one-off testing, and other irregular work. + +Branch names convey their purpose, such as ``fix-for-bug123``. Branch names are +not, however, discoverable in the Snap Store. Instead, they must be shared by +authors to users and referenced by their exact name. If a snap branch has no +new publications for 30 days, the Snap Store closes its branch. diff --git a/docs/reference/code/wethr-recipe.yaml b/docs/reference/code/wethr-recipe.yaml new file mode 100644 index 0000000000..dfcdebe518 --- /dev/null +++ b/docs/reference/code/wethr-recipe.yaml @@ -0,0 +1,44 @@ +# Example recipe for anatomical breakdown + +name: wethr +summary: Command line weather tool. +description: | + Get current weather + +adopt-info: wethr +base: core22 +grade: stable +confinement: strict + +architectures: + - build-on: amd64 + - build-on: armhf + - build-on: arm64 + +apps: + wethr: + command: bin/wethr + plugs: + - network + +parts: + wethr: + plugin: npm + npm-include-node: true + npm-node-version: "10.14.1" + source: https://github.com/twobucks/wethr.git + override-pull: | + Snapcraftctl pull + last_committed_tag="$(git describe --tags --abbrev=0)" + last_committed_tag_ver="$(echo ${last_committed_tag} | sed 's/v//')" + last_released_tag="$(snap info wethr | awk '$1 == "latest/beta:" { print $2 }')" + # If the latest tag from the upstream project has not been released to + # beta, build that tag instead of master. + if [ "${last_committed_tag_ver}" != "${last_released_tag}" ]; then + git fetch + git checkout "${last_committed_tag}" + fi + Snapcraftctl set-version "$(git describe --tags | sed 's/v//')" + build-packages: + - git + - sed diff --git a/docs/reference/code/yt-dlp-recipe.yaml b/docs/reference/code/yt-dlp-recipe.yaml new file mode 100644 index 0000000000..f5a1c0312f --- /dev/null +++ b/docs/reference/code/yt-dlp-recipe.yaml @@ -0,0 +1,22 @@ +# Example recipe for anatomical breakdown + +name: yt-dlp +summary: A fork of youtube-dl with additional features and patches +description: | + Download and play videos on your local system. Runs from the command + line and with all the features and patches of youtube-dlc in addition + to the latest youtube-dl. +version: test +grade: stable +confinement: strict +base: core22 + +apps: + yt-dlp: + command: bin/yt-dlp + plugs: [home, network, network-bind, removable-media] + +parts: + yt-dlp: + plugin: python + source: https://github.com/yt-dlp/yt-dlp.git diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 4c6c69a88c..f1a6e03e91 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,11 +1,15 @@ .. _reference: Reference -********* +========= .. toctree:: :maxdepth: 1 + anatomy-of-a-recipe + snap-build-process + snap-publishing-process + channels architectures bases changelog @@ -15,9 +19,11 @@ Reference plugins /common/craft-parts/reference/part_properties parts_steps + system-requirements + Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`modindex` diff --git a/docs/reference/snap-build-process.rst b/docs/reference/snap-build-process.rst new file mode 100644 index 0000000000..96c872ef7a --- /dev/null +++ b/docs/reference/snap-build-process.rst @@ -0,0 +1,131 @@ +.. _snap-build-process: + +Snap build process +================== + +This page describes at a high level the workflow between a snap recipe and its +resulting artefact. + + +The recipe file +--------------- + +Snaps are created using a build configuration -- called from here on a *recipe* +-- defined in a file named ``snapcraft.yaml``. The recipe is written in YAML, +with keys and values defining the snap's structure and behavior. When Snapcraft +runs, it parses this file and uses the declared information to build the snap. +For developers more familiar with the traditional Linux build systems, the +process is somewhat similar a Makefiles and RPM SPEC files. + +The recipe is a plaintext file encoded in UTF-8, can be composed manually or +generated from a template. The template contains enough boilerplate keys to +build the snap with little effort. + +Designing a snap is an open-ended craft. However, most snap recipes have some +common elements with special names in the Snapcraft world. + +* The snap's *metadata* provides identifiers and descriptions by which the snap + can account for itself and be discovered in the Snap Store. +* *Confinement* describes how confined and secure the snap is. +* The *base* describes which set of libraries the snap will use for its + functionality. The base also defines the operating system version for the + snap build instance in the virtual machine (VM) or container during build. + For instance, ``base: core24`` means that Snapcraft will launch an Ubuntu + 24.04 LTS VM or container, the set of tools and libraries used inside the + snap will originate from the Ubuntu 24.04 LTS repository archives, and the + snap apps will run as if on an Ubuntu 24.04 host, regardless of the + actual system's actual underlying Linux distribution. +* *Parts* describe the software components inside the snap. +* *Apps* describes the apps and their commands that are to run inside + the snap. + +It's important to note several details about snaps and their recipes: + +* A snap can contain one or more parts. +* A snap can contain one or more app. +* Parts can be pre-assembled binaries or they may be compiled as part of the + build process. +* Parts use special language- and framework-specific plugins to handle + different software build systems. +* Parts can make use of build dependencies but that won't be shipped in the + resulting snap. Common examples of such dependencies are gcc and Make. +* The parts can ship runtime dependencies in the snap for use by the apps, such + as ``python-bcrypt``. + + +The build +--------- + +When Snapcraft is executed, it looks for the recipe in the current working +directory, either at the root or in a ``snap`` sub-directory. If the file is +found, Snapcraft will then parse its contents and begin the build. + +The command will start an instance of a minimal Ubuntu install, either as VM +with Multipass or container instance with LXD, download the necessary packages +and begin building the snap. + + +The build lifecycle +------------------- + +During building, Snapcraft loops through several steps, collectively known as +the :ref:`build lifecycle `. Snapcraft inherits much of the build +DNA from other craft tools authored by Canonical, and the specific actions are: + +#. During the **pull** step, Snapcraft downloads or retrieves the components + needed to build the relevant part. For instance, if source points to a Git + repository, the pull step will clone that repository. +#. During the **build** step, Snapcraft constructs the part from the previously + pulled components. Since apps are compiled from multiple languages (C, Java, + Go, Rust, Python, and so on), the build definition also needs to include a + specification on how to construct the part. This is done by declaring a + :ref:`plugin `. Parts are processed linearly, unless there is a + dependency order declared. +#. During the **stage** step, Snapcraft copies the built parts into the staging + area. Parts aren't ordered at this point, and there might be an additional + level of processing to ensure the snap contains the required files, and that + there are no conflicts between parts. +#. During the **prime** step, Snapcraft copies the staged components into the + priming area, where the files are placed in their final paths for the + resulting snap. The prime step is similar to the stage step, but it may + exclude certain components from the latter. +#. During the **pack** step, Snapcraft bundles the assembled components in the + priming area into a single archive. + + +The result +---------- + +The result of a successful Snapcraft build is a snap file, which is itself a +compressed Squashfs archive with a ``.snap`` extension. + +After the build is complete, the resulting artefact is placed in the current +working directory. Snapcraft then halts the VM or container and preserves it +for reuse in any re-builds of the snap, to reduce processing time. + +A snap may contain one or more files that allow the apps to run without +reliance on the host's libraries. A snap will contain one or more apps, +services, configuration files, assets like icons, and other files. + +Typically, the content of a snap will resemble a Linux filesystem layout, like +this: + +.. terminal:: + + drwxr-xr-x 10 igor igor 4096 Jun 10 2020 ./ + drwxrwxrwx 14 igor igor 16384 Oct 17 16:40 ../ + drwxr-xr-x 2 igor igor 4096 Jun 10 2020 bin/ + drwxr-xr-x 10 igor igor 4096 Jun 10 2020 etc/ + -rw-r--r-- 1 igor igor 14 Jun 10 2020 flavor-select + drwxr-xr-x 3 igor igor 4096 Jun 10 2020 lib/ + drwxr-xr-x 2 igor igor 4096 Jun 10 2020 lib64/ + drwxr-xr-x 3 igor igor 4096 Jun 10 2020 meta/ + drwxr-xr-x 3 igor igor 4096 Jun 10 2020 snap/ + drwxr-xr-x 7 igor igor 4096 Jun 10 2020 usr/ + drwxr-xr-x 3 igor igor 4096 Feb 26 2018 var/ + +The contents of a snap can be examined directly by extracting it as an archive: + +.. code:: yaml + + unsquashfs .snap diff --git a/docs/reference/snap-publishing-process.rst b/docs/reference/snap-publishing-process.rst new file mode 100644 index 0000000000..fb895a4740 --- /dev/null +++ b/docs/reference/snap-publishing-process.rst @@ -0,0 +1,17 @@ +.. _snap-publishing-process: + +Snap publishing process +======================= + +After a snap is built, it's ready for distribution in a package store. Authors +who wish to make their snaps public can use of the official `Snap Store +`_, hosted and curated by Canonical. + +Prior to engaging with the Snap Store, authors must first create a free +developer account. Before they publish a new snap to the store, they must +register their snap's name to reserve it. + +The Snap Store comes with a high level of release management flexibility, +achieved by using multiple :ref:`channels `, which allow developers +to publish their apps in a staged, controlled manner. The channels can be +treated as concurrent software releasing and version control. diff --git a/docs/reference/system-requirements.rst b/docs/reference/system-requirements.rst new file mode 100644 index 0000000000..536a42bea9 --- /dev/null +++ b/docs/reference/system-requirements.rst @@ -0,0 +1,41 @@ +.. _system-requirements: + +System requirements +=================== + +To run Snapcraft, a system requires the following minimum hardware and +installed software. These requirements apply to local hosts as well as VMs and +container hosts. + + +Minimum hardware requirements +----------------------------- + +- 64-bit processor +- 2GB RAM +- 10GB available storage space +- Internet access for remote software sources and the Snap Store + + +Platform requirements +--------------------- + +.. list-table:: + :header-rows: 1 + :widths: 1 3 3 + + * - Platform + - Version + - Software requirements + * - GNU/Linux + - Popular distributions that ship with systemd and are `compatible with + snapd `_ + - systemd + + snapd 2.44.3 or higher + * - Windows + - Windows 10 version 2004 or higher + - `Windows Subsystem for Linux 2 (WSL2) `_ + * - macOS + - macOS Sonoma or higher + - `Homebrew `_ From f37dd64b0aa5d73bc06195283b6cf727dae8ad96 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Wed, 11 Dec 2024 15:06:32 -0800 Subject: [PATCH 2/8] Update docs/howto/select-a-build-provider.rst Co-authored-by: Callahan --- docs/howto/select-a-build-provider.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/howto/select-a-build-provider.rst b/docs/howto/select-a-build-provider.rst index 4b0a96d320..5b00146bc1 100644 --- a/docs/howto/select-a-build-provider.rst +++ b/docs/howto/select-a-build-provider.rst @@ -12,7 +12,7 @@ Consult the following tables for different methods of overriding the build provider. -core22 override methods +core22 and higher override methods ----------------------- .. list-table:: From d4d9b8c1a026496b9e004149dd623aeb69c29e77 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Wed, 11 Dec 2024 15:06:58 -0800 Subject: [PATCH 3/8] Update docs/howto/select-a-build-provider.rst Co-authored-by: Callahan --- docs/howto/select-a-build-provider.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/howto/select-a-build-provider.rst b/docs/howto/select-a-build-provider.rst index 5b00146bc1..dcd0aa10d7 100644 --- a/docs/howto/select-a-build-provider.rst +++ b/docs/howto/select-a-build-provider.rst @@ -60,8 +60,8 @@ core20 override methods Select through the Snapcraft configuration ------------------------------------------ -The snap configuration method mentioned in the previous sections is a feature -of snapd. +The snap configuration method mentioned in the previous sections is a +`feature of snapd`_. 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 From 1582115f2d1549bc351e44ca4962b4a04fb818ed Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Wed, 11 Dec 2024 15:09:10 -0800 Subject: [PATCH 4/8] docs: inline PR review Co-authored-by: Callahan --- docs/howto/set-up-snapcraft.rst | 4 ++-- docs/reference/code/wethr-recipe.yaml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/howto/set-up-snapcraft.rst b/docs/howto/set-up-snapcraft.rst index dd176e62ce..39f5ee3b80 100644 --- a/docs/howto/set-up-snapcraft.rst +++ b/docs/howto/set-up-snapcraft.rst @@ -165,7 +165,7 @@ Install multiple snap instances 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 an mainstream release. +new features in your snaps, before they arrive in a mainstream release. To install another version of Snapcraft as a snap: @@ -193,7 +193,7 @@ instance name of the command -- in this example, ``snapcraft_edge``. Locate your Snapcraft instances ------------------------------- -Your system cqn have multiple versions of Snapcraft installed. This situation +Your system can have multiple versions of Snapcraft installed. This situation is quite common for users who have both apt and snap copies of the tool. You can check which Snapcraft installation is selected when running diff --git a/docs/reference/code/wethr-recipe.yaml b/docs/reference/code/wethr-recipe.yaml index dfcdebe518..c502e0bc4c 100644 --- a/docs/reference/code/wethr-recipe.yaml +++ b/docs/reference/code/wethr-recipe.yaml @@ -28,7 +28,7 @@ parts: npm-node-version: "10.14.1" source: https://github.com/twobucks/wethr.git override-pull: | - Snapcraftctl pull + craftctl pull last_committed_tag="$(git describe --tags --abbrev=0)" last_committed_tag_ver="$(echo ${last_committed_tag} | sed 's/v//')" last_released_tag="$(snap info wethr | awk '$1 == "latest/beta:" { print $2 }')" From 1df1efa25f4ea171fbacaf1a91d04b36669918a0 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Wed, 11 Dec 2024 17:19:18 -0800 Subject: [PATCH 5/8] docs: incorporate mr-cal's review --- docs/howto/select-a-build-provider.rst | 15 ++++++--- docs/howto/set-up-snapcraft.rst | 15 ++++----- docs/reference/anatomy-of-a-recipe.rst | 44 ++++++++++++++------------ docs/reference/channels.rst | 7 ++++ docs/reference/snap-build-process.rst | 11 ++++--- 5 files changed, 53 insertions(+), 39 deletions(-) diff --git a/docs/howto/select-a-build-provider.rst b/docs/howto/select-a-build-provider.rst index dcd0aa10d7..b32970d213 100644 --- a/docs/howto/select-a-build-provider.rst +++ b/docs/howto/select-a-build-provider.rst @@ -13,7 +13,10 @@ 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 @@ -36,6 +39,8 @@ core22 and higher override methods core20 override methods ----------------------- +For core20, Multipass is the default provider on all platforms. + .. list-table:: :header-rows: 1 :widths: 1 1 1 @@ -57,11 +62,11 @@ core20 override methods - ``snap set snapcraft provider=`` -Select through the Snapcraft configuration ------------------------------------------- +Select through the snap configuration +------------------------------------- -The snap configuration method mentioned in the previous sections is a -`feature of snapd`_. +The snap configuration method mentioned in the previous sections is a `feature +of snapd `_. 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 diff --git a/docs/howto/set-up-snapcraft.rst b/docs/howto/set-up-snapcraft.rst index 39f5ee3b80..3918f547ad 100644 --- a/docs/howto/set-up-snapcraft.rst +++ b/docs/howto/set-up-snapcraft.rst @@ -86,6 +86,9 @@ For instance, it most likely won't itself run inside a VM. `LXD `_ 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 `. + Install Multipass ^^^^^^^^^^^^^^^^^ @@ -127,20 +130,14 @@ To install LXD: sudo snap install lxd -#. Next, add LXD to your system: - - .. code:: bash - - sudo snap install lxd - -#. You also need to add your user account to the ``lxd`` group so you can - access the tool's resources: +#. Add your user account to the ``lxd`` group so you can access the tool's + resources: .. code:: bash sudo usermod -a -G lxd $USER -#. Next, log out and back in to your account for the new group to become +#. 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 diff --git a/docs/reference/anatomy-of-a-recipe.rst b/docs/reference/anatomy-of-a-recipe.rst index c69250e2ab..355c000c54 100644 --- a/docs/reference/anatomy-of-a-recipe.rst +++ b/docs/reference/anatomy-of-a-recipe.rst @@ -53,10 +53,12 @@ The ``version`` key defines the version of the snap to the user. The maximum length is 32 characters. The ``summary`` key describes the software in brief. It can't exceed 79 -characters. It accepts multi-line YAML syntax. +characters. The ``description`` key describes the software in full. It also accepts -multi-line syntax. There is no practical limit on the length of this key. +multi-line syntax. It has a 4,096 character limit, and can be split across +multiple lines with `YAML's multi-line syntax +`_. When the snap is published, this metadata will be made available to users. It can also be used to pre-populate certain keys in the snap's Snap Store page @@ -72,11 +74,10 @@ However, apps inside the snap still need some location to act as their root filesystem. They would also benefit if common libraries were drawn from this root file system rather than being bundled into each. -The ``base`` key specifies the `core snap -`_, which provides a minimal set of -libraries common to most snaps. It's mounted and used as the root filesystem -for the apps inside the snap. In essence, this means the snaps behave as though -they were running on a system that matches the base. +The ``base`` key specifies the :doc:`core snap `, which +provides a minimal set of libraries common to most snaps. It's mounted and used +as the root filesystem for the apps inside the snap. In essence, this means the +snaps behave as though they were running on a system that matches the base. The core24, core22, and core20 bases are available. Bases correspond to Ubuntu LTS releases. For example, the library set in core24 is equivalent to a subset @@ -114,15 +115,17 @@ There are three confinment levels: because they may behave differently when confined. This confinement is a temporary measure while a snap is being crafted. -- ``classic``. This is a permissive level equivalent to the full system access - that traditional apps have. Classic confinement is often used as a stop-gap - measure to enable developers to publish apps that need more access than the - current set of permissions allow. - - This confinment should be used only when required for functionality, as it - lowers the security of the app. Classically-confined snaps must be approved - by the Snap Store team before publication. Snaps that use classic confinement - may be rejected if they don't meet the necessary requirements. +- ``classic``. This is the maximally permissive level equivalent to the full + system access that traditional apps have. Classic confinement is often used + as a stop-gap measure to enable developers to publish apps that need more + access than the current set of permissions allow. + + This confinment should be used only when required for functionality, as its + lack of restrictions is a security risk. Before a snap can be published with + classic confinement, it must be approved by the Snap Store team according to + a `candidate review process + `_. + Snaps may be rejected if they don't meet the necessary requirements. Here are the resources the snap is exposed to, across confinement levels: @@ -268,6 +271,7 @@ in two stages: #. The ``adopt-info`` key instructs Snapcraft to populate the metadata fields that aren't already declared in the recipe. #. In the parts section at the end of the recipe: + #. A step in the build lifecycle is manually overridden. #. A custom script is used to derive the version string. #. The version string is set using the Snapcraftctl scriptlet. @@ -287,10 +291,10 @@ either of the stable or candidate channels in the Snap Store. Architectures ~~~~~~~~~~~~~ -The ``architectures`` key defines the target platforms for which the snap -should be built on and built for. It requires the build system that is running -the Snapcraft tool to be able to compile and build the snap for the listed -platforms. +The ``architectures`` key defines the target :doc:`platforms +` for which the snap should be built on and built +for. It requires the build system that is running the Snapcraft tool to be able +to compile and build the snap for the listed platforms. Parts diff --git a/docs/reference/channels.rst b/docs/reference/channels.rst index c6a4848d9b..d200fc75bc 100644 --- a/docs/reference/channels.rst +++ b/docs/reference/channels.rst @@ -59,3 +59,10 @@ Branch names convey their purpose, such as ``fix-for-bug123``. Branch names are not, however, discoverable in the Snap Store. Instead, they must be shared by authors to users and referenced by their exact name. If a snap branch has no new publications for 30 days, the Snap Store closes its branch. + + +See also +-------- + +`Request process for custom tracks +`_ diff --git a/docs/reference/snap-build-process.rst b/docs/reference/snap-build-process.rst index 96c872ef7a..6b02ac8c16 100644 --- a/docs/reference/snap-build-process.rst +++ b/docs/reference/snap-build-process.rst @@ -11,11 +11,12 @@ The recipe file --------------- Snaps are created using a build configuration -- called from here on a *recipe* --- defined in a file named ``snapcraft.yaml``. The recipe is written in YAML, -with keys and values defining the snap's structure and behavior. When Snapcraft -runs, it parses this file and uses the declared information to build the snap. -For developers more familiar with the traditional Linux build systems, the -process is somewhat similar a Makefiles and RPM SPEC files. +-- defined in a file named ``snapcraft.yaml``. The recipe is written in a +declarative style in YAML, with keys and values defining the snap's structure +and behavior. When Snapcraft runs, it parses this file and uses the declared +information to build the snap. For developers more familiar with the +traditional Linux build systems, the process is somewhat similar a Makefiles +and RPM SPEC files. The recipe is a plaintext file encoded in UTF-8, can be composed manually or generated from a template. The template contains enough boilerplate keys to From bb375e08d824ff5598a0fcca76ec47b24d50077c Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Thu, 12 Dec 2024 12:01:09 -0800 Subject: [PATCH 6/8] docs: apply lengau's inline suggestions Co-authored-by: Alex Lowe --- docs/howto/set-up-snapcraft.rst | 30 ++---------------------------- 1 file changed, 2 insertions(+), 28 deletions(-) diff --git a/docs/howto/set-up-snapcraft.rst b/docs/howto/set-up-snapcraft.rst index 3918f547ad..de9bf499a3 100644 --- a/docs/howto/set-up-snapcraft.rst +++ b/docs/howto/set-up-snapcraft.rst @@ -31,13 +31,6 @@ Install Snapcraft sudo snap install snapcraft --classic - If your distribution lacks snapd or access to the Snap Store, but has - access to the Ubuntu or Debian package repository, you can install - Snapcraft as a deb package: - - .. code:: bash - - sudo apt install snapcraft .. group-tab:: macOS @@ -73,8 +66,8 @@ is the default on macOS and Windows. For **core20**, Multipass is the default provider on all platforms. -Chose a build provider -^^^^^^^^^^^^^^^^^^^^^^ +Choose a build provider +^^^^^^^^^^^^^^^^^^^^^^^ Before proceeding, you must choose a build provider. @@ -187,22 +180,3 @@ Whenever you want to run this parallel version of Snapcraft, invoke the instance name of the command -- in this example, ``snapcraft_edge``. -Locate your Snapcraft instances -------------------------------- - -Your system can have multiple versions of Snapcraft installed. This situation -is quite common for users who have both apt and snap copies of the tool. - -You can check which Snapcraft installation is selected when running -the ``snapcraft`` command by trying: - -.. code:: bash - - which snapcraft - -The output prints the location of the binary that's available in the -environment. The default snap of Snapcraft is installed in: - -.. terminal:: - - /snap/bin/snapcraft From a071107dd26289eec40eb6dd1b8201c9fc91df1b Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Thu, 12 Dec 2024 12:18:36 -0800 Subject: [PATCH 7/8] docs: incorporate mr-cal and langau's review --- docs/howto/set-up-snapcraft.rst | 29 ++++++++++++++------------ docs/reference/anatomy-of-a-recipe.rst | 28 ------------------------- docs/reference/system-requirements.rst | 3 ++- 3 files changed, 18 insertions(+), 42 deletions(-) diff --git a/docs/howto/set-up-snapcraft.rst b/docs/howto/set-up-snapcraft.rst index de9bf499a3..0608341c2f 100644 --- a/docs/howto/set-up-snapcraft.rst +++ b/docs/howto/set-up-snapcraft.rst @@ -150,33 +150,36 @@ See `How to install LXD the LXD documentation for further installation options and troubleshooting. -Install multiple snap instances -------------------------------- +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. +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 version of Snapcraft as a snap: +To install another instance of Snapcraft: -#. First, list all the available versions of Snapcraft, and take note of the - value in the channel column for the version you're interested in. +#. 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 - `_ syntax: + `_ 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 - Replace ``edge`` with whichever name is appropriate for the instance, and - ``latest/edge`` with the target channel and track. - Whenever you want to run this parallel version of Snapcraft, invoke the instance name of the command -- in this example, ``snapcraft_edge``. - - diff --git a/docs/reference/anatomy-of-a-recipe.rst b/docs/reference/anatomy-of-a-recipe.rst index 355c000c54..aeebead05b 100644 --- a/docs/reference/anatomy-of-a-recipe.rst +++ b/docs/reference/anatomy-of-a-recipe.rst @@ -129,34 +129,6 @@ There are three confinment levels: Here are the resources the snap is exposed to, across confinement levels: -.. list-table:: - :header-rows: 1 - - * - Resource - - strict - - devmode - - classic - * - Network - - No - - Yes - - System - * - Home directory - - No - - Yes - - system - * - Audio - - No - - Yes - - System - * - Webcam - - No - - Yes - - System - * - Display - - No - - Yes - - System - A strictly-confined snap is considered untrusted, and it runs in a restricted sandbox. By design, untrusted apps: diff --git a/docs/reference/system-requirements.rst b/docs/reference/system-requirements.rst index 536a42bea9..90a0755934 100644 --- a/docs/reference/system-requirements.rst +++ b/docs/reference/system-requirements.rst @@ -11,7 +11,8 @@ container hosts. Minimum hardware requirements ----------------------------- -- 64-bit processor +- AMD64, ARM64, ARMv7-M, RISC-V 64-bit, PowerPC 64-bit little-endian, or S390x + processor - 2GB RAM - 10GB available storage space - Internet access for remote software sources and the Snap Store From 07bd6c9854765af4cc52d67d5e2f9cb1916c9222 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Thu, 12 Dec 2024 14:27:49 -0800 Subject: [PATCH 8/8] docs: adjust description of tracks --- docs/reference/channels.rst | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/reference/channels.rst b/docs/reference/channels.rst index d200fc75bc..3ec2c50db4 100644 --- a/docs/reference/channels.rst +++ b/docs/reference/channels.rst @@ -20,17 +20,22 @@ In Snapcraft commands, a typical channel without a branch looks like this: Track ------- +----- The *track* represents the highest level of organisation for the snap's release. Typically, it signifies a major release. Authors can use tracks to maintain different major versions of their software. -All snaps must have a default track called *latest*. This track is assumed for -most operations with Snapcraft, unless otherwise specified. Aside from latest, -the release convention for tracks is at the author's discretion. A track could, -as examples, be used to track minor updates (2.0.1, 2.0.2), major updates (2.1, -2.2), or releases held for long-term support (3.2, 4.1). +All snaps have one default track, called *latest*. Most operations and commands +within Snapcraft and the snap ecosystem assume this track, unless otherwise +specified. If a snap has need for other tracks, they must be vetted and granted +on a snap-by-snap basis by the Snap Store team. The process for requesting a +track is outlined in `Process for aliases, auto-connections and tracks +`_. + +The release semantics for a track is at the snap author's discretion. A track +could, for examples, encompass minor updates, major updates, or long-term +support releases. Or, it could signify something else entirely. Risk @@ -59,10 +64,3 @@ Branch names convey their purpose, such as ``fix-for-bug123``. Branch names are not, however, discoverable in the Snap Store. Instead, they must be shared by authors to users and referenced by their exact name. If a snap branch has no new publications for 30 days, the Snap Store closes its branch. - - -See also --------- - -`Request process for custom tracks -`_