docs: migrate env-injector and gnome extension pages

- Add some indexes.
- Add new how-tos about extensions.

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,17 @@
+.. _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:
+
+    list-extensions
+    enable-experimental-extensions
+    use-the-env-injector-extension
+    use-the-gnome-extension

docs/howto/use-extensions/list-extensions.rst

@@ -0,0 +1,11 @@
+.. _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 extensions

docs/howto/use-extensions/use-the-env-injector-extension.rst

@@ -0,0 +1,166 @@
+.. _use-the-env-injector-extension:
+
+Use the env-injector extension
+==============================
+
+The :ref:`env-injector-extension` lets you expose environment variables within the snap
+to users. 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 confiugration option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users can set environment variables one at a time as a snap configuration options with
+the ``snap set`` command.
+
+To set an environment variable globally, 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
+
+    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``, users must the adjust environment variable name. For the
+complete details on how snap options interpret environment variables, see
+:ref:`env-injector-naming-rules`.
+
+
+With an environment file
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Users 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, such as the `home interface <https://snapcraft.io/docs/home-interface>`_
+or `personal-files interface <https://snapcraft.io/docs/personal-files-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,26 @@
+.. _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 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 help with other plugs, see `Adding interfaces <https://snapcraft.io/docs/snapcraft-interfaces>`_.

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 <https://snapcraft.io/docs/configuration-in-snaps>`_ 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-ibjector 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
+   <https://snapcraft.io/docs/snapcraft-yaml-schema#p-21225-command-chain-47>`_.
+2. The app's name is taken either from its internal name or an :ref:`environment alias
+   <use-the-env-injector-give-app-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 <https://snapcraft.io/docs/using-the-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.<key>=<value>``
+      - ``<key>=<value>``
+    * - Local
+      - ``apps.<app>.env.<key>=<value>``
+      - ``<key>=<value>``
+
+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.
+
+
+Environment file paths
+----------------------
+
+Environment (``.env``) files can pass variables to the snap with the special ``envfile``
+option:
+
+.. list-table::
+    :header-rows: 1
+
+    * - Type
+      - Snap option
+    * - Global
+      - ``envfile=<path>``
+    * - Local
+      - ``apps.<app>.envfile=<path>``