Refine corerun instructions. Improve argument parsing in src/tests/build. (#81733)

* Refine corerun instructions. Improve arg parsing in src/tests/build.

* Revert the libraries configuration default. Refine usage and docs.

* Exit argument processing at first unrecognized arg per existing pipeline usage

diff --git a/docs/workflow/testing/coreclr/running-aspnet-benchmarks-with-crossgen2.md b/docs/workflow/testing/coreclr/running-aspnet-benchmarks-with-crossgen2.md
index fbedaf7..c4f8909 100644 (file)
--- a/docs/workflow/testing/coreclr/running-aspnet-benchmarks-with-crossgen2.md
+++ b/docs/workflow/testing/coreclr/running-aspnet-benchmarks-with-crossgen2.md
@@ -192,7 +192,7 @@ CoreRun.exe \runtime\artifacts\bin\coreclr\windows.x64.Release\crossgen2\crossge
 On Linux:
 
 ```bash
-./corerun /runtime/artifacts/bin/coreclr/Linux.x64.Release/crossgen2/crossgen2.dll
+corerun /runtime/artifacts/bin/coreclr/Linux.x64.Release/crossgen2/crossgen2.dll
 --Os --composite -o /path/to/results/composite/TotalComposite.dll /path/to/results/application/*.dll
 ```
 

diff --git a/docs/workflow/testing/using-corerun-and-coreroot.md b/docs/workflow/testing/using-corerun-and-coreroot.md
index 3784e0c..f53e2ea 100644 (file)
--- a/docs/workflow/testing/using-corerun-and-coreroot.md
+++ b/docs/workflow/testing/using-corerun-and-coreroot.md
@@ -53,9 +53,9 @@ dotnet new console
 dotnet build
 ```
 
-Now, instead of running our app the usual way, we will use our newly built `corerun` to execute it using our build of the runtime. For this, we will follow the steps denoted below:
+Now, instead of running our app the usual way, we will use `corerun` to execute it using our build of the runtime. The `corerun` executable is created as part of building the `clr` subset, and it will exist in the `<repo root>/artifacts/bin/coreclr/<OS>.<Arch>.<Configuration>` folder. For this, we will follow the steps denoted below:
 
-* First we will add the `Core_Root` folder to the `PATH` environment variable for ease of use. Note that you can always skip this step and fully qualify the name instead.
+* First we will add `corerun`'s folder to the `PATH` environment variable for ease of use. Note that you can always skip this step and fully qualify the name instead.
   * This example assumes you built on the _Debug_ configuration for the _x64_ architecture. Make sure you adjust the path accordingly to your kind of build.
 * Then, we also need the libraries. Since we only built the runtime, we will tell `corerun` to use the ones shipped with .NET's default installation on your machine.
   * This example assumes your default .NET installation's version is called "_7.0.0_". Same deal as with your runtime build path, adjust to the version you have installed on your machine.
@@ -78,7 +78,7 @@ export CORE_LIBRARIES="/usr/local/share/dotnet/shared/Microsoft.NETCore.App/7.0.
 corerun HelloWorld.dll
 ```
 
-On Powershell:
+On PowerShell:
 
 ```powershell
 # Note the '+=' since we're appending to the already existing PATH variable.
@@ -98,7 +98,7 @@ When an application is published as self-contained (`dotnet publish --self-conta
 
 The test build script (`src/tests/build.cmd` or `src/tests/build.sh`) sets up a directory where it gathers the CoreCLR that has just been built with the pieces of the class libraries that the tests need. It places these binaries in the directory `artifacts/tests/coreclr/<OS>.<Arch>.<Configuration>/Tests/Core_Root`. Note that the test building process is a lengthy one, so it is recommended to only generate the Core_Root with the `-generatelayoutonly` flag to the tests build script, and build individual tests and/or test trees as you need them.
 
-**NOTE**: In order to generate the Core_Root, you must also have built the libraries beforehand with `-subset libs`. More details in the [testing CoreCLR doc](/docs/workflow/testing/coreclr/testing.md).
+**NOTE**: In order to generate the Core_Root, you must also have built the libraries beforehand with `-subset libs`. Running the tests build script by default searches the libraries in _Release_ mode, regardless of the runtime configuration you specify. If you built your libraries in another configuration, then you have to pass down the appropriate flag `/p:LibrariesConfiguration=<your_config>`. More details in the [testing CoreCLR doc](/docs/workflow/testing/coreclr/testing.md).
 
 Once you have your Core_Root, it's just a matter of calling it directly or adding it to your `PATH` environment variable, and you're ready to run your apps with it.
 
@@ -117,13 +117,13 @@ export PATH="$PATH:<repo_root>/artifacts/tests/coreclr/linux.x64.Debug/Tests/Cor
 corerun HelloWorld.dll
 ```
 
-On Powershell:
+On PowerShell:
 
 ```powershell
 # Note the '+=' since we're appending to the already existing PATH variable.
 # Also, replace the ';' with ':' if on Linux or macOS.
 $Env:PATH += ';<repo_root>\artifacts\tests\coreclr\windows.x64.Debug\Tests\Core_Root'
-.\corerun HelloWorld.dll
+corerun HelloWorld.dll
 ```
 
 The advantage of generating the Core_Root, instead of sticking to the _corerun_ from the _clr_ build, is that you can also test and debug libraries at the same time.

diff --git a/src/tests/build.cmd b/src/tests/build.cmd
index 5f39518..6fad9b0 100644 (file)
--- a/src/tests/build.cmd
+++ b/src/tests/build.cmd
@@ -30,6 +30,7 @@ set "__MsbuildDebugLogsDir=%__LogsDir%\MsbuildDebugLogs"
 set __Exclude=%__RepoRootDir%\src\tests\issues.targets
 
 REM __UnprocessedBuildArgs are args that we pass to msbuild (e.g. /p:TargetArchitecture=x64)
+set __commandName=%~nx0
 set "__args= %*"
 set processedArgs=
 set __UnprocessedBuildArgs=
@@ -39,7 +40,6 @@ set __RebuildTests=0
 set __BuildTestProject=%%3B
 set __BuildTestDir=%%3B
 set __BuildTestTree=%%3B
-
 set __BuildLogRootName=TestBuild
 
 set __SkipRestorePackages=0
@@ -69,57 +69,76 @@ set __BuildNeedTargetArg=
 :Arg_Loop
 if "%1" == "" goto ArgsDone
 
-if /i "%1" == "/?"     goto Usage
-if /i "%1" == "-?"     goto Usage
-if /i "%1" == "/h"     goto Usage
-if /i "%1" == "-h"     goto Usage
-if /i "%1" == "/help"  goto Usage
-if /i "%1" == "-help"  goto Usage
-if /i "%1" == "--help" goto Usage
-
-if /i "%1" == "x64"                   (set __BuildArch=x64&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "x86"                   (set __BuildArch=x86&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "arm"                   (set __BuildArch=arm&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "arm64"                 (set __BuildArch=arm64&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-
-if /i "%1" == "debug"                 (set __BuildType=Debug&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "release"               (set __BuildType=Release&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "checked"               (set __BuildType=Checked&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-
-if /i "%1" == "ci"                    (set __ArcadeScriptArgs="-ci"&set __ErrMsgPrefix=##vso[task.logissue type=error]&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-
-if /i "%1" == "skiprestorepackages"   (set __SkipRestorePackages=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "skipmanaged"           (set __SkipManaged=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "skipnative"            (set __SkipNative=1&set __CopyNativeProjectsAfterCombinedTestBuild=false&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "skiptestwrappers"      (set __SkipTestWrappers=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "skipgeneratelayout"    (set __SkipGenerateLayout=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-
-if /i "%1" == "rebuild"               (set __RebuildTests=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-
-if /i "%1" == "test"                  (set __BuildTestProject=!__BuildTestProject!%2%%3B&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
-if /i "%1" == "dir"                   (set __BuildTestDir=!__BuildTestDir!%2%%3B&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
-if /i "%1" == "tree"                  (set __BuildTestTree=!__BuildTestTree!%2%%3B&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
-
-if /i "%1" == "log"                   (set __BuildLogRootName=%2&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
-
-if /i "%1" == "copynativeonly"        (set __CopyNativeTestBinaries=1&set __SkipNative=1&set __CopyNativeProjectsAfterCombinedTestBuild=false&set __SkipGenerateLayout=1&set __SkipTestWrappers=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "generatelayoutonly"    (set __SkipManaged=1&set __SkipNative=1&set __CopyNativeProjectsAfterCombinedTestBuild=false&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "buildtestwrappersonly" (set __SkipNative=1&set __SkipManaged=1&set __BuildTestWrappersOnly=1&set __SkipGenerateLayout=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "-cmakeargs"            (set __CMakeArgs="%2=%3" %__CMakeArgs%&set "processedArgs=!processedArgs! %1 %2=%3"&shift&shift&goto Arg_Loop)
-if /i "%1" == "-msbuild"              (set __Ninja=0&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "buildagainstpackages"  (echo error: Remove /BuildAgainstPackages switch&&exit /b1)
-if /i "%1" == "crossgen2"             (set __TestBuildMode=crossgen2&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "composite"             (set __CompositeBuildMode=1&set __TestBuildMode=crossgen2&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "pdb"                   (set __CreatePdb=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "nativeaot"             (set __TestBuildMode=nativeaot&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "perfmap"               (set __CreatePerfmap=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "Exclude"               (set __Exclude=%2&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
-if /i "%1" == "-priority"             (set __Priority=%2&shift&set processedArgs=!processedArgs! %1=%2&shift&goto Arg_Loop)
-if /i "%1" == "allTargets"            (set "__BuildNeedTargetArg=/p:CLRTestBuildAllTargets=%1"&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "-excludemonofailures"  (set __Mono=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "-mono"                 (set __Mono=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "mono"                  (set __Mono=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
-if /i "%1" == "--"                    (set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+@REM All arguments following this tag will be passed directly to msbuild (as unprocessed arguments)
+if /i "%1" == "--"                       (set processedArgs=!processedArgs! %1&shift&goto ArgsDone)
+
+@REM The following arguments do not support '/', '-', or '--' prefixes
+if /i "%1" == "x64"                      (set __BuildArch=x64&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%1" == "x86"                      (set __BuildArch=x86&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%1" == "arm"                      (set __BuildArch=arm&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%1" == "arm64"                    (set __BuildArch=arm64&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+
+if /i "%1" == "debug"                    (set __BuildType=Debug&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%1" == "release"                  (set __BuildType=Release&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%1" == "checked"                  (set __BuildType=Checked&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+
+if /i "%1" == "ci"                       (set __ArcadeScriptArgs="-ci"&set __ErrMsgPrefix=##vso[task.logissue type=error]&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+
+@REM For the arguments below, we support '/', '-', and '--' prefixes.
+@REM But we also recognize them without prefixes at all. To achieve that,
+@REM we remove the '/' and '-' characters from the string for comparison.
+
+set arg=%~1
+set arg=%arg:/=%
+set arg=%arg:-=%
+
+if /i "%arg%" == "?"     goto Usage
+if /i "%arg%" == "h"     goto Usage
+if /i "%arg%" == "help"  goto Usage
+
+@REM Specify this argument to test the argument parsing logic of this script without executing the build
+if /i "%arg%" == "TestArgParsing"        (set __TestArgParsing=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+
+@REM The following arguments are switches that do not consume any subsequent arguments
+if /i "%arg%" == "Rebuild"               (set __RebuildTests=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "SkipRestorePackages"   (set __SkipRestorePackages=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "SkipManaged"           (set __SkipManaged=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "SkipNative"            (set __SkipNative=1&set __CopyNativeProjectsAfterCombinedTestBuild=false&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "SkipTestWrappers"      (set __SkipTestWrappers=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "SkipGenerateLayout"    (set __SkipGenerateLayout=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+
+if /i "%arg%" == "CopyNativeOnly"        (set __CopyNativeTestBinaries=1&set __SkipNative=1&set __CopyNativeProjectsAfterCombinedTestBuild=false&set __SkipGenerateLayout=1&set __SkipTestWrappers=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "GenerateLayoutOnly"    (set __GenerateLayoutOnly=1&set __SkipManaged=1&set __SkipNative=1&set __CopyNativeProjectsAfterCombinedTestBuild=false&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "BuildTestWrappersOnly" (set __SkipNative=1&set __SkipManaged=1&set __BuildTestWrappersOnly=1&set __SkipGenerateLayout=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "MSBuild"               (set __Ninja=0&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "crossgen2"             (set __TestBuildMode=crossgen2&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "composite"             (set __CompositeBuildMode=1&set __TestBuildMode=crossgen2&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "pdb"                   (set __CreatePdb=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "NativeAOT"             (set __TestBuildMode=nativeaot&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "Perfmap"               (set __CreatePerfmap=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "AllTargets"            (set "__BuildNeedTargetArg=/p:CLRTestBuildAllTargets=%1"&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "ExcludeMonoFailures"   (set __Mono=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+if /i "%arg%" == "Mono"                  (set __Mono=1&set processedArgs=!processedArgs! %1&shift&goto Arg_Loop)
+
+@REM The following arguments also consume one subsequent argument
+if /i "%arg%" == "test"                  (set __BuildTestProject=!__BuildTestProject!%2%%3B&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
+if /i "%arg%" == "dir"                   (set __BuildTestDir=!__BuildTestDir!%2%%3B&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
+if /i "%arg%" == "tree"                  (set __BuildTestTree=!__BuildTestTree!%2%%3B&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
+if /i "%arg%" == "log"                   (set __BuildLogRootName=%2&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
+if /i "%arg%" == "exclude"               (set __Exclude=%2&set processedArgs=!processedArgs! %1 %2&shift&shift&goto Arg_Loop)
+if /i "%arg%" == "priority"              (set __Priority=%2&set processedArgs=!processedArgs! %1=%2&shift&shift&goto Arg_Loop)
+
+@REM The following arguments also consume two subsequent arguments
+if /i "%arg%" == "CMakeArgs"             (set __CMakeArgs="%2=%3" %__CMakeArgs%&set "processedArgs=!processedArgs! %1 %2 %3"&shift&shift&shift&goto Arg_Loop)
+
+@REM Obsolete arguments that now produce errors
+if /i "%arg%" == "BuildAgainstPackages"  (echo error: Remove /BuildAgainstPackages switch&&exit /b 1)
+
+@REM If we encounter an unrecognized argument, then all remaining arguments are passed directly to MSBuild
+@REM This allows '/p:LibrariesConfiguration=Release' and other arguments to be passed through without having
+@REM '/p:LibrariesConfiguration' and 'Release' get handled as separate arguments.
+
+:ArgsDone
 
 if [!processedArgs!]==[] (
     set __UnprocessedBuildArgs=%__args%
@@ -130,7 +149,37 @@ if [!processedArgs!]==[] (
     )
 )
 
-:ArgsDone
+if defined __TestArgParsing (
+    echo.
+    echo.PROCESSED ARGS: "%processedArgs%"
+    echo.
+    echo.UNPROCESSED ARGS: "%__UnprocessedBuildArgs%"
+    echo.
+    echo.__BuildArch=%__BuildArch%
+    echo.__BuildType=%__BuildType%
+    echo.__Exclude=%__Exclude%
+    echo.__RebuildTests=%__RebuildTests%
+    echo.__BuildTestProject=%__BuildTestProject%
+    echo.__BuildTestDir=%__BuildTestDir%
+    echo.__BuildTestTree=%__BuildTestTree%
+    echo.__BuildLogRootName=%__BuildLogRootName%
+    echo.__SkipRestorePackages=%__SkipRestorePackages%
+    echo.__SkipManaged=%__SkipManaged%
+    echo.__SkipTestWrappers=%__SkipTestWrappers%
+    echo.__BuildTestWrappersOnly=%__BuildTestWrappersOnly%
+    echo.__SkipNative=%__SkipNative%
+    echo.__CompositeBuildMode=%__CompositeBuildMode%
+    echo.__TestBuildMode=%__TestBuildMode%
+    echo.__CreatePdb=%__CreatePdb%
+    echo.__CreatePerfmap=%__CreatePerfmap%
+    echo.__CopyNativeTestBinaries=%__CopyNativeTestBinaries%
+    echo.__CopyNativeProjectsAfterCombinedTestBuild=%__CopyNativeProjectsAfterCombinedTestBuild%
+    echo.__SkipGenerateLayout=%__SkipGenerateLayout%
+    echo.__GenerateLayoutOnly=%__GenerateLayoutOnly%
+    echo.__Ninja=%__Ninja%
+    echo.__CMakeArgs=%__CMakeArgs%
+    echo.
+)
 
 @if defined _echo @echo on
 
@@ -191,6 +240,10 @@ set __msbuildArgs=%__CommonMSBuildArgs% /nologo /verbosity:minimal /clp:Summary
 
 echo Common MSBuild args: %__msbuildArgs%
 
+if defined __TestArgParsing (
+    EXIT /b 0
+)
+
 call %__RepoRootDir%\eng\native\init-vs-env.cmd %__BuildArch%
 if NOT '%ERRORLEVEL%' == '0' exit /b 1
 
@@ -315,37 +368,49 @@ echo.
 echo Build the CoreCLR tests.
 echo.
 echo Usage:
-echo     %0 [option1] [option2] ...
-echo All arguments are optional. Options are case-insensitive. The options are:
+echo     %__commandName% [option1] [option2] ...
+echo All arguments are optional and case-insensitive, and the '-' prefix is optional. The options are:
 echo.
-echo.-? -h -help --help: view this message.
-echo Build architecture: one of x64, x86, arm, arm64 ^(default: x64^).
-echo Build type: one of Debug, Checked, Release ^(default: Debug^).
-echo skipgeneratelayout: Do not generate the Core_Root layout
-echo skipmanaged: skip the managed tests build
-echo skipnative: skip the native tests build
-echo skiprestorepackages: skip package restore
-echo skiptestwrappers: skip generating test wrappers
-echo buildtestwrappersonly: generate test wrappers without building managed or native test components or generating layouts
-echo copynativeonly: Only copy the native test binaries to the managed output. Do not build the native or managed tests.
-echo crossgen2: Precompiles the framework managed assemblies
-echo composite: Precompiles the framework managed assemblies in composite build mode
-echo pdb: create PDB files when precompiling the framework managed assemblies
-echo generatelayoutonly: Generate the Core_Root layout without building managed or native test components
-echo Exclude- Optional parameter - specify location of default exclusion file ^(defaults to tests\issues.targets if not specified^)
+echo.-? -h --help: View this message.
+echo.
+echo Build architecture: one of "x64", "x86", "arm", "arm64" ^(default: x64^).
+echo Build type: one of "Debug", "Checked", "Release" ^(default: Debug^).
+echo.
+echo -Rebuild: Clean up all test artifacts prior to building tests.
+echo -SkipRestorePackages: Skip package restore.
+echo -SkipManaged: Skip the managed tests build.
+echo -SkipNative: Skip the native tests build.
+echo -SkipTestWrappers: Skip generating test wrappers.
+echo -SkipGenerateLayout: Skip generating the Core_Root layout.
+echo.
+echo -CopyNativeOnly: Only copy the native test binaries to the managed output. Do not build the native or managed tests.
+echo -GenerateLayoutOnly: Only generate the Core_Root layout without building managed or native test components.
+echo -BuildTestWrappersOnly: Only generate test wrappers without building managed or native test components or generating layouts.
+echo -MSBuild: Use MSBuild instead of Ninja.
+echo -Crossgen2: Precompiles the framework managed assemblies in coreroot using the Crossgen2 compiler.
+echo -Composite: Use Crossgen2 composite mode (all framework gets compiled into a single native R2R library).
+echo -PDB: Create PDB files when precompiling the framework managed assemblies.
+echo -NativeAOT: Builds the tests for Native AOT compilation.
+echo -Perfmap: Emit perfmap symbol files when compiling the framework assemblies using Crossgen2.
+echo -AllTargets: Build managed tests for all target platforms (including test projects in which CLRTestTargetUnsupported resolves to true).
+echo -ExcludeMonoFailures, Mono: Build the tests for the Mono runtime honoring mono-specific issues.
+echo.
+echo -Exclude ^<xxx^>: Specify location of default exclusion file ^(defaults to tests\issues.targets if not specified^).
 echo     Set to "" to disable default exclusion file.
-echo -- ... : all arguments following this tag will be passed directly to msbuild.
-echo -priority=^<N^> : specify a set of tests that will be built and run, with priority N.
-echo     0: Build only priority 0 cases as essential testcases (default)
-echo     1: Build all tests with priority 0 and 1
-echo     666: Build all tests with priority 0, 1 ... 666
-echo test ^<xxx^>: Only build test project ^<xxx^> ^(relative or absolute project path under src\tests^)
-echo dir ^<xxx^>: Build all test projects in the folder ^<xxx^> ^(relative or absolute folder under src\tests^)
-echo tree ^<xxx^>: Build all test projects in the subtree ^<xxx^> ^(relative or absolute folder under src\tests^)
-echo rebuild: Clean up all test artifacts prior to building tests
-echo allTargets: Build managed tests for all target platforms (including test projects in which CLRTestTargetUnsupported resolves to true)
-echo -verbose: enables detailed file logging for the msbuild tasks into the msbuild log file.
-echo log: base file name to use for log files (used in lab pipelines that build tests in multiple steps to retain logs for each step)
+echo -Priority ^<N^> : specify a set of tests that will be built and run, with priority N.
+echo     0: Build only priority 0 cases as essential testcases (default).
+echo     1: Build all tests with priority 0 and 1.
+echo     666: Build all tests with priority 0, 1 ... 666.
+echo -Test ^<xxx^>: Only build the specified test project ^(relative or absolute project path under src\tests^).
+echo -Dir ^<xxx^>: Build all test projects in the given directory ^(relative or absolute directory under src\tests^).
+echo -Tree ^<xxx^>: Build all test projects in the given subtree ^(relative or absolute directory under src\tests^).
+echo -Log ^<xxx^>: Base file name to use for log files (used in lab pipelines that build tests in multiple steps to retain logs for each step).
+echo.
+echo -CMakeArgs ^<arg^>=^<value^>: Specify argument values to pass directly to CMake.
+echo     Can be used multiple times to provide multiple CMake arguments.
+echo.
+echo -- : All arguments following this tag will be passed directly to MSBuild.
+echo.     Any unrecognized arguments will also be passed directly to MSBuild.
 exit /b 1
 
 REM Exit_Failure:

diff --git a/src/tests/build.sh b/src/tests/build.sh
index a9137f6..f46c58e 100755 (executable)
--- a/src/tests/build.sh
+++ b/src/tests/build.sh
@@ -137,33 +137,37 @@ build_Tests()
 }
 
 usage_list=()
-
-usage_list+=("-skipmanaged: do not build managed components.")
-usage_list+=("-skipnative: do not build native components.")
-usage_list+=("-skiprestorepackages: skip package restore.")
-usage_list+=("-skipgeneratelayout: Do not generate the Core_Root layout.")
-usage_list+=("-skiptestwrappers: Don't generate test wrappers.")
-
-usage_list+=("-buildtestwrappersonly: only build the test wrappers.")
-usage_list+=("-copynativeonly: Only copy the native test binaries to the managed output. Do not build the native or managed tests.")
-usage_list+=("-generatelayoutonly: only pull down dependencies and build coreroot.")
-
-usage_list+=("-test:xxx - only build a single test project");
-usage_list+=("-dir:xxx - build all tests in a given directory");
-usage_list+=("-tree:xxx - build all tests in a given subtree");
-
-usage_list+=("-crossgen2: Precompiles the framework managed assemblies in coreroot using the Crossgen2 compiler.")
-usage_list+=("-nativeaot: Builds the tests for Native AOT compilation.")
-usage_list+=("-priority1: include priority=1 tests in the build.")
-usage_list+=("-composite: Use Crossgen2 composite mode (all framework gets compiled into a single native R2R library).")
-usage_list+=("-perfmap: emit perfmap symbol files when compiling the framework assemblies using Crossgen2.")
-usage_list+=("-allTargets: Build managed tests for all target platforms (including test projects in which CLRTestTargetUnsupported resolves to true).")
-
-usage_list+=("-rebuild: if tests have already been built - rebuild them.")
-usage_list+=("-runtests: run tests after building them.")
-usage_list+=("-mono: Build the tests for the Mono runtime honoring mono-specific issues.")
-
-usage_list+=("-log: base file name to use for log files (used in lab pipelines that build tests in multiple steps to retain logs for each step.")
+usage_list+=("All arguments are optional and the '-' prefix is optional. The options are:")
+usage_list+=("")
+usage_list+=("-rebuild - Clean up all test artifacts prior to building tests.")
+usage_list+=("-skiprestorepackages - Skip package restore.")
+usage_list+=("-skipmanaged - Skip the managed tests build.")
+usage_list+=("-skipnative - Skip the native tests build.")
+usage_list+=("-skiptestwrappers - Skip generating test wrappers.")
+usage_list+=("-skipgeneratelayout - Skip generating the Core_Root layout.")
+usage_list+=("")
+usage_list+=("-copynativeonly - Only copy the native test binaries to the managed output. Do not build the native or managed tests.")
+usage_list+=("-generatelayoutonly - Only generate the Core_Root layout without building managed or native test components.")
+usage_list+=("-buildtestwrappersonly - Only generate test wrappers without building managed or native test components or generating layouts.")
+usage_list+=("")
+usage_list+=("-crossgen2 - Precompiles the framework managed assemblies in coreroot using the Crossgen2 compiler.")
+usage_list+=("-composite - Use Crossgen2 composite mode (all framework gets compiled into a single native R2R library).")
+usage_list+=("-nativeaot - Builds the tests for Native AOT compilation.")
+usage_list+=("-priority1 - Include priority=1 tests in the build.")
+usage_list+=("-perfmap - Emit perfmap symbol files when compiling the framework assemblies using Crossgen2.")
+usage_list+=("-allTargets - Build managed tests for all target platforms (including test projects in which CLRTestTargetUnsupported resolves to true).")
+usage_list+=("")
+usage_list+=("-runtests - Run tests after building them.")
+usage_list+=("-mono, -excludemonofailures - Build the tests for the Mono runtime honoring mono-specific issues.")
+usage_list+=("-mono_aot - Use Mono AOT mode.")
+usage_list+=("-mono_fullaot - Use Mono Full AOT mode.")
+usage_list+=("")
+usage_list+=("-test:xxx - Only build the specified test project ^(relative or absolute project path under src\tests^).");
+usage_list+=("-dir:xxx - Build all test projects in the given directory ^(relative or absolute directory under src\tests^).");
+usage_list+=("-tree:xxx - Build all test projects in the given subtree ^(relative or absolute directory under src\tests^).");
+usage_list+=("-log:xxx - Base file name to use for log files (used in lab pipelines that build tests in multiple steps to retain logs for each step).")
+usage_list+=("")
+usage_list+=("Any unrecognized arguments will be passed directly to MSBuild.")
 
 # Obtain the location of the bash script to figure out where the root of the repo is.
 __ProjectRoot="$(cd "$(dirname "$0")"; pwd -P)"