Code review

doc/user-changes.md

@@ -8,8 +8,6 @@ stay on top of `alr` new features.
 
 ### New switch `alr build --stop-after=<build stage>`
 
-### Enable shared dependencies by default
-
 PR [#1573](https://github.com/alire-project/alire/pull/1573)
 
 From `alr help build`:
@@ -25,6 +23,37 @@ From `alr help build`:
    * build: actual building of sources
    * post-build: running of post-build actions
 
+### Enable shared dependencies by default
+
+PR [#1449](https://github.com/alire-project/alire/pull/1449)
+
+Pre-2.0, Alire worked always in "sandboxed" mode; that is, all source
+dependencies were found under `<workspace>/alire/cache`. This behavior can be
+now enabled with `alr config --set dependencies.shared false`, locally or
+globally.
+
+By default, post-2.0, Alire works in "shared" mode, where sources are
+downloaded once (to `~/.cache/alire/releases`) and unique builds are created
+(under `~/.cache/alire/builds`) for unique configurations. This should minimize
+rebuilds across crate configurations and workspaces, and eliminate risks of
+inconsistencies.
+
+Disk use is decreased by unique source downloads, but might be increased by
+unique build configurations. Cache management and cleanup will be provided down
+the road. The build cache can always be deleted to retrieve disk space, at the
+cost of triggering rebuilds.
+
+Unique builds are identified by a build hash which takes into account the
+following inputs for a given release:
+
+- Build profile
+- Environment variables modified in the manifest
+- GPR external variables declared or set
+- Configuration variables declared or set
+- Compiler version
+- Vaue of `LIBRARY_TYPE` and `<CRATE>_LIBRARY_TYPE` variables.
+- Hash of dependencies
+
 ### Automatic index updates
 
 PR [#1447](https://github.com/alire-project/alire/pull/1447)

src/alr/alr-commands-build.adb

@@ -230,6 +230,17 @@ package body Alr.Commands.Build is
         .Append (Stage (Pre_Build, " running of pre-build actions"))
         .Append (Stage (Building, "     actual building of sources"))
         .Append (Stage (Post_Build, "running of post-build actions"))
+        .New_Line
+        .Append ("These stages are always run in the given order. A premature"
+                 & " stop will likely not produce the complete build "
+                 & "artifacts, so it is intended for advanced usage when "
+                 & "debugging or testing specific build stages, or to ensure "
+                 & "generated files are up-to-date without launching a "
+                 & "costly build, for example.")
+        .New_Line
+        .Append ("After a partial build, to ensure a proper full build is"
+                 & " performed, just run a regular "
+                 & TTY.Terminal ("alr build") &  " without " & Switch_Stop)
       ;
    end Long_Description;