Make build scripts' -help information more helpful (#37377)

* Sorted the build scripts' help alphabetically, and made the subset error
message softer and without metrics.

* Added simple examples to the scripts' helps.

* Moved short flags to the flag column and rephrased a bit.

* Removed remains of old code.

* Added more examples and rephrased some things for better clarity.

* Added gcc example to build.sh.

* Corrected definition of the Checked configuration.

* Added --clangx to build.sh

1 files changed, 75 insertions, 25 deletions

diff --git a/eng/build.ps1 b/eng/build.ps1
index f8f1164bcaf..651a17ad820 100644
--- a/eng/build.ps1
+++ b/eng/build.ps1
@@ -20,39 +20,84 @@ Param(
 
 function Get-Help() {
   Write-Host "Common settings:"
-  Write-Host "  -subset                   Build a subset, print available subsets with -subset help (short: -s)"
-  Write-Host "  -vs                       Open the solution with VS using the locally acquired SDK. Path or solution name (ie -vs Microsoft.CSharp)"
-  Write-Host "  -os                       Build operating system: Windows_NT, Linux, OSX, or Browser"
-  Write-Host "  -arch                     Build platform: x86, x64, arm, arm64, or wasm (short: -a). Pass a comma-separated list to build for multiple architectures."
-  Write-Host "  -configuration            Build configuration: Debug, Release or [CoreCLR]Checked (short: -c). Pass a comma-separated list to build for multiple configurations"
-  Write-Host "  -runtimeConfiguration     Runtime build configuration: Debug, Release or [CoreCLR]Checked (short: -rc)"
-  Write-Host "  -librariesConfiguration   Libraries build configuration: Debug or Release (short: -lc)"
-  Write-Host "  -verbosity                MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic] (short: -v)"
-  Write-Host "  -binaryLog                Output binary log (short: -bl)"
-  Write-Host "  -help                     Print help and exit (short: -h)"
+  Write-Host "  -arch (-a)                     Target platform: x86, x64, arm, arm64, or wasm."
+  Write-Host "                                 Pass a comma-separated list to build for multiple architectures."
+  Write-Host "                                 [Default: Your machine's architecture.]"
+  Write-Host "  -binaryLog (-bl)               Output binary log."
+  Write-Host "  -configuration (-c)            Build configuration: Debug, Release or Checked."
+  Write-Host "                                 Checked is exclusive to the CLR subset. It is the same as Debug, except code is"
+  Write-Host "                                 compiled with optimizations enabled."
+  Write-Host "                                 Pass a comma-separated list to build for multiple configurations."
+  Write-Host "                                 [Default: Debug]"
+  Write-Host "  -help (-h)                     Print help and exit."
+  Write-Host "  -librariesConfiguration (-lc)  Libraries build configuration: Debug or Release."
+  Write-Host "                                 [Default: Debug]"
+  Write-Host "  -os                            Target operating system: Windows_NT, Linux, OSX, or Browser."
+  Write-Host "                                 [Default: Your machine's OS.]"
+  Write-Host "  -runtimeConfiguration (-rc)    Runtime build configuration: Debug, Release or Checked."
+  Write-Host "                                 Checked is exclusive to the CLR runtime. It is the same as Debug, except code is"
+  Write-Host "                                 compiled with optimizations enabled."
+  Write-Host "                                 [Default: Debug]"
+  Write-Host "  -subset (-s)                   Build a subset, print available subsets with -subset help."
+  Write-Host "                                 '-subset' can be omitted if the subset is given as the first argument."
+  Write-Host "                                 [Default: Builds the entire repo.]"
+  Write-Host "  -verbosity (-v)                MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]."
+  Write-Host "                                 [Default: Minimal]"
+  Write-Host "  -vs                            Open the solution with Visual Studio using the locally acquired SDK."
+  Write-Host "                                 Path or any project or solution name is accepted."
+  Write-Host "                                 (Example: -vs Microsoft.CSharp)"
   Write-Host ""
 
   Write-Host "Actions (defaults to -restore -build):"
-  Write-Host "  -restore                Restore dependencies"
-  Write-Host "  -build                  Build all source projects (short: -b)"
-  Write-Host "  -rebuild                Rebuild all source projects"
-  Write-Host "  -test                   Build and run tests (short: -t)"
-  Write-Host "  -pack                   Package build outputs into NuGet packages"
-  Write-Host "  -sign                   Sign build outputs"
-  Write-Host "  -publish                Publish artifacts (e.g. symbols)"
-  Write-Host "  -clean                  Clean the solution"
+  Write-Host "  -build (-b)             Build all source projects."
+  Write-Host "                          This assumes -restore has been run already."
+  Write-Host "  -clean                  Clean the solution."
+  Write-Host "  -pack                   Package build outputs into NuGet packages."
+  Write-Host "  -publish                Publish artifacts (e.g. symbols)."
+  Write-Host "                          This assumes -build has been run already."
+  Write-Host "  -rebuild                Rebuild all source projects."
+  Write-Host "  -restore                Restore dependencies."
+  Write-Host "  -sign                   Sign build outputs."
+  Write-Host "  -test (-t)              Incrementally builds and runs tests."
+  Write-Host "                          Use in conjuction with -testnobuild to only run tests."
   Write-Host ""
 
   Write-Host "Libraries settings:"
-  Write-Host "  -framework              Build framework: net5.0 or net472 (short: -f)"
-  Write-Host "  -coverage               Collect code coverage when testing"
-  Write-Host "  -testscope              Scope tests, allowed values: innerloop, outerloop, all"
-  Write-Host "  -testnobuild            Skip building tests when invoking -test"
-  Write-Host "  -allconfigurations      Build packages for all build configurations"
+  Write-Host "  -allconfigurations      Build packages for all build configurations."
+  Write-Host "  -coverage               Collect code coverage when testing."
+  Write-Host "  -framework (-f)         Build framework: net5.0 or net472."
+  Write-Host "                          [Default: net5.0]"
+  Write-Host "  -testnobuild            Skip building tests when invoking -test."
+  Write-Host "  -testscope              Scope tests, allowed values: innerloop, outerloop, all."
   Write-Host ""
 
-  Write-Host "Command-line arguments not listed above are passed thru to msbuild."
-  Write-Host "The above arguments can be shortened as much as to be unambiguous (e.g. -con for configuration, -t for test, etc.)."
+  Write-Host "Command-line arguments not listed above are passed through to MSBuild."
+  Write-Host "The above arguments can be shortened as much as to be unambiguous."
+  Write-Host "(Example: -con for configuration, -t for test, etc.)."
+  Write-Host ""
+
+  Write-Host "Here are some quick examples. These assume you are on a Windows x64 machine:"
+  Write-Host ""
+  Write-Host "* Build CoreCLR for Windows x64 on Release configuration:"
+  Write-Host ".\build.cmd clr -c release"
+  Write-Host ""
+  Write-Host "* Cross-compile CoreCLR runtime for Windows ARM64 on Release configuration."
+  Write-Host ".\build.cmd clr.runtime -arch arm64 -c release"
+  Write-Host ""
+  Write-Host "* Build Debug libraries with a Release runtime for Windows x64."
+  Write-Host ".\build.cmd clr+libs -rc release"
+  Write-Host ""
+  Write-Host "* Build Release libraries and their tests with a Checked runtime for Windows x64, and run the tests."
+  Write-Host ".\build.cmd clr+libs+libs.tests -rc checked -lc release -test"
+  Write-Host ""
+  Write-Host "* Build Mono runtime for Windows x64 on Release configuration."
+  Write-Host ".\build.cmd mono -c release"
+  Write-Host ""
+  Write-Host "It's important to mention that to build Mono for the first time,"
+  Write-Host "you need to build the CLR and Libs subsets beforehand."
+  Write-Host "This is done automatically if a full build is performed at first."
+  Write-Host ""
+  Write-Host "For more information, check out https://github.com/dotnet/runtime/blob/master/docs/workflow/README.md"
 }
 
 if ($help -or (($null -ne $properties) -and ($properties.Contains('/help') -or $properties.Contains('/?')))) {
@@ -60,6 +105,11 @@ if ($help -or (($null -ne $properties) -and ($properties.Contains('/help') -or $
   exit 0
 }
 
+if ($subset -eq 'help') {
+  Invoke-Expression "& `"$PSScriptRoot/common/build.ps1`" -restore -build /p:subset=help /clp:nosummary"
+  exit 0
+}
+
 if ($vs) {
   . $PSScriptRoot\common\tools.ps1