docs: migrate env-injector and gnome extension pages (#5212)

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

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

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

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`.

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

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
+   <https://snapcraft.io/docs/supported-extensions#p-80380-experimental-extensions>`_,
+   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
+   <https://snapcraft.io/docs/supported-snap-hooks#heading--the-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
+<https://snapcraft.io/docs/configuration-in-snaps>`_ 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
+  <use-the-env-injector-give-app-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 <snap-name> 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.<app-name>``. To target only the server app
+in the previous example, the user would run:
+
+.. code-block:: bash
+
+    sudo snap set <snap-name> 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 <https://snapcraft.io/docs/data-locations>`_ 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 <my-snap> 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 <my-snap> 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 <my-name> 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 <my-name> apps.web-server.envfile=/var/snap/my-snap/common/server.env

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
+<gnome-extension-included-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
+<https://snapcraft.io/docs/snapcraft-interfaces>`_.