feedback from PR: many improvements

Signed-off-by: Callahan Kovacs <[email protected]>

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=<arch>`` or the command-line argument
 ``--build-for=<arch>``. 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 <issue 4356_>`_.
 
 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,18 +157,18 @@ with brackets. For example:
 
   architectures:
     - build-on: amd64, arm64
-      build-for: arm64
+      build-for: [arm64]
 
 should be changed to:
 
 .. code-block:: yaml
 
   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 <issue 4340_>`_.
 
 Unsupported architectures in remote build
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -164,5 +186,5 @@ architectures supported by Launchpad.
 The second cause is the same :ref:`as above<build-plan-error>` - 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

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,27 +94,25 @@ 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
 ^^^^^^
 
 .. 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,30 +132,35 @@ 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<reference-build-for>` 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
 ^^^^^^
 
 .. 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.

docs/reference/architectures.rst

@@ -22,34 +22,84 @@ pairs with the following syntax:
       build-for: [<arch 4>]
       ...
 
-If the value is a single item, it can be simplified from a list to a scalar.
-For example:
+See :ref:`here<supported-architectures>` 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
 
   architectures:
     - 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-plans>`.
+
+``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<how-to-arch-build-for-all>` 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<supported-architectures>` 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