Skip to content

Commit da97f17

Browse files
ivdiazsaivdiazsa
authored
Make build scripts' -help information more helpful (dotnet#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 parent f833ffd commit da97f17

File tree

3 files changed

+174
-56
lines changed

3 files changed

+174
-56
lines changed

‎eng/SubsetValidation.targets

+1-1
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
<Error Text="Subset not recognized: @(InvalidSpecifiedSubsetName, ' ')"
4040
Condition="'$(UserRequestedHelp)' != 'true'" />
4141

42-
<Error Text="Choose a subset to use, or do not specify a subset to perform the full build."
42+
<Error Text="This is not an error. These are the available subsets. You can choose one or none at all for a full build."
4343
Condition="'$(UserRequestedHelp)' == 'true'" />
4444
</Target>
4545

‎eng/build.ps1

+75-25
Original file line numberDiff line numberDiff line change
@@ -20,46 +20,96 @@ Param(
2020

2121
function Get-Help() {
2222
Write-Host "Common settings:"
23-
Write-Host " -subset Build a subset, print available subsets with -subset help (short: -s)"
24-
Write-Host " -vs Open the solution with VS using the locally acquired SDK. Path or solution name (ie -vs Microsoft.CSharp)"
25-
Write-Host " -os Build operating system: Windows_NT, Linux, OSX, or Browser"
26-
Write-Host " -arch Build platform: x86, x64, arm, arm64, or wasm (short: -a). Pass a comma-separated list to build for multiple architectures."
27-
Write-Host " -configuration Build configuration: Debug, Release or [CoreCLR]Checked (short: -c). Pass a comma-separated list to build for multiple configurations"
28-
Write-Host " -runtimeConfiguration Runtime build configuration: Debug, Release or [CoreCLR]Checked (short: -rc)"
29-
Write-Host " -librariesConfiguration Libraries build configuration: Debug or Release (short: -lc)"
30-
Write-Host " -verbosity MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic] (short: -v)"
31-
Write-Host " -binaryLog Output binary log (short: -bl)"
32-
Write-Host " -help Print help and exit (short: -h)"
23+
Write-Host " -arch (-a) Target platform: x86, x64, arm, arm64, or wasm."
24+
Write-Host " Pass a comma-separated list to build for multiple architectures."
25+
Write-Host " [Default: Your machine's architecture.]"
26+
Write-Host " -binaryLog (-bl) Output binary log."
27+
Write-Host " -configuration (-c) Build configuration: Debug, Release or Checked."
28+
Write-Host " Checked is exclusive to the CLR subset. It is the same as Debug, except code is"
29+
Write-Host " compiled with optimizations enabled."
30+
Write-Host " Pass a comma-separated list to build for multiple configurations."
31+
Write-Host " [Default: Debug]"
32+
Write-Host " -help (-h) Print help and exit."
33+
Write-Host " -librariesConfiguration (-lc) Libraries build configuration: Debug or Release."
34+
Write-Host " [Default: Debug]"
35+
Write-Host " -os Target operating system: Windows_NT, Linux, OSX, or Browser."
36+
Write-Host " [Default: Your machine's OS.]"
37+
Write-Host " -runtimeConfiguration (-rc) Runtime build configuration: Debug, Release or Checked."
38+
Write-Host " Checked is exclusive to the CLR runtime. It is the same as Debug, except code is"
39+
Write-Host " compiled with optimizations enabled."
40+
Write-Host " [Default: Debug]"
41+
Write-Host " -subset (-s) Build a subset, print available subsets with -subset help."
42+
Write-Host " '-subset' can be omitted if the subset is given as the first argument."
43+
Write-Host " [Default: Builds the entire repo.]"
44+
Write-Host " -verbosity (-v) MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]."
45+
Write-Host " [Default: Minimal]"
46+
Write-Host " -vs Open the solution with Visual Studio using the locally acquired SDK."
47+
Write-Host " Path or any project or solution name is accepted."
48+
Write-Host " (Example: -vs Microsoft.CSharp)"
3349
Write-Host ""
3450

3551
Write-Host "Actions (defaults to -restore -build):"
36-
Write-Host " -restore Restore dependencies"
37-
Write-Host " -build Build all source projects (short: -b)"
38-
Write-Host " -rebuild Rebuild all source projects"
39-
Write-Host " -test Build and run tests (short: -t)"
40-
Write-Host " -pack Package build outputs into NuGet packages"
41-
Write-Host " -sign Sign build outputs"
42-
Write-Host " -publish Publish artifacts (e.g. symbols)"
43-
Write-Host " -clean Clean the solution"
52+
Write-Host " -build (-b) Build all source projects."
53+
Write-Host " This assumes -restore has been run already."
54+
Write-Host " -clean Clean the solution."
55+
Write-Host " -pack Package build outputs into NuGet packages."
56+
Write-Host " -publish Publish artifacts (e.g. symbols)."
57+
Write-Host " This assumes -build has been run already."
58+
Write-Host " -rebuild Rebuild all source projects."
59+
Write-Host " -restore Restore dependencies."
60+
Write-Host " -sign Sign build outputs."
61+
Write-Host " -test (-t) Incrementally builds and runs tests."
62+
Write-Host " Use in conjuction with -testnobuild to only run tests."
4463
Write-Host ""
4564

4665
Write-Host "Libraries settings:"
47-
Write-Host " -framework Build framework: net5.0 or net472 (short: -f)"
48-
Write-Host " -coverage Collect code coverage when testing"
49-
Write-Host " -testscope Scope tests, allowed values: innerloop, outerloop, all"
50-
Write-Host " -testnobuild Skip building tests when invoking -test"
51-
Write-Host " -allconfigurations Build packages for all build configurations"
66+
Write-Host " -allconfigurations Build packages for all build configurations."
67+
Write-Host " -coverage Collect code coverage when testing."
68+
Write-Host " -framework (-f) Build framework: net5.0 or net472."
69+
Write-Host " [Default: net5.0]"
70+
Write-Host " -testnobuild Skip building tests when invoking -test."
71+
Write-Host " -testscope Scope tests, allowed values: innerloop, outerloop, all."
5272
Write-Host ""
5373

54-
Write-Host "Command-line arguments not listed above are passed thru to msbuild."
55-
Write-Host "The above arguments can be shortened as much as to be unambiguous (e.g. -con for configuration, -t for test, etc.)."
74+
Write-Host "Command-line arguments not listed above are passed through to MSBuild."
75+
Write-Host "The above arguments can be shortened as much as to be unambiguous."
76+
Write-Host "(Example: -con for configuration, -t for test, etc.)."
77+
Write-Host ""
78+
79+
Write-Host "Here are some quick examples. These assume you are on a Windows x64 machine:"
80+
Write-Host ""
81+
Write-Host "* Build CoreCLR for Windows x64 on Release configuration:"
82+
Write-Host ".\build.cmd clr -c release"
83+
Write-Host ""
84+
Write-Host "* Cross-compile CoreCLR runtime for Windows ARM64 on Release configuration."
85+
Write-Host ".\build.cmd clr.runtime -arch arm64 -c release"
86+
Write-Host ""
87+
Write-Host "* Build Debug libraries with a Release runtime for Windows x64."
88+
Write-Host ".\build.cmd clr+libs -rc release"
89+
Write-Host ""
90+
Write-Host "* Build Release libraries and their tests with a Checked runtime for Windows x64, and run the tests."
91+
Write-Host ".\build.cmd clr+libs+libs.tests -rc checked -lc release -test"
92+
Write-Host ""
93+
Write-Host "* Build Mono runtime for Windows x64 on Release configuration."
94+
Write-Host ".\build.cmd mono -c release"
95+
Write-Host ""
96+
Write-Host "It's important to mention that to build Mono for the first time,"
97+
Write-Host "you need to build the CLR and Libs subsets beforehand."
98+
Write-Host "This is done automatically if a full build is performed at first."
99+
Write-Host ""
100+
Write-Host "For more information, check out https://github.com/dotnet/runtime/blob/master/docs/workflow/README.md"
56101
}
57102

58103
if ($help -or (($null -ne $properties) -and ($properties.Contains('/help') -or $properties.Contains('/?')))) {
59104
Get-Help
60105
exit 0
61106
}
62107

108+
if ($subset -eq 'help') {
109+
Invoke-Expression "& `"$PSScriptRoot/common/build.ps1`" -restore -build /p:subset=help /clp:nosummary"
110+
exit 0
111+
}
112+
63113
if ($vs) {
64114
. $PSScriptRoot\common\tools.ps1
65115

‎eng/build.sh

+98-30
Original file line numberDiff line numberDiff line change
@@ -17,47 +17,100 @@ scriptroot="$( cd -P "$( dirname "$source" )" && pwd )"
1717
usage()
1818
{
1919
echo "Common settings:"
20-
echo " --subset Build a subset, print available subsets with -subset help (short: -s)"
21-
echo " --os Build operating system: Windows_NT, Linux, FreeBSD, OSX, tvOS, iOS, Android, Browser, NetBSD or SunOS"
22-
echo " --arch Build platform: x86, x64, arm, armel, arm64 or wasm"
23-
echo " --configuration Build configuration: Debug, Release or [CoreCLR]Checked (short: -c)"
24-
echo " --runtimeConfiguration Runtime build configuration: Debug, Release or [CoreCLR]Checked (short: -rc)"
25-
echo " --librariesConfiguration Libraries build configuration: Debug or Release (short: -lc)"
26-
echo " --projects <value> Project or solution file(s) to build"
27-
echo " --verbosity MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic] (short: -v)"
28-
echo " --binaryLog Output binary log (short: -bl)"
29-
echo " --cross Optional argument to signify cross compilation"
30-
echo " --help Print help and exit (short: -h)"
20+
echo " --arch Target platform: x86, x64, arm, armel, arm64 or wasm."
21+
echo " [Default: Your machine's architecture.]"
22+
echo " --binaryLog (-bl) Output binary log."
23+
echo " --cross Optional argument to signify cross compilation."
24+
echo " --configuration (-c) Build configuration: Debug, Release or Checked."
25+
echo " Checked is exclusive to the CLR subset. It is the same as Debug, except code is"
26+
echo " compiled with optimizations enabled."
27+
echo " [Default: Debug]"
28+
echo " --help (-h) Print help and exit."
29+
echo " --librariesConfiguration (-lc) Libraries build configuration: Debug or Release."
30+
echo " [Default: Debug]"
31+
echo " --os Target operating system: Windows_NT, Linux, FreeBSD, OSX, tvOS, iOS, Android,"
32+
echo " Browser, NetBSD or SunOS."
33+
echo " [Default: Your machine's OS.]"
34+
echo " --projects <value> Project or solution file(s) to build."
35+
echo " --runtimeConfiguration (-rc) Runtime build configuration: Debug, Release or Checked."
36+
echo " Checked is exclusive to the CLR runtime. It is the same as Debug, except code is"
37+
echo " compiled with optimizations enabled."
38+
echo " [Default: Debug]"
39+
echo " --subset (-s) Build a subset, print available subsets with -subset help."
40+
echo " '--subset' can be omitted if the subset is given as the first argument."
41+
echo " [Default: Builds the entire repo.]"
42+
echo " --verbosity (-v) MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]."
43+
echo " [Default: Minimal]"
3144
echo ""
3245

3346
echo "Actions (defaults to --restore --build):"
34-
echo " --restore Restore dependencies (short: -r)"
35-
echo " --build Build all source projects (short: -b)"
36-
echo " --rebuild Rebuild all source projects"
37-
echo " --test Build and run tests (short: -t)"
38-
echo " --pack Package build outputs into NuGet packages"
39-
echo " --sign Sign build outputs"
40-
echo " --publish Publish artifacts (e.g. symbols)"
41-
echo " --clean Clean the solution"
47+
echo " --build (-b) Build all source projects."
48+
echo " This assumes --restore has been run already."
49+
echo " --clean Clean the solution."
50+
echo " --pack Package build outputs into NuGet packages."
51+
echo " --publish Publish artifacts (e.g. symbols)."
52+
echo " This assumes --build has been run already."
53+
echo " --rebuild Rebuild all source projects."
54+
echo " --restore (-r) Restore dependencies."
55+
echo " --sign Sign build outputs."
56+
echo " --test (-t) Incrementally builds and runs tests."
57+
echo " Use in conjuction with --testnobuild to only run tests."
4258
echo ""
4359

4460
echo "Libraries settings:"
45-
echo " --framework Build framework: net5.0 or net472 (short: -f)"
46-
echo " --coverage Collect code coverage when testing"
47-
echo " --testscope Test scope, allowed values: innerloop, outerloop, all"
48-
echo " --testnobuild Skip building tests when invoking -test"
49-
echo " --allconfigurations Build packages for all build configurations"
61+
echo " --allconfigurations Build packages for all build configurations."
62+
echo " --coverage Collect code coverage when testing."
63+
echo " --framework (-f) Build framework: net5.0 or net472."
64+
echo " [Default: net5.0]"
65+
echo " --testnobuild Skip building tests when invoking -test."
66+
echo " --testscope Test scope, allowed values: innerloop, outerloop, all."
5067
echo ""
5168

5269
echo "Native build settings:"
53-
echo " --clang Optional argument to build using clang in PATH (default)"
54-
echo " --clangx.y Optional argument to build using clang version x.y"
70+
echo " --clang Optional argument to build using clang in PATH (default)."
71+
echo " --clangx Optional argument to build using clang version x (used for Clang 7 and newer)."
72+
echo " --clangx.y Optional argument to build using clang version x.y (used for Clang 6 and older)."
5573
echo " --cmakeargs User-settable additional arguments passed to CMake."
56-
echo " --gcc Optional argument to build using gcc in PATH (default)"
57-
echo " --gccx.y Optional argument to build using gcc version x.y"
74+
echo " --gcc Optional argument to build using gcc in PATH (default)."
75+
echo " --gccx.y Optional argument to build using gcc version x.y."
76+
echo ""
5877

5978
echo "Command line arguments starting with '/p:' are passed through to MSBuild."
6079
echo "Arguments can also be passed in with a single hyphen."
80+
echo ""
81+
82+
echo "Here are some quick examples. These assume you are on a Linux x64 machine:"
83+
echo ""
84+
echo "* Build CoreCLR for Linux x64 on Release configuration:"
85+
echo "./build.sh clr -c release"
86+
echo ""
87+
echo "* Build Debug libraries with a Release runtime for Linux x64."
88+
echo "./build.sh clr+libs -rc release"
89+
echo ""
90+
echo "* Build Release libraries and their tests with a Checked runtime for Linux x64, and run the tests."
91+
echo "./build.sh clr+libs+libs.tests -rc checked -lc release -test"
92+
echo ""
93+
echo "* Build CoreCLR for Linux x64 on Debug configuration using Clang 9."
94+
echo "./build.sh clr -clang9"
95+
echo ""
96+
echo "* Build CoreCLR for Linux x64 on Debug configuration using GCC 8.4."
97+
echo "./build.sh clr -gcc8.4"
98+
echo ""
99+
echo "* Cross-compile CoreCLR runtime for Linux ARM64 on Release configuration."
100+
echo "./build.sh clr.runtime -arch arm64 -c release -cross"
101+
echo ""
102+
echo "However, for this example, you need to already have ROOTFS_DIR set up."
103+
echo "Further information on this can be found here:"
104+
echo "https://github.com/dotnet/runtime/blob/master/docs/workflow/building/coreclr/linux-instructions.md"
105+
echo ""
106+
echo "* Build Mono runtime for Linux x64 on Release configuration."
107+
echo "./build.sh mono -c release"
108+
echo ""
109+
echo "It's important to mention that to build Mono for the first time,"
110+
echo "you need to build the CLR and Libs subsets beforehand."
111+
echo "This is done automatically if a full build is performed at first."
112+
echo ""
113+
echo "For more general information, check out https://github.com/dotnet/runtime/blob/master/docs/workflow/README.md"
61114
}
62115

63116
initDistroRid()
@@ -79,6 +132,11 @@ initDistroRid()
79132
initDistroRidGlobal ${targetOs} ${buildArch} ${isPortableBuild} ${passedRootfsDir}
80133
}
81134

135+
showSubsetHelp()
136+
{
137+
"$scriptroot/common/build.sh" "-restore" "-build" "/p:Subset=help" "/clp:nosummary"
138+
}
139+
82140
arguments=''
83141
cmakeargs=''
84142
extraargs=''
@@ -95,6 +153,11 @@ while [[ $# > 0 ]]; do
95153
opt="$(echo "${1/#--/-}" | awk '{print tolower($0)}')"
96154

97155
if [[ $firstArgumentChecked -eq 0 && $opt =~ ^[a-zA-Z.+]+$ ]]; then
156+
if [ $opt == "help" ]; then
157+
showSubsetHelp
158+
exit 0
159+
fi
160+
98161
arguments="$arguments /p:Subset=$1"
99162
shift 1
100163
continue
@@ -110,9 +173,14 @@ while [[ $# > 0 ]]; do
110173

111174
-subset|-s)
112175
if [ -z ${2+x} ]; then
113-
arguments="$arguments /p:Subset=help"
114-
shift 1
176+
showSubsetHelp
177+
exit 0
115178
else
179+
passedSubset="$(echo "$2" | awk '{print tolower($0)}')"
180+
if [ $passedSubset == "help" ]; then
181+
showSubsetHelp
182+
exit 0
183+
fi
116184
arguments="$arguments /p:Subset=$2"
117185
shift 2
118186
fi

0 commit comments

Comments
 (0)