From 5c73e84196b3c6d330d111dafa207e1d621384d9 Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Fri, 8 Sep 2023 13:36:26 -0500 Subject: [PATCH] feedback from PR: many improvements Signed-off-by: Callahan Kovacs --- docs/explanation/architectures.rst | 42 ++++++++++++---- docs/howto/architectures.rst | 79 ++++++++++++++++-------------- docs/reference/architectures.rst | 74 +++++++++++++++++++++++----- 3 files changed, 136 insertions(+), 59 deletions(-) diff --git a/docs/explanation/architectures.rst b/docs/explanation/architectures.rst index 2f7d4f2938..48622eb426 100644 --- a/docs/explanation/architectures.rst +++ b/docs/explanation/architectures.rst @@ -46,10 +46,10 @@ Consider the following ``snapcraft.yaml`` snippet: .. code-block:: yaml architectures: - - build-on: amd64 - build-for: amd64 + - build-on: [amd64] + build-for: [amd64] - build-on: [amd64, arm64] - build-for: arm64 + build-for: [arm64] If snapcraft executes on an ``amd64`` machine, then it will create the following build plan: @@ -63,6 +63,16 @@ following build plan: Two snap files will be created: ``my-snap_1.0_amd64.snap`` and ``my-snap_1.0_arm64.snap``. +If snapcraft executes on an ``arm64`` machine, then it will create the +following build plan: + +.. code-block:: text + + Created build plan: + build-on: arm64 build-for: arm64 + +One snap file will be created: ``my-snap_1.0_arm64.snap``. + This build plan can be filtered with the environment variable ``SNAPCRAFT_BUILD_FOR=`` or the command-line argument ``--build-for=``. The command-line argument takes priority over the @@ -80,7 +90,7 @@ Destructive mode In destructive mode, all builds in the build plan occur in the same location. This can cause unintended consequences, such as parts not being re-built. For -more information, see `this issue`_. +more information, see `this issue `_. To workaround this, use ``--build-for`` or ``SNAPCRAFT_BUILD_FOR`` to build one snap at a time and run ``snapcraft clean --destructive-mode`` when changing @@ -108,6 +118,18 @@ build the snap on all architectures If architectures are defined in the ``snapcraft.yaml``, then Launchpad will build the snap on all ``build-on`` architectures. +When a snap can be built on multiple architectures, Launchpad can choose which +``build-on`` platform to use. For example: + +.. code-block:: yaml + + architectures: + - build-on: [amd64, arm64] + build-for: [ppc64el] + +Launchpad may build the snap on an ``amd64`` or ``arm64`` platform. This choice +is controlled by Launchpad and cannot be influenced by the user. + Architecture errors ------------------- @@ -124,7 +146,7 @@ Could not make build plan This ``core22`` error has two common causes. The first cause is that snapcraft is not able to create a build plan because -the there are no build-on architectures matching the host's architecture. +the there are no ``build-on`` architectures matching the host's architecture. To resolve this, build the snap on an architecture listed in the ``snapcraft.yaml`` or add the host architecture as a ``build-on`` value. @@ -135,7 +157,7 @@ with brackets. For example: architectures: - build-on: amd64, arm64 - build-for: arm64 + build-for: [arm64] should be changed to: @@ -143,10 +165,10 @@ should be changed to: architectures: - build-on: [amd64, arm64] - build-for: arm64 + build-for: [arm64] The brackets are required for lists. This problem is described in -more detail `here`_. +more detail `here `_. Unsupported architectures in remote build ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -164,5 +186,5 @@ architectures supported by Launchpad. The second cause is the same :ref:`as above` - not enclosing a list of multiple architectures with brackets. -.. _`here`: https://github.com/snapcore/snapcraft/issues/4340 -.. _`this issue`: https://github.com/snapcore/snapcraft/issues/4356 +.. _`issue 4340`: https://github.com/snapcore/snapcraft/issues/4340 +.. _`issue 4356`: https://github.com/snapcore/snapcraft/issues/4356 diff --git a/docs/howto/architectures.rst b/docs/howto/architectures.rst index 34840e8996..503dd9e8b9 100644 --- a/docs/howto/architectures.rst +++ b/docs/howto/architectures.rst @@ -21,8 +21,8 @@ core22 .. code-block:: yaml architectures: - - build-on: amd64 - build-for: amd64 + - build-on: [amd64] + build-for: [amd64] Building on ``amd64`` will produce one snap built for ``amd64``. Snapcraft will raise an error when building on another architecture. @@ -33,7 +33,7 @@ following snippet snippet will produce the same result: .. code-block:: yaml architectures: - - build-on: amd64 + - build-on: [amd64] The shorthand format will also produce the same result: @@ -48,8 +48,8 @@ core20 .. code-block:: yaml architectures: - - build-on: amd64 - run-on: amd64 + - build-on: [amd64] + run-on: [amd64] Building on ``amd64`` will produce one snap built for ``amd64``. Snapcraft will not raise an error when building on another architecture. Instead, it will @@ -61,7 +61,7 @@ following snippet snippet will produce the same result: .. code-block:: yaml architectures: - - build-on: amd64 + - build-on: [amd64] The shorthand format will also produce the same result: @@ -79,10 +79,10 @@ core22 .. code-block:: yaml architectures: - - build-on: amd64 - build-for: amd64 - - build-on: arm64 - build-for: arm64 + - build-on: [amd64] + build-for: [amd64] + - build-on: [arm64] + build-for: [arm64] Building on ``amd64`` will produce one snap for ``amd64``. Building on ``arm64`` will produce one snap for ``arm64``. Snapcraft will raise an error when building @@ -94,16 +94,14 @@ following snippet snippet will produce the same result: .. code-block:: yaml architectures: - - build-on: amd64 - - build-on: arm64 + - build-on: [amd64] + - build-on: [arm64] The shorthand format will also produce the same result: .. code-block:: yaml - architectures: - - amd64 - - arm64 + architectures: [amd64, arm64] core20 ^^^^^^ @@ -111,10 +109,10 @@ core20 .. code-block:: yaml architectures: - - build-on: amd64 - run-on: amd64 - - build-on: arm64 - run-on: arm64 + - build-on: [amd64] + run-on: [amd64] + - build-on: [arm64] + run-on: [arm64] Building on ``amd64`` will produce one snap built for ``amd64``. Building on ``arm64`` will produce one snap built for ``arm64``. Snapcraft will not raise @@ -134,21 +132,26 @@ The shorthand format will also produce the same result: .. code-block:: yaml - architectures: - - amd64 - - arm64 + architectures: [amd64, arm64] + +.. _how-to-arch-build-for-all: How to create an architecture independent snap ---------------------------------------------- +``build-for: [all]`` is used for a snap that can run on all architectures, like +a snap that is a shell or python script. It cannot be combined with other +architectures. Click :ref:`here` for more information on +the ``all`` keyword. + core22 ^^^^^^ .. code-block:: yaml architectures: - - build-on: amd64 - build-for: all + - build-on: [amd64] + build-for: [all] core20 ^^^^^^ @@ -156,8 +159,8 @@ core20 .. code-block:: yaml architectures: - - build-on: amd64 - run-on: all + - build-on: [amd64] + run-on: [all] How to create a cross-compiling snap ------------------------------------ @@ -168,8 +171,8 @@ core22 .. code-block:: yaml architectures: - - build-on: amd64 - build-for: arm64 + - build-on: [amd64] + build-for: [arm64] Building on ``amd64`` will produce one snap built for ``arm64``. Snapcraft will raise an error when building on another architecture. @@ -179,10 +182,10 @@ raise an error when building on another architecture. .. code-block:: yaml architectures: - - build-on: amd64 - build-for: amd64 + - build-on: [amd64] + build-for: [amd64] - build-on: [amd64, arm64] - build-for: arm64 + build-for: [arm64] Building on ``amd64`` will produce two snaps, one built for ``amd64`` and one built for ``arm64``. Building on ``arm64`` will produce one snap built for @@ -194,8 +197,8 @@ core20 .. code-block:: yaml architectures: - - build-on: amd64 - run-on: arm64 + - build-on: [amd64] + run-on: [arm64] Building on ``amd64`` will produce one snap built for ``arm64``. Snapcraft will not raise an error when building on another architecture. Instead, it will @@ -213,7 +216,8 @@ To use an ``i386`` package for an ``amd64`` snap, use the following .. code-block:: yaml architectures: - - build-on: amd64 + - build-on: [amd64] + build-for: [amd64] package-repositories: - type: apt @@ -229,6 +233,7 @@ To use an ``i386`` package for an ``amd64`` snap, use the following stage-packages: - libpython3.11-minimal:i386 -This is supported for related architectures. ``amd64`` and ``i386`` can stage -packages for each other. ``arm64`` and ``armhf`` can also stage packages for -each other. +This is supported for related architectures. A snap built for ``amd64`` can +stage ``i386`` packages and a snap built for ``i386`` can stage ``amd64`` +packages. Similarly, a snap built for ``arm64`` can stage ``armhf`` packages +and a snap built for ``armhf`` can stage ``amd64`` packages. diff --git a/docs/reference/architectures.rst b/docs/reference/architectures.rst index a839d255fd..fef00ad2aa 100644 --- a/docs/reference/architectures.rst +++ b/docs/reference/architectures.rst @@ -22,8 +22,21 @@ pairs with the following syntax: build-for: [] ... -If the value is a single item, it can be simplified from a list to a scalar. -For example: +See :ref:`here` for a list of supported architectures. + +Data types +"""""""""" + +If the value is a single item, it can be written as a single element list or a +scalar. For example: + +.. code-block:: yaml + + architectures: + - build-on: amd64 + build-for: arm64 + +is equivalent to: .. code-block:: yaml @@ -31,25 +44,62 @@ For example: - build-on: [amd64] build-for: [arm64] -can be rewritten as: +.. note:: + + Using a list is the recommended syntax. Scalars are not recommended. + +``build-on`` +"""""""""""" + +The ``build-on`` field is required and can contain multiple architectures. + +.. _reference-build-for: + +``build-for`` +""""""""""""" + +The ``build-for`` field is optional and should be a single element list. If it +is not defined, the ``build-for`` will be set the ``build-on`` for each build +in the :ref:`build plan`. + +``build-for: [all]`` is a special keyword to denote an architecture-independent +snap. If the ``all`` keyword is used, no other ``build-on/build-for`` pairs can +be defined. See :ref:`this page` to learn how to +use the ``all`` keyword. + +``all`` cannot be used for ``build-on``. + +The same architecture cannot be defined in multiple ``build-for`` entries. + +Shorthand format +"""""""""""""""" + +As an alternative to the explicit format described above, a shorthand format +can be used for simple ``build-on/build-for`` pairs. The following shorthand: .. code-block:: yaml - architectures: - - build-on: amd64 - build-for: arm64 + architectures: [amd64, arm64] -See :ref:`here` for a list of supported architectures. +is equivalent to: -``build-for: all`` can be used for snaps that can run on all architectures, -like a snap that is a shell or python script. It cannot be combined with other -architectures. +.. code-block:: yaml + + architectures: + - build-on: [amd64] + build-for: [amd64] + - build-on: [arm64] + build-for: [arm64] + +The explicit and shorthand format cannot be mixed. core20 ^^^^^^ The above syntax and rules for ``core22`` apply for ``core20`` except that -``run-on`` is used in place of ``build-for``. +``run-on`` is used in place of ``build-for``. Additionally, ``core20`` supports +multiple architectures in the ``run-on`` field, which will create +multi-architecture snaps. Project variables ----------------- @@ -146,9 +196,9 @@ Supported by Launchpad The following architectures are supported by Launchpad for remote building. +* amd64 * arm64 * armhf -* amd64 * ppc64el * s390x