docs: add environment variables reference (#431)

docs/reference/environment-variables.rst

@@ -0,0 +1,111 @@
+*********************
+Environment variables
+*********************
+
+Applications built on craft-application have several environment variables that
+can configure their behaviour. They and the behaviour they modify are listed
+below.
+
+Variables passed to managed builders
+------------------------------------
+
+Several environment variables from the host environment are passed to the
+managed build environment. While an application may adjust these by adjusting
+the ``environment`` dictionary attached to the ``ProviderService``,
+craft-application will by default forward the ``http_proxy``, ``https_proxy``
+and ``no_proxy`` environment variables from the host.
+
+Supported variables
+-------------------
+
+These variables are explicitly supported for user configuration.
+
+.. _env-var-craft-build-environment:
+
+``CRAFT_BUILD_ENVIRONMENT``
+===========================
+
+If the value is ``host``, allows an environment to tell a craft application
+to run directly on the host rather than in managed mode. This method is
+roughly equivalent to using ``--destructive-mode``, but is designed for
+configurations where the application is already being run in an appropriate
+container or VM, such as
+`Snapcraft rocks <https://github.com/canonical/snapcraft-rocks/>`_ or
+when controlled by a CI system such as `Launchpad <https://launchpad.net>`_.
+
+**CAUTION**: Setting the build environment is only recommended if you are
+aware of the exact packages needed to reproduce the build containers created
+by the app.
+
+``CRAFT_BUILD_FOR``
+===================
+
+Sets the default architecture to build for. Overridden by ``--build-for`` in
+lifecycle commands.
+
+``CRAFT_PLATFORM``
+==================
+
+Sets the default platform to build. Overridden by ``--platform`` in lifecycle
+commands.
+
+``CRAFT_SNAP_CHANNEL``
+======================
+
+Overrides the default channel that a craft application's snap is installed from
+if the manager instance is not running as a snap. If unset, the application
+will be installed from the ``latest/stable`` channel. If the application is
+running from a snap, this variable is ignored and the same snap used on
+the host system is injected into the managed builder.
+
+``CRAFT_VERBOSITY_LEVEL``
+=========================
+
+Set the verbosity level for the application. Valid values are: ``quiet``,
+``brief``, ``verbose``, ``debug`` and ``trace``. This is overridden by the
+``--quiet``, ``--verbose`` or ``--verbosity={value}`` global command options.
+
+Development variables
+---------------------
+
+The following variables exist to help developers writing applications using
+craft-application more easily debug their code:
+
+``CRAFT_DEBUG``
+===============
+
+Controls whether the application is in debug mode. If this variable is set to
+``1``, general exceptions will not be caught, instead showing a traceback on
+the command line. This is normally only useful for developers working on
+craft-application or an app that uses the framework, as a traceback is always
+written to the log file as well.
+
+``CRAFT_LAUNCHPAD_INSTANCE``
+============================
+
+For remote builds, allows the user to set an alternative launchpad instance.
+Accepts any string that can be used as the ``service_root`` value in
+`Launchpadlib <https://help.launchpad.net/API/launchpadlib>`_.
+
+Unsupported variables
+---------------------
+
+The following variables cause behaviour changes in craft-application, but
+should not be set except by craft-application itself.
+
+``CRAFT_LXD_REMOTE``
+====================
+
+If using LXD, the application will start containers in the configured remote
+rather than ``local``.
+
+**CAUTION:** Using non-default remotes is experimental and not recommended at
+this time.
+
+``CRAFT_MANAGED_MODE``
+======================
+
+Alerts the application that it is running in managed mode. This should only be
+set by craft-application when creating a provider. Systems designed to wrap
+craft applications may use the :ref:`env-var-craft-build-environment`
+environment variable to make the app run on the host.

docs/reference/index.rst

@@ -7,6 +7,7 @@ Reference
    :maxdepth: 1
 
    changelog
+   environment-variables
    platforms
 
 Indices and tables