From 2df2881d797d24af7cc9fde8e9c576883d0d3dd6 Mon Sep 17 00:00:00 2001 From: Michael DuBelko Date: Fri, 13 Dec 2024 07:02:38 -0800 Subject: [PATCH] docs: port the how-to/quickstart chapter from discourse (#5176) Co-authored-by: Callahan Co-authored-by: Alex Lowe --- docs/howto/index.rst | 2 + docs/howto/select-a-build-provider.rst | 93 +++++++ docs/howto/set-up-snapcraft.rst | 185 +++++++++++++ docs/reference/anatomy-of-a-recipe.rst | 305 +++++++++++++++++++++ docs/reference/channels.rst | 66 +++++ 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 | 132 +++++++++ docs/reference/snap-publishing-process.rst | 17 ++ docs/reference/system-requirements.rst | 42 +++ 11 files changed, 916 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..b32970d213 --- /dev/null +++ b/docs/howto/select-a-build-provider.rst @@ -0,0 +1,93 @@ +.. _select-a-build-provider: + +Select a build provider +======================= + +Depending on the core version and platform, there are different default build +providers and multiple ways to change providers. The following tables are +ranked by precedence across cores, so for example a provider chosen by the +first method overrides the second and third method, and so on. + +Consult the following tables for different methods of overriding the build +provider. + + +core22 and higher override methods +---------------------------------- + +For core22 and higher, LXD is the default provider on Linux, and Multipass is +the default on macOS and Windows. + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Provider override for core22 and higher + - Priority + - Command + * - Command-line argument + - 1 + - ``--use-lxd`` + * - Environmental variable + - 2 + - ``SNAPCRAFT_BUILD_ENVIRONMENT=`` + * - Snap configuration of Snapcraft + - 3 + - ``snap set snapcraft provider=`` + + +core20 override methods +----------------------- + +For core20, Multipass is the default provider on all platforms. + +.. list-table:: + :header-rows: 1 + :widths: 1 1 1 + + * - Provider override for core20 + - Priority + - Command + * - Command-line argument + - 1 + - ``--provider=`` + * - Environmental variable + - 2 + - ``SNAPCRAFT_BUILD_ENVIRONMENT=`` + * - Command-line argument + - 3 + - ``--use-lxd`` + * - Snap configuration of Snapcraft + - 4 + - ``snap set snapcraft provider=`` + + +Select through the snap 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..0608341c2f --- /dev/null +++ b/docs/howto/set-up-snapcraft.rst @@ -0,0 +1,185 @@ +.. _install-snapcraft: + +Set up Snapcraft +================ + +Snapcraft can be installed on all popular Linux distributions with systemd, +macOS, and Windows. + +Before you begin installation and setup, make sure your system meets the +:ref:`system requirements `. + + +Install the main components +--------------------------- + +A working Snapcraft setup has two components -- Snapcraft itself, and a build +provider. + + +Install Snapcraft +~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. group-tab:: Linux + + If your Linux distribution has snapd installed, the easiest way to install + Snapcraft is from the Snap Store: + + .. code:: bash + + sudo snap install snapcraft --classic + + + .. group-tab:: macOS + + #. `Install Brew `_. + #. 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. + + +Choose 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. + +If the default build provider isn't fit for your snap, you can +:ref:`switch between them `. + + +Install Multipass +^^^^^^^^^^^^^^^^^ + +If Multipass isn't installed, on first run Snapcraft will ask you'd like to +automatically install and configure it. If you agree, it will walk you through +installation. + +.. If Multipass isn't installed while running in a non-interactive mode +.. (running from a CI/CD pipeline), snapcraft will log an error and exit. + +To install Multipass on its own, run: + +.. code:: bash + + sudo snap install multipass + +.. tip:: + + With core20 snaps and Multipass, the default virtual machine is assigned 2 + CPUs and 2GB of RAM. To extend the hardware capacity, you can set the + following environment variables to modify CPU and memory allocation, and + improve performance: + + .. code:: bash + + export SNAPCRAFT_BUILD_ENVIRONMENT_CPU=8 + export SNAPCRAFT_BUILD_ENVIRONMENT_MEMORY=16G + + +Install LXD +^^^^^^^^^^^ + +To install LXD: + +#. Install the app: + + .. code:: bash + + sudo snap install lxd + +#. Add your user account to the ``lxd`` group so you can access the tool's + resources: + + .. code:: bash + + sudo usermod -a -G lxd $USER + +#. Log out and back in to your account for the new group to become + active. Then, check that you're a member of the group by running: + + .. code:: bash + + groups $USER + + ``lxd`` should be present in the output. + +#. Finally, initialise LXD with a lightweight, default configuration: + + .. code:: bash + + lxd init --minimal + +See `How to install LXD +`_ in +the LXD documentation for further installation options and troubleshooting. + + +Install multiple instances of Snapcraft +--------------------------------------- + +If you're installing Snapcraft as a snap, you can install multiple concurrent +versions at the same time. Doing so could come in handy if you want to test new +features in your snaps, before they arrive in a mainstream release. + +To install another instance of Snapcraft: + +#. Enable parallel installs in snapd: + + .. code:: bash + + sudo snap set system experimental.parallel-instances=true + +#. List all the available versions of Snapcraft. For the version you're + interested in, take note of the value in the channel column. + + .. code:: bash + + sudo snap info snapcraft + +#. Install Snapcraft using the `instance key naming + `_ syntax. + Replace ``edge`` with whichever name is appropriate for the instance, and + ``latest/edge`` with the target channel and track: + + .. code:: bash + + sudo snap install snapcraft_edge latest/edge --classic + +Whenever you want to run this parallel version of Snapcraft, invoke the +instance name of the command -- in this example, ``snapcraft_edge``. diff --git a/docs/reference/anatomy-of-a-recipe.rst b/docs/reference/anatomy-of-a-recipe.rst new file mode 100644 index 0000000000..aeebead05b --- /dev/null +++ b/docs/reference/anatomy-of-a-recipe.rst @@ -0,0 +1,305 @@ +.. _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. + +The ``description`` key describes the software in full. It also accepts +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 +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 :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 +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 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: + +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 :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 +~~~~~ + +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..3ec2c50db4 --- /dev/null +++ b/docs/reference/channels.rst @@ -0,0 +1,66 @@ +.. _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 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 +---- + +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..c502e0bc4c --- /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: | + 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 }')" + # 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..6b02ac8c16 --- /dev/null +++ b/docs/reference/snap-build-process.rst @@ -0,0 +1,132 @@ +.. _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 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 +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..90a0755934 --- /dev/null +++ b/docs/reference/system-requirements.rst @@ -0,0 +1,42 @@ +.. _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 +----------------------------- + +- 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 + + +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 `_