docs: add explanation, howto, and reference for components

docs/conf.py

@@ -67,7 +67,6 @@
     "common/craft-parts/explanation/overlay_parameters.rst",
     "common/craft-parts/explanation/overlays.rst",
     "common/craft-parts/how-to/craftctl.rst",
-    "common/craft-parts/reference/partition_specific_output_directory_variables.rst",
     "common/craft-parts/reference/parts_steps.rst",
     "common/craft-parts/reference/step_execution_environment.rst",
     "common/craft-parts/reference/step_output_directories.rst",

docs/explanation/components.rst

@@ -0,0 +1,65 @@
+Components
+**********
+
+.. include:: /reuse/components-intro.rst
+
+Components are useful for distributing optional resources alongside a snap. For
+example, debug symbols are useful for the developer of an application and are
+closely linked to a particular build of an application. Debug symbols are not
+useful for the users. Including debug symbols in a snap package would waste
+user's network bandwidth and disk space. If an application packages debug
+symbols as a component alongside the snap, then the developers who require
+debug symbols can download and install them as a component.
+
+.. note::
+
+   Components are under development and not production ready.
+
+.. _components-and-partitions:
+
+Components and Partitions
+-------------------------
+
+Components utilise a `Craft Parts`_ feature called ``partitions``. This feature
+is enabled only when the ``component`` keyword is defined in the project file.
+
+Each component has a namespaced partition ``component/<component-name>`` where
+``component`` is the partition's namespace and ``<component-name>`` is the name
+of the component from the ``snapcraft.yaml`` file.
+
+The partition for the snap itself is known as the ``default`` partition.
+
+Component lifecycle directories
+-------------------------------
+
+When a part is built, the output is the default partition's install directory
+for that part.
+
+Each component has a partition. This means each component has its own install,
+stage, and prime directories. When a file is organised into a component's
+partition, it is moved to the part's install directory for that component's
+partition.
+
+For example, consider a part with the ``organize`` keyword:
+
+.. code-block:: yaml
+
+    parts:
+      my-part:
+        plugin: nil
+        override-build: |
+          touch $CRAFT_PART_INSTALL/hello
+        organize:
+          hello: (component/translations)/hello-world
+
+This part's build creates a file called ``hello`` in ``my-part``'s default
+install directory. If no ``organize`` keyword was used, this file would be
+included in the snap itself.
+
+However this example uses the ``organize`` keyword to move the file ``hello``
+from ``my-part``'s default install directory to ``my-parts``'s install
+directory for the ``translations`` component. It also renames the file from
+``hello`` to ``hello-world``.
+
+The packed snap will contain nothing from this part and the ``translations``
+component will contain the ``hello-world`` file.

docs/explanation/index.rst

@@ -7,6 +7,7 @@ Explanation
    :maxdepth: 1
 
    architectures
+   components
    remote-build
    /common/craft-parts/explanation/filesets
    /common/craft-parts/explanation/parts

docs/howto/code/basic/snapcraft.yaml

@@ -0,0 +1,11 @@
+name: hello-components
+version: "1.0"
+summary: A snap with a component
+description: A simple snap with a component containing translations
+base: core24
+confinement: strict
+
+parts:
+  application:
+    source: src
+    plugin: dump

docs/howto/code/basic/task.yaml

@@ -0,0 +1,15 @@
+summary: test the "How to package and upload a snap with components"
+
+restore:
+  rm -r *.snap
+
+execute: |
+  unset SNAPCRAFT_BUILD_ENVIRONMENT
+
+  snapcraft pack
+
+  # assert artefacts were packed
+  if [ ! -e "hello-components_1.0_amd64.snap" ]; then
+    echo "snap was not packed"
+    exit 1
+  fi

docs/howto/code/components-organize/snapcraft.yaml

@@ -0,0 +1,24 @@
+name: hello-components
+version: "1.0"
+summary: A snap with a component
+description: A simple snap with a component containing translations
+base: core24
+confinement: strict
+
+components:
+  translations:
+    type: test
+    summary: Translations modules
+    description: Translations modules
+    version: "1.0"
+
+parts:
+  application:
+    source: src
+    plugin: dump
+
+  translations:
+    source: translations
+    plugin: dump
+    organize:
+      la: (component/translations)

docs/howto/code/components-organize/task.yaml

@@ -0,0 +1,17 @@
+summary: test the "How to package and upload a snap with components"
+
+restore:
+  rm -r *.snap *.comp
+
+execute: |
+  unset SNAPCRAFT_BUILD_ENVIRONMENT
+
+  # [docs:pack]
+  snapcraft pack
+  # [docs:pack-end]
+
+  # assert artefacts were packed
+  if [ ! -e "hello-components_1.0_amd64.snap" ] || [ ! -e "hello-components+translations_1.0.comp" ]; then
+    echo "snap and components were not packed"
+    exit 1
+  fi

docs/howto/code/components/snapcraft.yaml

@@ -0,0 +1,22 @@
+name: hello-components
+version: "1.0"
+summary: A snap with a component
+description: A simple snap with a component containing translations
+base: core24
+confinement: strict
+
+components:
+  translations:
+    type: test
+    summary: Translations modules
+    description: Translations modules
+    version: "1.0"
+
+parts:
+  application:
+    source: src
+    plugin: dump
+
+  translations:
+    source: translations
+    plugin: dump

docs/howto/code/components/task.yaml

@@ -0,0 +1,17 @@
+summary: test the "How to package and upload a snap with components"
+
+restore:
+  rm -r *.snap *.comp
+
+execute: |
+  unset SNAPCRAFT_BUILD_ENVIRONMENT
+
+  # [docs:pack]
+  snapcraft pack
+  # [docs:pack-end]
+
+  # assert artefacts were packed
+  if [ ! -e "hello-components_1.0_amd64.snap" ] || [ ! -e "hello-components+translations_1.0.comp" ]; then
+    echo "snap and components were not packed"
+    exit 1
+  fi

docs/howto/components.rst

@@ -0,0 +1,88 @@
+How to package and upload a snap with components
+************************************************
+
+.. include:: /reuse/components-intro.rst
+
+Start with a simple ``snapcraft.yaml``:
+
+.. literalinclude:: code/basic/snapcraft.yaml
+    :language: yaml
+
+And create the following project tree:
+
+.. code-block::
+
+   .
+   └── src
+       └── my-app
+
+``my-app`` can be an empty file. The contents are not important for this
+how-to guide.
+
+To create a component, define a component called ``translations`` under
+a new top-level ``components`` keyword. We will also add a new part that
+dumps the contents of the ``translations`` directory:
+
+.. literalinclude:: code/components/snapcraft.yaml
+    :language: yaml
+
+Next, create a ``translations`` directory with a file called ``la``:
+
+.. code-block::
+
+   .
+   ├── src
+   │   └── my-app
+   └── translations
+       └── la
+
+``la`` can also be an empty file.
+
+Pack the snap with:
+
+.. literalinclude:: code/components/task.yaml
+    :language: shell
+    :start-after: [docs:pack]
+    :end-before: [docs:pack-end]
+    :dedent: 2
+
+This will produce 2 artefacts, the snap and the component:
+
+* ``hello-components_1.0_amd64.snap``
+* ``hello-components+translations_1.0.comp``
+
+The ``my-app`` and ``la`` files are staged, primed, and packed in the snap
+artefact. The component artefact has no payload. It is empty except for a
+metadata file ``meta/component.yaml``.
+
+To move the ``la`` translation file to the ``component`` artefact, use the
+``organize`` keyword for the ``translations`` part:
+
+.. literalinclude:: code/components-organize/snapcraft.yaml
+    :language: yaml
+
+The parentheses around ``(component/translations)`` indicate that the files
+should be organized into the translations component's install directory.
+
+Pack the snap again with:
+
+.. literalinclude:: code/components/task.yaml
+    :language: shell
+    :start-after: [docs:pack]
+    :end-before: [docs:pack-end]
+    :dedent: 2
+
+This will produce two artefacts again but the component now contains the
+``la`` translation file.
+
+To upload the snap and the component to the store, specify the snap file
+and the component file for the ``translations`` component.
+
+.. code-block:: shell
+
+   snapcraft upload hello-components_1.0_amd64.snap \
+     --component translations=hello-components+translations_1.0.comp
+
+The store expects a snap and its components to be uploaded together.
+
+The component has to be uploaded alongside the snap.

docs/howto/index.rst

@@ -7,5 +7,6 @@ How-to guides
    :maxdepth: 1
 
    architectures
+   components
    /common/craft-parts/how-to/include_files
    /common/craft-parts/how-to/override_build

docs/reference/components.rst

@@ -0,0 +1,10 @@
+Components
+**********
+
+.. include:: /reuse/components-intro.rst
+
+Components employ a `Craft Parts`_ feature called ``partitions``. See
+:ref:`component and partitions<components-and-partitions>` for an explanation
+on how they are related.
+
+.. include:: /common/craft-parts/reference/partition_specific_output_directory_variables.rst

docs/reference/index.rst

@@ -8,6 +8,7 @@ Reference
 
    architectures
    commands
+   components
    plugins
    /common/craft-parts/reference/part_properties
    parts_steps

docs/reuse/components-intro.rst

@@ -0,0 +1,3 @@
+Components are parts of a snap that can be built and uploaded in conjunction
+with a snap and later optionally installed beside it. Components are defined
+with a top-level ``components`` keyword in a snapcraft.yaml.

docs/reuse/links.txt

@@ -2,6 +2,7 @@
 .. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
 .. _Canonical website: https://canonical.com/
 .. _`Charmcraft`: https://juju.is/docs/sdk/charmcraft
+.. _`Craft Parts`: https://canonical-craft-parts.readthedocs-hosted.com/en/latest/
 .. _`Create a brand account`: https://snapcraft.io/docs/t/creating-snap-store-brand-accounts/6271
 .. _`Kernel connector`: https://www.kernel.org/doc/Documentation/connector/connector.txt
 .. _managing-snap-configuration: https://snapcraft.io/docs/configuration-in-snaps
@@ -18,4 +19,3 @@
 .. _`Ubuntu Core`: https://ubuntu.com/core/
 .. _vscode: https://code.visualstudio.com/
 .. _`YAML specification`: https://yaml.org/spec/
-

spread.yaml

@@ -376,8 +376,15 @@ suites:
      sudo apt-get install git
      sudo apt-mark auto git
 
+ docs/howto/code/:
+   summary: tests how-to guides from the docs
+   systems:
+   - ubuntu-24.04-64
+
+
 path: /snapcraft/
 include:
+  - docs/
   - tests/
   - requirements.txt
   - requirements-devel.txt