diff --git a/docs/howto/index.rst b/docs/howto/index.rst index 48646b6b71..6d39896d13 100644 --- a/docs/howto/index.rst +++ b/docs/howto/index.rst @@ -12,5 +12,6 @@ How-to guides architectures bases components + use-extensions/index /common/craft-parts/how-to/include_files /common/craft-parts/how-to/override_build diff --git a/docs/howto/use-extensions/enable-experimental-extensions.rst b/docs/howto/use-extensions/enable-experimental-extensions.rst new file mode 100644 index 0000000000..4d15be34fc --- /dev/null +++ b/docs/howto/use-extensions/enable-experimental-extensions.rst @@ -0,0 +1,14 @@ +.. _enable-experimental-extensions: + +Enable experimental extensions +============================== + +Some extensions aren't as refined or well-tested, and are flagged as experimental. They +aren't available by default. + +If you're comfortable with using experimental extensions and understand the risks, you +can use them by exporting the following environment variable before running Snapcraft: + +.. code-block:: bash + + SNAPCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=1 diff --git a/docs/howto/use-extensions/index.rst b/docs/howto/use-extensions/index.rst new file mode 100644 index 0000000000..efa36a717c --- /dev/null +++ b/docs/howto/use-extensions/index.rst @@ -0,0 +1,18 @@ +.. _use-extensions: + +Use extensions +============== + +This section contains usage information for :ref:`extensions`. + +It covers general usage, as well as special guidance for particular extensions. + + +.. toctree:: + :hidden: + + use-an-extension + list-extensions + enable-experimental-extensions + use-the-env-injector-extension + use-the-gnome-extension diff --git a/docs/howto/use-extensions/list-extensions.rst b/docs/howto/use-extensions/list-extensions.rst new file mode 100644 index 0000000000..e55dbe603d --- /dev/null +++ b/docs/howto/use-extensions/list-extensions.rst @@ -0,0 +1,16 @@ +.. _list-extensions: + +List extensions +=============== + +Different versions of Snapcraft and its various cores support different extensions. To +list all extensions supported by the installed version of Snapcraft, run: + +.. code-block:: bash + + snapcraft list-extensions + +The output includes all extensions, both stable and experimental, without +differentiating them. + +For the full reference for this command, see :ref:`ref_commands_list-extensions`. diff --git a/docs/howto/use-extensions/use-an-extension.rst b/docs/howto/use-extensions/use-an-extension.rst new file mode 100644 index 0000000000..0240f83674 --- /dev/null +++ b/docs/howto/use-extensions/use-an-extension.rst @@ -0,0 +1,15 @@ +.. _use-an-extension: + +Use an extension +================ + +To use an extension in an app, list it in the app's ``extensions`` key in the snap's +project file. Here's an example of an app using the KDE neon 6 extension: + +.. code:: yaml + + apps: + kcalc: + command: usr/bin/kcalc + extensions: + - kde-neon-6 diff --git a/docs/howto/use-extensions/use-the-env-injector-extension.rst b/docs/howto/use-extensions/use-the-env-injector-extension.rst new file mode 100644 index 0000000000..efba8c45e0 --- /dev/null +++ b/docs/howto/use-extensions/use-the-env-injector-extension.rst @@ -0,0 +1,165 @@ +.. _use-the-env-injector-extension: + +Use the env-injector extension +============================== + +The :ref:`env-injector-extension` lets you expose environment variables within the snap +to the user. These variables are accessible by the snap's apps and can modify their +behavior as they would in a bare host environment. + +The user has multiple available methods for setting these environment variables. Your +snap's apps and design should be oriented toward the most optimal method, and its +documentation should cover which variables are available and the correct method of +assigning them. + + +Set up the env-injector extension +--------------------------------- + +To add the env-injector extension to an app in your snap: + +1. Since env-injector is an `experimental extension + `_, + it's blocked by default. To enable experimental extensions during build, your host + must set the following environment variable when packing with Snapcraft: + + .. code-block:: bash + + SNAPCRAFT_ENABLE_EXPERIMENTAL_EXTENSIONS=1 + +2. Your snap must enable configurations with a `configure hook + `_. If + your snap doesn't use this hook yet, it needs at minimum an executable file named + ``configure``, without an extension, in ``snap/hooks/``. It should contain at + minimum: + + .. code-block:: bash + + #!/bin/sh + + # Optional validation logic + +3. In your snap's recipe, the target app's ``extensions`` key must list + ``env-injector``. For example, if your snap had an app named ``server``, the key + would declare: + + .. code-block:: yaml + + apps: + server: + command: run.sh + daemon: simple + extensions: [ env-injector ] + +Once set up, the user can set any available environment variables for the snap's apps. + + +Set an environment variable +--------------------------- + +When an app in a snap has behavior bound to an environment variable, the user can set it +either through the `snap's configuration +`_ or by reading an environment +(``.env``) file. + +Environment variables are applied to apps in one of two ways: + +- *Globally*, where the environment variable is passed to all apps that use + env-injector. +- *Locally*, where the environment variable is passed to a specific app that uses + env-injector. The app's name is taken from its definition in the snap recipe. The name + according to the extension can be :ref:`overridden with an alias + ` to avoid naming conflicts. + + + +As a snap configuration option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The user can set environment variables one at a time as snap configuration options +with the ``snap set`` command. + +To set an environment variable for all apps in a snap, the user can call ``snap set`` +and target the snap and its app. The passed environment variable name must be lowercase. +For example, to set ``HTTP_PORT=8080`` for all apps in a snap that use the env-injector, +the user would run: + +.. code-block:: bash + + sudo snap set env.http-port=8080 + +To set a local environment variable and target a specific app, they can call ``snap +set`` and prefix the option name with ``apps.``. To target only the server app +in the previous example, the user would run: + +.. code-block:: bash + + sudo snap set apps.server.env.http-port=8080 + +The app's name is taken from the snap's ``snapcraft.yaml``. + +When running ``snap set``, the user must adjust the environment variable name. For the +complete details on how snap options interpret environment variables, see +:ref:`env-injector-naming-rules`. + + +With an environment file +~~~~~~~~~~~~~~~~~~~~~~~~ + +The user can pass environment variables in ``.env`` files to the snap with the ``snap +set`` command. + +If a snap is confined, its file system needs access to the file, either by storing the +file in its `writable area `_ or through a +file interface. + +For a simple example, to globally export the contents of an environment file stored in +the local host, the user would run: + +.. code-block:: bash + + sudo snap set envfile=/var/snap/my-snap/common/config.env + +The environment variables inside ``config.env`` are then exported to all apps that use +the extension. + +To export the contents of the same file as local environment variables of the server +app, the user would run: + +.. code-block:: bash + + bash sudo snap set apps.server.envfile=/var/snap/my-snap/common/server.env + + +.. _use-the-env-injector-give-app-alias: + +Give an app an alias for the environment +---------------------------------------- + +The app's name is taken from its definition in the snap's recipe. You can override how +the app is referred to in the environment by setting its ``env_alias`` key. + +For example, to override an app named ``server`` with ``web-server``, the recipe would +declare: + +.. code-block:: yaml + + apps: + server: + command: run.sh + daemon: simple + extensions: [ env-injector ] + environments: + env_alias: web-server + +Then, the user could set a local environment variable on the app with: + +.. code-block:: bash + + sudo snap set apps.web-server.env.http-port=8080 + +Similarly, the user could override the app's local ``.env`` file with: + +.. code-block:: bash + + sudo snap set apps.web-server.envfile=/var/snap/my-snap/common/server.env diff --git a/docs/howto/use-extensions/use-the-gnome-extension.rst b/docs/howto/use-extensions/use-the-gnome-extension.rst new file mode 100644 index 0000000000..aacfc16b2f --- /dev/null +++ b/docs/howto/use-extensions/use-the-gnome-extension.rst @@ -0,0 +1,38 @@ +.. _use-the-gnome-extension: + +Use the GNOME extension +======================= + +To use the :ref:`gnome-extension` with an app, add it to the app's ``extensions`` +key in the snap recipe. For example: + +.. code:: yaml + + apps: + tali: + extensions: [gnome] + command: usr/bin/tali + +For a comprehensive example of a snap recipe that includes the extension, see +:ref:`example-gtk4-app`. + + +Additional interfaces +--------------------- + +When you include this extension, a number of :ref:`plugs +` are automatically opened, so you won't need to declare these if needed. + +For a comprehensive look, you can preview all the keys the extension will add to your +project file. At the root of your project, run: + +.. code-block:: bash + + snapcraft expand-extensions + +Expanding the extensions prints your project file to the terminal exactly as it would be +transformed by the preprocessor immediately prior to build. The output reveals all the +keys and their default values. + +For help with other plugs, see `Adding interfaces +`_. diff --git a/docs/reference/code/extensions/gnome-extension-gnome-system-monitor-core-22-expanded.diff b/docs/reference/code/extensions/gnome-extension-gnome-system-monitor-core-22-expanded.diff new file mode 100644 index 0000000000..f8b36020e0 --- /dev/null +++ b/docs/reference/code/extensions/gnome-extension-gnome-system-monitor-core-22-expanded.diff @@ -0,0 +1,209 @@ + name: gnome-system-monitor + adopt-info: gnome-system-monitor + summary: System Monitor + description: | + GNOME System Monitor is a GNOME process viewer and system monitor with + an attractive, easy-to-use interface, It has features, such as a tree + view for process dependencies, icons for processes, the ability to hide + processes that you don't want to see, graphical time histories of + CPU/memory/swap usage, the ability to kill/renice processes needing root + access, as well as the standard features that you might expect from a + process viewer. + + grade: stable + confinement: strict + base: core22 + +-build-snaps: +- - gnome-42-2204/latest/candidate + + slots: + # for GtkApplication registration + gnome-system-monitor: + interface: dbus + bus: session + name: org.gnome.SystemMonitor + + parts: + gnome-system-monitor: + # ext:updatesnap + source: https://gitlab.gnome.org/GNOME/gnome-system-monitor.git + source-type: git + source-tag: "46.0" + source-depth: 1 + plugin: meson +- parse-info: [usr/share/metainfo/gnome-system-monitor.appdata.xml] + meson-parameters: + - --prefix=/snap/gnome-system-monitor/current/usr + - --buildtype=release + - -Dsystemd=true + organize: + snap/gnome-system-monitor/current/usr: usr + override-pull: | + craftctl default + craftctl set version=$(git describe --tags --abbrev=10) + sed -i.bak -e 's|Icon=org.gnome.SystemMonitor$|Icon=${SNAP}/meta/gui/org.gnome.SystemMonitor.svg|g' gnome-system-monitor.desktop.in + sed -i.bak -E -e 's|^(NotShowIn=.*)$|# \1|g' gnome-system-monitor.desktop.in + override-build: | + craftctl default + mkdir -p $CRAFT_PART_INSTALL/meta/gui/ + cp $CRAFT_PART_BUILD/gnome-system-monitor.desktop $CRAFT_PART_INSTALL/meta/gui/ + cp $CRAFT_PART_SRC/data/icons/public/hicolor/scalable/apps/org.gnome.SystemMonitor.svg $CRAFT_PART_INSTALL/meta/gui/ + build-packages: + - desktop-file-utils + - docbook-to-man + - libgtop2-dev + - libsigc++-2.0-dev + - libsystemd-dev + - policykit-1 + - yelp-tools + stage-packages: + - libsigc++-2.0-0v5 ++ build-environment: ++ - PATH: /snap/gnome-42-2204-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-42-2204-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-42-2204-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib:/snap/gnome-42-2204-sdk/current/usr/lib/vala-current:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/lib/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-42-2204-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-42-2204-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-42-2204-sdk/current/usr/lib/python3.10:/snap/gnome-42-2204-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/girepository-1.0:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} + libraries: + after: + - gnome-system-monitor + plugin: nil + stage-packages: + - libgtop-2.0-11 + prime: + # Find files provided by the base and platform snap and ensure they aren't + # duplicated in this snap + - usr/lib/*/libgtop* + - usr/lib/*/libsigc-2.0.so.0* ++ build-environment: ++ - PATH: /snap/gnome-42-2204-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-42-2204-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-42-2204-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib:/snap/gnome-42-2204-sdk/current/usr/lib/vala-current:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/lib/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-42-2204-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-42-2204-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-42-2204-sdk/current/usr/lib/python3.10:/snap/gnome-42-2204-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/girepository-1.0:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} + cleanup: + after: + - libraries + plugin: nil + build-snaps: + - core22 + - gnome-42-2204 + override-prime: | + set -eux + for snap in "core22" "gnome-42-2204"; do + cd "/snap/$snap/current" && find . -type f,l -exec rm -f "$CRAFT_PRIME/{}" \; + done ++ build-environment: ++ - PATH: /snap/gnome-42-2204-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-42-2204-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-42-2204-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib:/snap/gnome-42-2204-sdk/current/usr/lib/vala-current:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/lib/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-42-2204-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-42-2204-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-42-2204-sdk/current/usr/lib/python3.10:/snap/gnome-42-2204-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/girepository-1.0:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} ++ snapcraft/core: ++ build-snaps: ++ - gnome-42-2204/latest/candidate ++ plugin: nil ++ build-environment: ++ - PATH: /snap/gnome-42-2204-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-42-2204-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-42-2204-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-42-2204-sdk/current/usr/lib:/snap/gnome-42-2204-sdk/current/usr/lib/vala-current:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/lib/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-42-2204-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-42-2204-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-42-2204-sdk/current/usr/lib/python3.10:/snap/gnome-42-2204-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/girepository-1.0:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} ++ gnome/sdk: ++ source: /snap/snapcraft/13181/share/snapcraft/extensions/desktop/command-chain ++ plugin: make ++ build-snaps: ++ - gnome-42-2204-sdk + ++layout: ++ /usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.0: ++ bind: $SNAP/gnome-platform/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.0 ++ /usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.1: ++ bind: $SNAP/gnome-platform/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.1 ++ /usr/share/xml/iso-codes: ++ bind: $SNAP/gnome-platform/usr/share/xml/iso-codes ++ /usr/share/libdrm: ++ bind: $SNAP/gnome-platform/usr/share/libdrm + ++architectures: ++ - build-on: ++ - amd64 ++ build-for: ++ - amd64 ++assumes: ++ - snapd2.43 ++hooks: ++ configure: ++ command-chain: ++ - snap/command-chain/hooks-configure-fonts ++ plugs: ++ - desktop + + apps: + gnome-system-monitor: +- extensions: +- - gnome + command: usr/bin/gnome-system-monitor + common-id: gnome-system-monitor.desktop + desktop: usr/share/applications/gnome-system-monitor.desktop ++ plugs: ++ - desktop ++ - desktop-legacy ++ - gsettings ++ - opengl ++ - wayland ++ - x11 + - unity7 + - mount-observe + - network-observe + - hardware-observe + - system-observe + - process-control + - run-systemd-sessions ++ command-chain: ++ - snap/command-chain/desktop-launch + + plugs: + run-systemd-sessions: + interface: system-files + read: + - /run/systemd/sessions ++ desktop: ++ mount-host-font-cache: false ++ gtk-3-themes: ++ interface: content ++ target: $SNAP/data-dir/themes ++ default-provider: gtk-common-themes ++ icon-themes: ++ interface: content ++ target: $SNAP/data-dir/icons ++ default-provider: gtk-common-themes ++ sound-themes: ++ interface: content ++ target: $SNAP/data-dir/sounds ++ default-provider: gtk-common-themes ++ gnome-42-2204: ++ interface: content ++ target: $SNAP/gnome-platform ++ default-provider: gnome-42-2204 + ++environment: ++ SNAP_DESKTOP_RUNTIME: $SNAP/gnome-platform ++ GTK_USE_PORTAL: "1" diff --git a/docs/reference/code/extensions/gnome-extension-gnome-system-monitor-core-24-expanded.diff b/docs/reference/code/extensions/gnome-extension-gnome-system-monitor-core-24-expanded.diff new file mode 100644 index 0000000000..a9da008938 --- /dev/null +++ b/docs/reference/code/extensions/gnome-extension-gnome-system-monitor-core-24-expanded.diff @@ -0,0 +1,214 @@ +# Diff between snapcraft.yaml and `snapcraft expand-extensions`, showing the differences +# that the GNOME extension applies to a project file. + name: gnome-system-monitor + adopt-info: gnome-system-monitor + summary: System Monitor + description: | + GNOME System Monitor is a GNOME process viewer and system monitor with + an attractive, easy-to-use interface, It has features, such as a tree + view for process dependencies, icons for processes, the ability to hide + processes that you don't want to see, graphical time histories of + CPU/memory/swap usage, the ability to kill/renice processes needing root + access, as well as the standard features that you might expect from a + process viewer. + + grade: stable + confinement: strict + base: core24 + +-build-snaps: +- - gnome-46-2404/latest/candidate + + parts: + gnome-system-monitor: + source: https://gitlab.gnome.org/GNOME/gnome-system-monitor.git + source-type: git + source-tag: "46.0" + source-depth: 1 + plugin: meson +- parse-info: [usr/share/metainfo/gnome-system-monitor.appdata.xml] + meson-parameters: + - --prefix=/snap/gnome-system-monitor/current/usr + - --buildtype=release + - -Dsystemd=true + organize: + snap/gnome-system-monitor/current/usr: usr + override-pull: | + craftctl default + craftctl set version=$(git describe --tags --abbrev=10) + sed -i.bak -e 's|Icon=@APP_ID@$|Icon=${SNAP}/meta/gui/org.gnome.SystemMonitor.svg|g' ./data/org.gnome.SystemMonitor.desktop.in.in + sed -i.bak -E -e 's|^(NotShowIn=.*)$|# \1|g' ./data/org.gnome.SystemMonitor.desktop.in.in + override-build: | + craftctl default + mkdir -p $CRAFT_PART_INSTALL/meta/gui/ + cp $CRAFT_PART_BUILD/data/org.gnome.SystemMonitor.desktop $CRAFT_PART_INSTALL/meta/gui/ + cp $CRAFT_PART_SRC/data/icons/public/hicolor/scalable/apps/org.gnome.SystemMonitor.svg $CRAFT_PART_INSTALL/meta/gui/ + build-packages: + - desktop-file-utils + - docbook-to-man + - libgtop2-dev + - libsigc++-2.0-dev + - libsystemd-dev + - policykit-1 + - yelp-tools + stage-packages: + - libsigc++-2.0-0v5 + build-snaps: + - gnome-46-2404-sdk/latest/candidate + ++ build-environment: ++ - PATH: /snap/gnome-46-2404-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-46-2404-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-46-2404-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib:/snap/gnome-46-2404-sdk/current/usr/lib/vala-current:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/lib/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-46-2404-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-46-2404-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-46-2404-sdk/current/usr/lib/python3.10:/snap/gnome-46-2404-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/girepository-1.0:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} + libraries: + after: + - gnome-system-monitor + plugin: nil + stage-packages: + - libgtop-2.0-11 + prime: + # Find files provided by the base and platform snap and ensure they aren't + # duplicated in this snap + - usr/lib/*/libgtop* + - usr/lib/*/libsigc-2.0.so.0* ++ build-environment: ++ - PATH: /snap/gnome-46-2404-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-46-2404-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-46-2404-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib:/snap/gnome-46-2404-sdk/current/usr/lib/vala-current:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/lib/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-46-2404-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-46-2404-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-46-2404-sdk/current/usr/lib/python3.10:/snap/gnome-46-2404-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/girepository-1.0:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} + cleanup: + after: + - libraries + plugin: nil + build-snaps: + - core24 + - gnome-46-2404 + override-prime: | + set -eux + for snap in "core24" "gnome-46-2404"; do + cd "/snap/$snap/current" && find . -type f,l -exec rm -f "$CRAFT_PRIME/{}" \; + done ++ build-environment: ++ - PATH: /snap/gnome-46-2404-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-46-2404-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-46-2404-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib:/snap/gnome-46-2404-sdk/current/usr/lib/vala-current:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/lib/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-46-2404-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-46-2404-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-46-2404-sdk/current/usr/lib/python3.10:/snap/gnome-46-2404-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/girepository-1.0:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} ++ snapcraft/core: ++ build-snaps: ++ - gnome-46-2404/latest/candidate ++ plugin: nil ++ build-environment: ++ - PATH: /snap/gnome-46-2404-sdk/current/usr/bin${PATH:+:$PATH} ++ - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-46-2404-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} ++ - LD_LIBRARY_PATH: /snap/gnome-46-2404-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib:/snap/gnome-46-2404-sdk/current/usr/lib/vala-current:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} ++ - PKG_CONFIG_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/lib/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} ++ - GETTEXTDATADIRS: /snap/gnome-46-2404-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} ++ - GDK_PIXBUF_MODULE_FILE: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache ++ - ACLOCAL_PATH: /snap/gnome-46-2404-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} ++ - PYTHONPATH: /snap/gnome-46-2404-sdk/current/usr/lib/python3.10:/snap/gnome-46-2404-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} ++ - GI_TYPELIB_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/girepository-1.0:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} ++ gnome/sdk: ++ source: /snap/snapcraft/13181/share/snapcraft/extensions/desktop/command-chain ++ plugin: make ++ make-parameters: ++ - GPU_WRAPPER=gpu-2404-wrapper ++ ++layout: ++ /usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.0: ++ bind: $SNAP/gnome-platform/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.0 ++ /usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.1: ++ bind: $SNAP/gnome-platform/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.1 ++ /usr/share/xml/iso-codes: ++ bind: $SNAP/gnome-platform/usr/share/xml/iso-codes ++ /usr/share/libdrm: ++ bind: $SNAP/gpu-2404/libdrm ++ /usr/share/drirc.d: ++ symlink: $SNAP/gpu-2404/drirc.d ++ /usr/share/X11/XErrorDB: ++ symlink: $SNAP/gpu-2404/X11/XErrorDB ++assumes: ++ - snapd2.43 ++hooks: ++ configure: ++ command-chain: ++ - snap/command-chain/hooks-configure-fonts ++ plugs: ++ - desktop + + apps: + gnome-system-monitor: +- extensions: [ gnome ] + command: usr/bin/gnome-system-monitor + desktop: usr/share/applications/org.gnome.SystemMonitor.desktop + plugs: ++ - desktop ++ - desktop-legacy ++ - gsettings ++ - opengl ++ - wayland ++ - x11 + - unity7 + - mount-observe + - network-observe + - hardware-observe + - system-observe + - process-control + - run-systemd-sessions ++ command-chain: ++ - snap/command-chain/gpu-2404-wrapper ++ - snap/command-chain/desktop-launch + + plugs: + run-systemd-sessions: + interface: system-files + read: + - /run/systemd/sessions ++ desktop: ++ mount-host-font-cache: false ++ gtk-3-themes: ++ interface: content ++ target: $SNAP/data-dir/themes ++ default-provider: gtk-common-themes ++ icon-themes: ++ interface: content ++ target: $SNAP/data-dir/icons ++ default-provider: gtk-common-themes ++ sound-themes: ++ interface: content ++ target: $SNAP/data-dir/sounds ++ default-provider: gtk-common-themes ++ gnome-46-2404: ++ interface: content ++ target: $SNAP/gnome-platform ++ default-provider: gnome-46-2404 ++ gpu-2404: ++ interface: content ++ target: $SNAP/gpu-2404 ++ default-provider: mesa-2404 + + slots: + gnome-system-monitor: + # for GtkApplication registration + interface: dbus + bus: session + name: org.gnome.SystemMonitor + ++environment: ++ SNAP_DESKTOP_RUNTIME: $SNAP/gnome-platform ++ GTK_USE_PORTAL: "1" diff --git a/docs/reference/extensions/env-injector-extension.rst b/docs/reference/extensions/env-injector-extension.rst new file mode 100644 index 0000000000..8b1c4bcee1 --- /dev/null +++ b/docs/reference/extensions/env-injector-extension.rst @@ -0,0 +1,126 @@ +.. _env-injector-extension: + +env-injector extension +====================== + +The env-injector extension, referred to internally as ``env-injector``, provides an +interface for altering snap behavior with user-defined environment variables. + +When you add the extension to individual apps inside a snap, you open the way for the +user to `configure the snap `_ or +affect its behaviour with environment variables. + + +How it works +------------ + +This extension splits environment variables into two types: + +- *Global* environment variables are visible to all apps in the snap that use + env-injector. +- *Local* environment variables are visible only to apps with env-injector that the user + specifically targets. + +At a high level, the extension has the following processes and rules during build and +runtime. + + +Environment variable order of precedence +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Environment variables are processed in the following order: + +1. Variables extracted from the global ``.env`` file. +2. Variables extracted from the local ``.env`` file. +3. Variables from global snap config. +4. Variables from local snap config. + + +App build process +~~~~~~~~~~~~~~~~~ + +.. TODO: Put a link to exporter program repository + +For each app that uses the extension: + +1. The app responsible for processing environment variables (the exporter program) is + added to its `command chain + `_. +2. The app's name is taken either from its internal name or an :ref:`environment alias + `. + + +Runtime process +~~~~~~~~~~~~~~~ + +When the snap runs, for each app that uses the extension, the exporter program: + +1. Runs before the app is executed. +2. Makes a request to the `snapd API `_ + through the snapd Unix socket. +3. Reads the available environment variables or paths to the ``.env`` files. +4. Translates the snap options into environment variables. +5. If available, loads the ``.env`` files and sets the listed variables. +6. Sets all converted environment variables. +7. Executes the app's command. + + +.. _env-injector-naming-rules: + +Snap option naming and rules +---------------------------- + +Because there's a chance of conflict and collision between the names of snap options and +environment variables, this extension is governed by naming rules. + +Snap options map to environment variables: + +.. list-table:: + :header-rows: 1 + + * - Type + - Snap configuration option + - Environment variable + * - Global + - ``env.=`` + - ``=`` + * - Local + - ``apps..env.=`` + - ``=`` + +When mapped, key names are sanitized before being converted into environment variable +names: + +.. list-table:: + :header-rows: 1 + + * - Character in snap option + - Result in environment variable + * - Lowercase letters + - Uppercase letters + * - Number not at key start + - Number + * - Hyphen not at key start or end + - Underscore + +.. tip:: + + The first column is the rule set for snap option names. Any character not detailed + in it is invalid in a snap option name. + + +User-selected environment files +------------------------------- + +With the special ``envfile`` snap options, the user can also pass whole environment +(``.env``) files to the snap, provided the file is already packed inside the snap. + +.. list-table:: + :header-rows: 1 + + * - Type + - Snap option + * - Global + - ``envfile=`` + * - Local + - ``apps..envfile=`` diff --git a/docs/reference/extensions/gnome-extension.rst b/docs/reference/extensions/gnome-extension.rst new file mode 100644 index 0000000000..cf689085e6 --- /dev/null +++ b/docs/reference/extensions/gnome-extension.rst @@ -0,0 +1,267 @@ +.. _gnome-extension: + +GNOME extension +=============== + +The GNOME extension, referred to internally as ``gnome``, helps build snaps that use GTK +3, GNOME 42 and higher, and GLib. This extension provides many of the components needed +for general desktop apps, making it useful for a broader set of apps outside of those +tailored for the GNOME desktop. + +This extension is compatible with the core22 and core24 bases. + + +.. _gnome-extension-included-plugs: + +Included plugs +-------------- + +When this extension is used, the following plugs are connected for the app. The paths +slightly differ between core24 and core22 bases. + +.. tabs:: + + .. group-tab:: core24 + + .. collapse:: Included snap-wide plugs + + .. code-block:: yaml + + plugs: + desktop: + mount-host-font-cache: false + gtk-3-themes: + interface: content + target: $SNAP/data-dir/themes + default-provider: gtk-common-themes + icon-themes: + interface: content + target: $SNAP/data-dir/icons + default-provider: gtk-common-themes + sound-themes: + interface: content + target: $SNAP/data-dir/sounds + default-provider: gtk-common-themes + gnome-46-2404: + interface: content + target: $SNAP/gnome-platform + default-provider: gnome-46-2404 + gpu-2404: + interface: content + target: $SNAP/gpu-2404 + default-provider: mesa-2404 + + .. group-tab:: core22 + + .. collapse:: Included snap-wide plugs + + .. code-block:: yaml + + plugs: + desktop: + mount-host-font-cache: false + gtk-3-themes: + interface: content + target: $SNAP/data-dir/themes + default-provider: gtk-common-themes + icon-themes: + interface: content + target: $SNAP/data-dir/icons + default-provider: gtk-common-themes + sound-themes: + interface: content + target: $SNAP/data-dir/sounds + default-provider: gtk-common-themes + gnome-42-2204: + interface: content + target: $SNAP/gnome-platform + default-provider: gnome-42-2204 + +The extension also connects the following plugs to all apps that use it. + +.. collapse:: Included app plugs + + .. code-block:: yaml + + plugs: + - desktop + - desktop-legacy + - gsettings + - opengl + - wayland + - x11 + - mount-observe + - calendar-service + + +Included packages +----------------- + +The GNOME extension is derived from two separate snaps -- a `build snap +`_ and a +`platform snap +`_. + +The build snap compiles libraries from source that are commonly used across GNOME apps. +Examples include GLib, GTK, and gnome-desktop. These are built to provide newer versions +of these packages that exist in either the core24 or core22 base snaps (a subset of +their respective Ubuntu archives). + +The platform snap takes the build snap and makes all of those libraries available at +build time to snaps using this extension. This way, snap authors don't need to include +the pieces of the build snap that are unnecessary at runtime, like compilers, in the +final snap. + + +Included environment variables +------------------------------ + +In addition to using the build and platform snaps, this extension sets several +environment variables, links, and default plugs for the app to use, and a default +build-environment for each part in your snap to use. + + +Build variables +~~~~~~~~~~~~~~~ + +The following build environment variables are added to each part in a snap that uses +this extension. + +You can declare additional variables in the ``build-environment`` key. Furthermore, +these default variables can be overridden by declaring them in the recipe. + +The paths differ slightly between core24 and core22 bases. + +.. tabs:: + + .. group-tab:: core24 + + .. collapse:: Included build environment variables + + .. code-block:: yaml + + build-environment: + - PATH: /snap/gnome-46-2404-sdk/current/usr/bin${PATH:+:$PATH} + - XDG_DATA_DIRS: $CRAFT_STAGE/usr/share:/snap/gnome-46-2404-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} + - LD_LIBRARY_PATH: /snap/gnome-46-2404-sdk/current/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR:/snap/gnome-46-2404-sdk/current/usr/lib:/snap/gnome-46-2404-sdk/current/usr/lib/vala-current:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} + - PKG_CONFIG_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/lib/pkgconfig:/snap/gnome-46-2404-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} + - GETTEXTDATADIRS: /snap/gnome-46-2404-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} + - GDK_PIXBUF_MODULE_FILE: /snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gdk-pixbuf-current/loaders.cache + - ACLOCAL_PATH: /snap/gnome-46-2404-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} + - PYTHONPATH: /snap/gnome-46-2404-sdk/current/usr/lib/python3.10:/snap/gnome-46-2404-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} + - GI_TYPELIB_PATH: /snap/gnome-46-2404-sdk/current/usr/lib/girepository-1.0:/snap/gnome-46-2404-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/girepository-1.0${GI_TYPELIB_PATH:+:$GI_TYPELIB_PATH} + + .. group-tab:: core22 + + .. collapse:: Included build environment variables + + .. code-block:: yaml + + build-environment: + - PATH: /snap/gnome-42-2204-sdk/current/usr/bin${PATH:+:$PATH} + - XDG_DATA_DIRS: $SNAPCRAFT_STAGE/usr/share:/snap/gnome-42-2204-sdk/current/usr/share:/usr/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS} + - LD_LIBRARY_PATH: /snap/gnome-42-2204-sdk/current/lib/$CRAFT_ARCH_TRIPLET:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET:/snap/gnome-42-2204-sdk/current/usr/lib:/snap/gnome-42-2204-sdk/current/usr/lib/vala-current:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET/pulseaudio${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH} + - PKG_CONFIG_PATH: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/lib/pkgconfig:/snap/gnome-42-2204-sdk/current/usr/share/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH} + - GETTEXTDATADIRS: /snap/gnome-42-2204-sdk/current/usr/share/gettext-current${GETTEXTDATADIRS:+:$GETTEXTDATADIRS} + - GDK_PIXBUF_MODULE_FILE: /snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET/gdk-pixbuf-current/loaders.cache + - ACLOCAL_PATH: /snap/gnome-42-2204-sdk/current/usr/share/aclocal${ACLOCAL_PATH:+:$ACLOCAL_PATH} + - PYTHONPATH: /snap/gnome-42-2204-sdk/current/usr/lib/python3.10:/snap/gnome-42-2204-sdk/current/usr/lib/python3/dist-packages:/snap/gnome-42-2204-sdk/current/usr/lib/$CRAFT_ARCH_TRIPLET/gobject-introspection${PYTHONPATH:+:$PYTHONPATH} + + +Runtime variables +~~~~~~~~~~~~~~~~~ + +The following environment variables are exported when the app runs: + +.. collapse:: Environment variables + + .. code-block:: yaml + + environment: + SNAP_DESKTOP_RUNTIME: $SNAP/gnome-platform + GTK_USE_PORTAL: '1' + + +Included layouts +---------------- + +This extension uses `layouts `_ to access files +on the host. The platform snap's GNOME JavaScript (GJS), webkit2gtk-4.0, and iso-codes +are used so they don't need to be packaged as part of the snap and would greatly inflate +the size. + +.. tabs:: + + .. group-tab:: core24 + + .. collapse:: Included layouts + + .. code-block:: yaml + + layout: + /usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.0: + bind: $SNAP/gnome-platform/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.0 + /usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.1: + bind: $SNAP/gnome-platform/usr/lib/$CRAFT_ARCH_TRIPLET_BUILD_FOR/webkit2gtk-4.1 + /usr/share/xml/iso-codes: + bind: $SNAP/gnome-platform/usr/share/xml/iso-codes + /usr/share/libdrm: + bind: $SNAP/gpu-2404/libdrm + /usr/share/drirc.d: + symlink: $SNAP/gpu-2404/drirc.d + /usr/share/X11/XErrorDB: + symlink: $SNAP/gpu-2404/X11/XErrorDB + + .. group-tab:: core22 + + .. collapse:: Included layouts + + .. code-block:: yaml + + layout: + /usr/lib/$SNAPCRAFT_ARCH_TRIPLET/libgweather-4: + symlink: $SNAP/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/libgweather-4 + /usr/lib/evolution-data-server: + symlink: $SNAP/usr/lib/evolution-data-server + /usr/bin/gnome-control-center: + symlink: $SNAP/usr/bin/gnome-control-center + /usr/lib/$SNAPCRAFT_ARCH_TRIPLET/webkit2gtk-4.0: + bind: $SNAP/gnome-platform/usr/lib/$SNAPCRAFT_ARCH_TRIPLET/webkit2gtk-4.0 + /usr/share/xml/iso-codes: + bind: $SNAP/gnome-platform/usr/share/xml/iso-codes + /usr/share/libdrm: + bind: $SNAP/gnome-platform/usr/share/libdrm + + +Example expanded project file +----------------------------- + +Here's an example of the result of Snapcraft expanding a core24-based project file, as +immediately prior to build. It demonstrates the added plugs, packages, variables, and +layouts that the GNOME extension includes in a project. + +The original files were for the `GNOME System Monitor snap +`_. These texts contain the difference +between the original file and the output of the :ref:`snapcraft expand-extensions +` command. Some of the text has been altered for ease of +reading. + +.. tabs:: + + .. group-tab:: core24 + + .. collapse:: Expanded project file for GNOME System Monitor + + .. literalinclude:: ../code/extensions/gnome-extension-gnome-system-monitor-core-24-expanded.diff + :language: diff + :lines: 3- + :emphasize-lines: 57-66, 78-87, 100-150, 158-163, 171-173, 180-201, 210-212 + + .. group-tab:: core22 + + .. collapse:: Expanded project file for GNOME System Monitor + + .. literalinclude:: ../code/extensions/gnome-extension-gnome-system-monitor-core-22-expanded.diff + :language: diff + :lines: 3- + :emphasize-lines: 60-69, 81-90, 103-155, 159-160, 164-170, 178-179, 186-207 diff --git a/docs/reference/extensions/index.rst b/docs/reference/extensions/index.rst new file mode 100644 index 0000000000..7973a8e33c --- /dev/null +++ b/docs/reference/extensions/index.rst @@ -0,0 +1,21 @@ +.. _extensions: + +Extensions +========== + +Snapcraft extensions enable you to easily incorporate a set of common requirements into +a snap, saving time spent replicating the same general requirements shared across +similar apps. + +Extensions instruct Snapcraft to operate on the project file prior to build, causing it +to add any needed scaffolding and boilerplate keys to enable a particular technology. +The procedure is merely a postprocessor acting on the project's keys in memory -- the +actual project file on disk is unaffected. + +For guidance on specific extensions, see :ref:`use-extensions`. + +.. toctree:: + :hidden: + + env-injector-extension + gnome-extension diff --git a/docs/reference/index.rst b/docs/reference/index.rst index f1a6e03e91..bce27635e4 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -17,6 +17,7 @@ Reference components linters plugins + extensions/index /common/craft-parts/reference/part_properties parts_steps system-requirements