Document more configuration details (#1611)

doc/configuration.md

@@ -14,25 +14,25 @@
  "10.1" or "true". Extra type checking is used for built-in options (see below).
 
  Specific config options:
-                           
+
   - `--list` List configuration options
   - `--show-origin` Show origin of configuration values in `--list`
   - `--get` Print value of a configuration option
   - `--set` Set a configuration option
   - `--unset` Unset a configuration option
   - `--global` Set and Unset global configuration instead of the local one
   - `--builtins-doc` Print Markdown list of built-in configuration options
- 
+
  Examples:
 
  - `alr config --global --set my_option option_value`
-  
-    Will set a configuration option with the key `my_option` and the string 
+
+    Will set a configuration option with the key `my_option` and the string
     value `option_value` in the global configuration file.
 
  - `alr config --get my_option`
-  
-    Will print the value configuration option `my_option` if it is defined, 
+
+    Will print the value configuration option `my_option` if it is defined,
     otherwise the command fails.
 
 
@@ -62,6 +62,23 @@ The built-ins also have a short description to document their type and usage.
 
 ## Built-ins list
 
-Here is the list of `Alire` built-in configuration options. You can also get
-this from `alr` with `alr help config`.
+You can get the list of options recognized by `alr` with `alr help config`,
+including their default values and a short explanation of their effects.
+
+## Relocating your configuration
+
+By default, `alr` stores its global configuration at `<user
+home>/.config/alire`. You can use any other location by setting in the
+environment the variable `ALR_CONFIG=</absolute/path/to/config/folder>`, or by
+using the global `-c` switch: `alr -c </path/to/config> <command>`.
+
+Using a pristine default configuration can be useful to isolate the source of
+errors by ensuring that a misconfiguration is not at play.
+
+## Inspecting your configuration
 
+These commands may help you in identifying Alire configuration and environment:
+- `alr config --list` will show all configuration options in effect.
+- `alr version` will print many relevant bits of information about the current
+  `alr` environment.
+- `alr --version` will just print the version number and exit.

doc/getting-started.md

@@ -10,30 +10,38 @@ repository](https://github.com/alire-project/alire/releases).
 On Linux, `Alire` is simply provided in an archive.
 
 Once the archive is extracted you have to add `alr` in the environment `PATH` .
-This may be done for the duration of a terminal session by running the command below: 
+This may be done for the duration of a terminal session by running the command below:
 ```bash
 $ export PATH="<PATH_TO_EXTRACTED>/bin/:$PATH"
 ```
 Those wanting to keep this path permanently in their `PATH` environment may do so by pasting the above command into the `.profile` file of their user's account.
 
-Alire provides GNAT toolchains hosted on x86-64 for Linux. If those toolchains do not 
-work for you, or if you are on another host architecture like ARM, you have the option 
+Alire provides GNAT toolchains hosted on x86-64 for Linux. If those toolchains do not
+work for you, or if you are on another host architecture like ARM, you have the option
 to look at the GNAT toolchains from the Linux distribution.
 
 ## `alr` on Windows
 
 On Windows an installer is provided. The installer will create a shortcut to
 start `PowerShell` with `Alire` in the environment `PATH`.
 
-The first time you run `alr` the program will ask if you want to install
-[msys2](https://www.msys2.org/). This is recommended as `alr` will use `msys2`
+The first time you run `alr`, the program
+will ask if you want to install
+[msys2](https://www.msys2.org/) (except in the cases listed below). This is recommended as `alr` will use `msys2`
 to automatically install required tools such as `git` or `make` that you would
 otherwise have to install manually. `msys2` will also provide external
 libraries required by some projects in the Alire index, allowing you to build
 more projects out of the box.
 
-Alire provides GNAT toolchains hosted on x86-64 for Windows. Those toolchains 
-should work for all cases, if not, let us know.
+`msys2` will not be installed
+- when running `alr config`, to allow uninterrupted configuration, and configuration
+  of `msys2` location (see `alr help config`), or
+- when you already have a msys2 installation in your PATH (more precisely, if `pacman`
+  is found in your PATH.)
+  - In this case, `alr` will reuse your existing installation.
+
+Alire provides GNAT toolchains hosted on x86-64 for Windows. Those toolchains
+should work for all cases; if not, let us know.
 
 ## `alr` on macOS
 
@@ -44,14 +52,14 @@ Once the archive is extracted you have to add `alr` in the environment `PATH`:
 $ export PATH="<PATH_TO_EXTRACTED>/bin/:$PATH"
 ```
 
-If you try to run it on recent versions of macOS, you will get a popup saying 
-`“alr” cannot be opened because the developer cannot be verified.` and inviting 
+If you try to run it on recent versions of macOS, you will get a popup saying
+`“alr” cannot be opened because the developer cannot be verified.` and inviting
 you to move it to the bin. The way round this is to remove the quarantine attribute,
 ```console
 $ xattr -d com.apple.quarantine bin/alr
 ```
 
-Alire provides GNAT toolchains hosted on x86-64 for macOS. If those toolchains do not 
+Alire provides GNAT toolchains hosted on x86-64 for macOS. If those toolchains do not
 work for you, or if you are on another host architecture like the Apple M1, you have
 the option to look at the GNAT toolchains from the community.
 
@@ -276,10 +284,18 @@ to print the build environment:
 
 ## Troubleshooting
 
-By default `alr` is quite terse and will hide the output of subprocesses,
-mostly reporting in case of failure. If you hit any problem, increasing
-verbosity (`-v` or even `-vv`) is usually enough to get an idea of the root of
-the problem. Additionally, `-d` will show tracebacks of exceptions.
+If you hit any problem, increasing verbosity (`-v` or even `-vv`) is usually
+enough to get an idea of the root of the problem. Additionally, `-d` will show
+tracebacks of exceptions.
+
+Subprocess output is shown by default (you can silence it, and anything else
+not an error) with `-q`, which enables quiet mode. Any subprocess that exist
+abnormally will be reported, including its invocation arguments.
+
+If you suspect your configuration may be the source of some problem, please
+check our section on [Configuration](configuration.md), and in particular how
+to use a [default pristine
+configuration](configuration.md#Relocating-your-configuration)
 
 ## Running tests