From b8b4159ce3c12525ce283553ffee9f3b60a608b9 Mon Sep 17 00:00:00 2001 From: James Ennis Date: Tue, 17 Apr 2018 11:55:09 +0100 Subject: config.rst: Renamed to user_config.rst and anchors changed --- doc/source/artifacts.rst | 2 +- doc/source/config.rst | 97 ---------------------------------------------- doc/source/main_using.rst | 2 +- doc/source/user_config.rst | 97 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 99 insertions(+), 99 deletions(-) delete mode 100644 doc/source/config.rst create mode 100644 doc/source/user_config.rst diff --git a/doc/source/artifacts.rst b/doc/source/artifacts.rst index c51ce09ac..8edf3462a 100644 --- a/doc/source/artifacts.rst +++ b/doc/source/artifacts.rst @@ -183,7 +183,7 @@ E.g., create ``/etc/cron.d/artifacts`` with the following content: User configuration ~~~~~~~~~~~~~~~~~~ The user configuration for artifacts is documented with the rest -of the :ref:`user configuration documentation `. +of the :ref:`user configuration documentation `. Assuming you have the same setup used in this document, and that your host is reachable on the internet as ``artifacts.com`` (for example), diff --git a/doc/source/config.rst b/doc/source/config.rst deleted file mode 100644 index ee426f0ab..000000000 --- a/doc/source/config.rst +++ /dev/null @@ -1,97 +0,0 @@ - -.. _config: - - -User configuration -================== -User configuration and preferences can be specified in a user provided -configuration file, and usually also on the command line. - -Values specified in a user provided configuration file override the -defaults, while command line options take precedence over any other -specified configurations. - - -Configuration file ------------------- -Users can provide a configuration file to override parameters in -the default configuration. - -Unless a configuration file is explicitly specified on the command line when -invoking ``bst``, an attempt is made to load user specific configuration from -``$XDG_CONFIG_HOME/buildstream.conf``. On most Linux based systems, the location -will be ``~/.config/buildstream.conf`` - - -Project specific value ----------------------- -The ``projects`` key can be used to specify project specific configurations, -the supported configurations on a project wide basis are listed here. - -.. _config_artifacts: - -Artifact server -~~~~~~~~~~~~~~~ -The project you build will often specify a :ref:`remote artifact cache -` already, but you may want to specify extra caches. There are two -ways to do this. You can add one or more global caches: - -**Example** - -.. code:: yaml - - artifacts: - url: https://artifacts.com/artifacts - -Caches listed there will be considered lower priority than those specified -by the project configuration. - -You can also add project-specific caches: - -**Example** - -.. code:: yaml - - projects: - project-name: - artifacts: - - url: https://artifacts.com/artifacts1 - - url: ssh://user@artifacts.com/artifacts2 - push: true - -Caches listed here will be considered higher priority than those specified -by the project. - -If you give a list of URLs, earlier entries in the list will have higher -priority than later ones. - -Strict build plan -~~~~~~~~~~~~~~~~~ -The strict build plan option decides whether you want elements -to rebuild when their dependencies have changed. This is enabled -by default, but recommended to turn off in developer scenarios where -you might want to build a large system and test it quickly after -modifying some low level component. - - -**Example** - -.. code:: yaml - - projects: - project-name: - strict: False - - -.. note:: - - It is always possible to override this at invocation time using - the ``--strict`` and ``--no-strict`` command line options. - - -Default configuration ---------------------- -The default BuildStream configuration is specified here for reference: - - .. literalinclude:: ../../buildstream/data/userconfig.yaml - :language: yaml diff --git a/doc/source/main_using.rst b/doc/source/main_using.rst index 069ac0466..73d9716eb 100644 --- a/doc/source/main_using.rst +++ b/doc/source/main_using.rst @@ -11,5 +11,5 @@ This section details how to use the BuildStream command line interface, work wit :maxdepth: 2 commands - config + user_config authoring diff --git a/doc/source/user_config.rst b/doc/source/user_config.rst new file mode 100644 index 000000000..d02aaf3d4 --- /dev/null +++ b/doc/source/user_config.rst @@ -0,0 +1,97 @@ + +.. _user_config: + + +User configuration +================== +User configuration and preferences can be specified in a user provided +configuration file, and usually also on the command line. + +Values specified in a user provided configuration file override the +defaults, while command line options take precedence over any other +specified configurations. + + +Configuration file +------------------ +Users can provide a configuration file to override parameters in +the default configuration. + +Unless a configuration file is explicitly specified on the command line when +invoking ``bst``, an attempt is made to load user specific configuration from +``$XDG_CONFIG_HOME/buildstream.conf``. On most Linux based systems, the location +will be ``~/.config/buildstream.conf`` + + +Project specific value +---------------------- +The ``projects`` key can be used to specify project specific configurations, +the supported configurations on a project wide basis are listed here. + +.. _config_artifacts: + +Artifact server +~~~~~~~~~~~~~~~ +The project you build will often specify a :ref:`remote artifact cache +` already, but you may want to specify extra caches. There are two +ways to do this. You can add one or more global caches: + +**Example** + +.. code:: yaml + + artifacts: + url: https://artifacts.com/artifacts + +Caches listed there will be considered lower priority than those specified +by the project configuration. + +You can also add project-specific caches: + +**Example** + +.. code:: yaml + + projects: + project-name: + artifacts: + - url: https://artifacts.com/artifacts1 + - url: ssh://user@artifacts.com/artifacts2 + push: true + +Caches listed here will be considered higher priority than those specified +by the project. + +If you give a list of URLs, earlier entries in the list will have higher +priority than later ones. + +Strict build plan +~~~~~~~~~~~~~~~~~ +The strict build plan option decides whether you want elements +to rebuild when their dependencies have changed. This is enabled +by default, but recommended to turn off in developer scenarios where +you might want to build a large system and test it quickly after +modifying some low level component. + + +**Example** + +.. code:: yaml + + projects: + project-name: + strict: False + + +.. note:: + + It is always possible to override this at invocation time using + the ``--strict`` and ``--no-strict`` command line options. + + +Default configuration +--------------------- +The default BuildStream configuration is specified here for reference: + + .. literalinclude:: ../../buildstream/data/userconfig.yaml + :language: yaml -- cgit v1.2.1