Merge remote-tracking branch 'alire/master' into release/2.0

.github/workflows/ci-windows.yml

@@ -12,7 +12,10 @@ on:
   workflow_dispatch:
 
 env:
-  ALIRE_OS: "windows"
+  ALIRE_OS:     windows
+  MINGW64_PATH: C:\Users\runneradmin\AppData\Local\alire\cache\msys64\mingw64\bin
+  MSYS2_PATH:   C:\Users\runneradmin\AppData\Local\alire\cache\msys64\usr\bin
+  PACMAN:       C:\Users\runneradmin\AppData\Local\alire\cache\msys64\usr\bin\pacman --noconfirm
 
 jobs:
 
@@ -35,11 +38,11 @@ jobs:
     - name: Build alr
       run: gprbuild -j0 -p -P alr_env
 
-    - name: alr first run to install msys2
-      run: ./bin/alr --non-interactive help get
+    - name: Display built alr and trigger install of msys2
+      run: ./bin/alr version
 
     - name: install tar from msys2 (Git tar in Actions VM does not seem to work)
-      run: C:\Users\runneradmin\AppData\Local\alire\msys64\usr\bin\pacman --noconfirm -S tar
+      run: ${{env.PACMAN}} -S tar
 
     - name: Install Python 3.x (required for the testsuite)
       uses: actions/setup-python@v2
@@ -57,17 +60,17 @@ jobs:
       run: gprinstall -p -P alr_env --prefix=${{ runner.temp }}/alr_install
 
     - name: Install qt-installer-framework in msys2
-      run: C:\Users\runneradmin\AppData\Local\alire\msys64\usr\bin\pacman --noconfirm -S mingw64/mingw-w64-x86_64-qt-installer-framework
+      run: ${{env.PACMAN}} -S mingw64/mingw-w64-x86_64-qt-installer-framework
 
     - name: Add msys2 /mingw64/bin to the path (for qt-installer-framework)
-      run: echo 'C:\Users\runneradmin\AppData\Local\alire\msys64\mingw64\bin' >> $GITHUB_PATH
+      run: echo '${{env.MINGW64_PATH}}' >> $GITHUB_PATH
       shell: bash
 
     - name: Install zip in msys2
-      run: C:\Users\runneradmin\AppData\Local\alire\msys64\usr\bin\pacman --noconfirm -S zip
+      run: ${{env.PACMAN}} --noconfirm -S zip
 
     - name: Add msys2 /usr/bin to the path (for zip)
-      run: echo 'C:\Users\runneradmin\AppData\Local\alire\msys64\usr\bin' >> $GITHUB_PATH
+      run: echo '${{env.MSYS2_PATH}}' >> $GITHUB_PATH
       shell: bash
 
     - name: Run installer build script

UPGRADING.md

@@ -3,6 +3,25 @@
 There are no special preparations to be made in advance to upgrading. However,
 please check out the following information.
 
+### Refactored features
+
+The following features have changed in version `2.0`, with the corresponding
+replacements:
+
+- "Alire configuration" is now renamed to "Alire settings", to distinguish it
+  from a crate configuration. This entails a few changes:
+  - `ALR_CONFIG` environment variable is now `ALIRE_SETTINGS_DIR`.
+  - `alr config` is now `alr settings`.
+  - `alr -c|--config` is now `alr -s|--settings`.
+
+- Installation of toolchains for use outside of Alire control is no longer done
+  through `alr toolchain`, but through `alr install`:
+  - `alr toolchain --install|--uninstall|--install-dir` no longer exist.
+  - `alr toolchain --select` remains as the way to select a default toolchain
+    for use by Alire.
+  - `alr install` will create a standard prefix structure, with binaries found
+    at `<prefix>/bin`. The default prefix location is `<user home>/.alire`.
+
 ### Obsolete large folders
 
 Changes in default storage locations mean that the following folders, if
@@ -33,9 +52,9 @@ If you want to have a fallback to be able to downgrade, you have two safe
 options:
 
 - Use the newer version with its own separate configuration storage. You can override
-  the default location by providing a new path in the `ALR_CONFIG` environment
+  the default location by providing a new path in the `ALIRE_SETTINGS_DIR` environment
   variable.
 
 - Keep a backup of your current configuration at the default location, which is
   `.config/alire` within your user's home. You can restore this folder in sync with
-  its older `alr` version.
+  its older `alr` version.

doc/catalog-format-spec.md

@@ -1169,7 +1169,7 @@ project My_Crate is
 
 Dependencies in Alire are used also to deal with compiler versions and
 cross-compilers. Also related is the information on toolchains available in the
-[Toolchain management](./toolchains.md) document or via `alr help toolchains`.
+[Toolchain management](toolchains) document or via `alr help toolchains`.
 
 ### Excluding compiler versions
 

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 settings`, to allow uninterrupted configuration, and setting
+  of `msys2` location (see `alr help settings`), 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,17 @@ 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 settings may be the source of some problem, please check
+our section on [Settings](setting), and in particular how to use a [default
+pristine settings](settings#Relocating-your-settings)
 
 ## Running tests
 

doc/policies.md

@@ -60,7 +60,7 @@ major/minor/patch/build version changes), but not modified.
   - Tests, demos, examples, etc., can be provided in nested crates so they can
     be conveniently used locally when needed without causing extra build load
     on clients. See the documentation on
-    [local pins](catalog-format-spec.md#using-pins-for-crate-testing) for
+    [local pins](catalog-format-spec#using-pins-for-crate-testing) for
     details.
 
   - The manifests of these nested crates need not to be published to the

doc/publishing.md

@@ -57,7 +57,7 @@ crate and version it contains. A file contains the description of a release,
 with other metadata.
 
 The complete specification of such TOML files is available in this
-[document](catalog-format-spec.md).
+[document](catalog-format-spec).
 
 ## New crates and releases
 
@@ -88,7 +88,7 @@ release of `alr`.
 
 Each crate is "owned" by a list of maintainers, provided with the
 `maintainers-logins` property of the crate file. After the initial submission,
-which will be manually approved (see the [policies](policies.md) for details),
+which will be manually approved (see the [policies](policies) for details),
 the maintainers of a crate are the only people allowed to submit new releases
 or metadata modifications to the corresponding crate.
 
@@ -100,7 +100,7 @@ Other checks your submission will go through are:
 
 ## Best practices
 
-See the section on [best practices](policies.md#best-practices) for crates
+See the section on [best practices](policies#best-practices) for crates
 before publishing your first release.
 
 ## Detailed steps

doc/settings.md

@@ -0,0 +1,84 @@
+# Settings
+
+`alr` provides a generic mechanism to `list`, `get`, `set` or
+`unset` settings options, either in a local or global context.
+
+ Option names (keys) can use lowercase and uppercase alphanumeric characters
+ from the Latin alphabet. Underscores and dashes can also be used except as
+ the first or last character. Dot '.' is used to specify sub-categories, e.g.
+ 'user.name' or 'user.email'.
+
+ Option values can be integers, floats, Booleans (true or false), or strings. The
+ type detection is automatic, e.g. 10 is integer, 10.1 is float, true is
+ Boolean. You can force a value to be a string by using double-quotes, e.g.
+ "10.1" or "true". Extra type checking is used for built-in options (see below).
+
+ Specific settings options:
+
+  - `--list` List settings options
+  - `--show-origin` Show origin of settings values in `--list`
+  - `--get` Print value of a setting option
+  - `--set` Set a setting option
+  - `--unset` Unset a setting option
+  - `--global `Set and Unset global settings instead of the local one
+  - `--builtins-doc` Print Markdown list of built-in settings
+
+ Examples:
+
+ - `alr settings --global --set my_option option_value`
+
+    Will set a setting option with the key `my_option` and the string
+    value `option_value` in the global settings file.
+
+ - `alr settings --get my_option`
+
+    Will print the value setting option `my_option` if it is defined,
+    otherwise the command fails.
+
+
+## Custom settings options
+
+The `alr settings` command allows you to set and get any combination of option
+`key` and `value`. You can use this feature to store your own project related
+settings, or implement tools that integrate in an `Alire` context. However, be
+careful when naming custom settings options because `Alire` may use the same
+`key` in the future. We recommend using a distinctive sub-category name, for
+instance: `my_project.my_option`.
+
+## Built-in settings options
+
+The options used by `Alire` are pre-defined and documented. We call these
+options `built-ins`.
+
+A built-in option has a pre-defined type that is checked when setting or
+loading. For instance:
+
+ - `alr settings --global --set user.email "This is not an email address"`
+
+will fail because the value tentatively assigned to `user.email` is not an
+email address.
+
+The built-ins also have a short description to document their type and usage.
+
+## Built-ins list
+
+You can get the list of options recognized by `alr` with `alr help settings`,
+including their default values and a short explanation of their effects.
+
+## Relocating your settings
+
+By default, `alr` stores its global settings at `<user home>/.config/alire`.
+You can use any other location by setting in the environment the variable
+`ALIRE_SETTINGS_DIR=</absolute/path/to/settings/folder>`, or by using the global `-s`
+switch: `alr -s </path/to/settings> <command>`.
+
+Using pristine default settings can be useful to isolate the source of errors
+by ensuring that a misconfiguration is not at play.
+
+## Inspecting your settings
+
+These commands may help you in identifying Alire settings and environment:
+- `alr settings --list` will show all settings 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.