From 54210cc0e48c34c2913674efe5a805e05a4b130d Mon Sep 17 00:00:00 2001 From: Callahan Kovacs Date: Wed, 10 Jul 2024 07:54:27 -0500 Subject: [PATCH] docs: add explanation, howto, and reference for components Signed-off-by: Callahan Kovacs --- docs/conf.py | 1 - docs/explanation/components.rst | 53 ++++++++++++ docs/explanation/index.rst | 1 + docs/howto/code/basic/snapcraft.yaml | 11 +++ docs/howto/code/basic/src/my-app | 0 docs/howto/code/basic/task.yaml | 15 ++++ .../code/components-organize/snapcraft.yaml | 24 ++++++ .../howto/code/components-organize/src/my-app | 0 docs/howto/code/components-organize/task.yaml | 17 ++++ .../code/components-organize/translations/la | 0 docs/howto/code/components/snapcraft.yaml | 22 +++++ docs/howto/code/components/src/my-app | 0 docs/howto/code/components/task.yaml | 17 ++++ docs/howto/code/components/translations/la | 0 docs/howto/components.rst | 84 +++++++++++++++++++ docs/howto/index.rst | 1 + docs/reference/components.rst | 10 +++ docs/reference/index.rst | 1 + docs/reuse/components-intro.rst | 3 + docs/reuse/links.txt | 2 +- spread.yaml | 7 ++ 21 files changed, 267 insertions(+), 2 deletions(-) create mode 100644 docs/explanation/components.rst create mode 100644 docs/howto/code/basic/snapcraft.yaml create mode 100644 docs/howto/code/basic/src/my-app create mode 100644 docs/howto/code/basic/task.yaml create mode 100644 docs/howto/code/components-organize/snapcraft.yaml create mode 100644 docs/howto/code/components-organize/src/my-app create mode 100644 docs/howto/code/components-organize/task.yaml create mode 100644 docs/howto/code/components-organize/translations/la create mode 100644 docs/howto/code/components/snapcraft.yaml create mode 100644 docs/howto/code/components/src/my-app create mode 100644 docs/howto/code/components/task.yaml create mode 100644 docs/howto/code/components/translations/la create mode 100644 docs/howto/components.rst create mode 100644 docs/reference/components.rst create mode 100644 docs/reuse/components-intro.rst diff --git a/docs/conf.py b/docs/conf.py index 4319d3b3ba..9e456ae914 100644 --- a/docs/conf.py +++ b/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", diff --git a/docs/explanation/components.rst b/docs/explanation/components.rst new file mode 100644 index 0000000000..d43c61c690 --- /dev/null +++ b/docs/explanation/components.rst @@ -0,0 +1,53 @@ +Components +********** + +.. include:: /reuse/components-intro.rst + +.. _components-and-partitions: + +Components and Partitions +------------------------- + +Components utilize a `Craft Parts`_ feature called ``partitions``. This feature +is enabled only when a ``components`` keyword is defined. + +Each component has a namespaced partition ``component/`` where +``component`` is the partition's namespace and ```` 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 organized 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 outputs 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. diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst index 2368e0e3dd..2d198a0a16 100644 --- a/docs/explanation/index.rst +++ b/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 diff --git a/docs/howto/code/basic/snapcraft.yaml b/docs/howto/code/basic/snapcraft.yaml new file mode 100644 index 0000000000..ac99b79269 --- /dev/null +++ b/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 diff --git a/docs/howto/code/basic/src/my-app b/docs/howto/code/basic/src/my-app new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/howto/code/basic/task.yaml b/docs/howto/code/basic/task.yaml new file mode 100644 index 0000000000..b0c6ce6284 --- /dev/null +++ b/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 diff --git a/docs/howto/code/components-organize/snapcraft.yaml b/docs/howto/code/components-organize/snapcraft.yaml new file mode 100644 index 0000000000..a6e6e10389 --- /dev/null +++ b/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) diff --git a/docs/howto/code/components-organize/src/my-app b/docs/howto/code/components-organize/src/my-app new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/howto/code/components-organize/task.yaml b/docs/howto/code/components-organize/task.yaml new file mode 100644 index 0000000000..eadbbb3537 --- /dev/null +++ b/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 diff --git a/docs/howto/code/components-organize/translations/la b/docs/howto/code/components-organize/translations/la new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/howto/code/components/snapcraft.yaml b/docs/howto/code/components/snapcraft.yaml new file mode 100644 index 0000000000..0065eb7df1 --- /dev/null +++ b/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 diff --git a/docs/howto/code/components/src/my-app b/docs/howto/code/components/src/my-app new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/howto/code/components/task.yaml b/docs/howto/code/components/task.yaml new file mode 100644 index 0000000000..eadbbb3537 --- /dev/null +++ b/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 diff --git a/docs/howto/code/components/translations/la b/docs/howto/code/components/translations/la new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/howto/components.rst b/docs/howto/components.rst new file mode 100644 index 0000000000..4b1321ef37 --- /dev/null +++ b/docs/howto/components.rst @@ -0,0 +1,84 @@ +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 diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 5800799951..f8195707c2 100644 --- a/docs/howto/index.rst +++ b/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 diff --git a/docs/reference/components.rst b/docs/reference/components.rst new file mode 100644 index 0000000000..5b1cd7bdb5 --- /dev/null +++ b/docs/reference/components.rst @@ -0,0 +1,10 @@ +Components +********** + +.. include:: /reuse/components-intro.rst + +Components utilize a `Craft Parts`_ feature called ``partitions``. See +:ref:`component and partitions` for an explanation +on how they are related. + +.. include:: /common/craft-parts/reference/partition_specific_output_directory_variables.rst diff --git a/docs/reference/index.rst b/docs/reference/index.rst index 5bafe6f180..eea31a7d61 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -8,6 +8,7 @@ Reference architectures commands + components plugins /common/craft-parts/reference/part_properties parts_steps diff --git a/docs/reuse/components-intro.rst b/docs/reuse/components-intro.rst new file mode 100644 index 0000000000..bd0a4b6682 --- /dev/null +++ b/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. diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt index a299bf6a1f..f6901970e2 100644 --- a/docs/reuse/links.txt +++ b/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/ - diff --git a/spread.yaml b/spread.yaml index 9eef183a25..6a8bac5692 100644 --- a/spread.yaml +++ b/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