From: Ivan Diaz Sanchez Date: Tue, 9 Jun 2020 00:58:50 +0000 (-0700) Subject: Make build scripts' -help information more helpful (#37377) X-Git-Tag: submit/tizen/20210909.063632~7513 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=da97f17219da1cea3a53fbdb7f80b0a2012b982f;p=platform%2Fupstream%2Fdotnet%2Fruntime.git 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 --- diff --git a/eng/SubsetValidation.targets b/eng/SubsetValidation.targets index 3b0acd5..182f711 100644 --- a/eng/SubsetValidation.targets +++ b/eng/SubsetValidation.targets @@ -39,7 +39,7 @@ - diff --git a/eng/build.ps1 b/eng/build.ps1 index f8f1164..651a17a 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 diff --git a/eng/build.sh b/eng/build.sh index 02c5d27..442702f 100755 --- a/eng/build.sh +++ b/eng/build.sh @@ -17,47 +17,100 @@ scriptroot="$( cd -P "$( dirname "$source" )" && pwd )" usage() { echo "Common settings:" - echo " --subset Build a subset, print available subsets with -subset help (short: -s)" - echo " --os Build operating system: Windows_NT, Linux, FreeBSD, OSX, tvOS, iOS, Android, Browser, NetBSD or SunOS" - echo " --arch Build platform: x86, x64, arm, armel, arm64 or wasm" - echo " --configuration Build configuration: Debug, Release or [CoreCLR]Checked (short: -c)" - echo " --runtimeConfiguration Runtime build configuration: Debug, Release or [CoreCLR]Checked (short: -rc)" - echo " --librariesConfiguration Libraries build configuration: Debug or Release (short: -lc)" - echo " --projects Project or solution file(s) to build" - echo " --verbosity MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic] (short: -v)" - echo " --binaryLog Output binary log (short: -bl)" - echo " --cross Optional argument to signify cross compilation" - echo " --help Print help and exit (short: -h)" + echo " --arch Target platform: x86, x64, arm, armel, arm64 or wasm." + echo " [Default: Your machine's architecture.]" + echo " --binaryLog (-bl) Output binary log." + echo " --cross Optional argument to signify cross compilation." + echo " --configuration (-c) Build configuration: Debug, Release or Checked." + echo " Checked is exclusive to the CLR subset. It is the same as Debug, except code is" + echo " compiled with optimizations enabled." + echo " [Default: Debug]" + echo " --help (-h) Print help and exit." + echo " --librariesConfiguration (-lc) Libraries build configuration: Debug or Release." + echo " [Default: Debug]" + echo " --os Target operating system: Windows_NT, Linux, FreeBSD, OSX, tvOS, iOS, Android," + echo " Browser, NetBSD or SunOS." + echo " [Default: Your machine's OS.]" + echo " --projects Project or solution file(s) to build." + echo " --runtimeConfiguration (-rc) Runtime build configuration: Debug, Release or Checked." + echo " Checked is exclusive to the CLR runtime. It is the same as Debug, except code is" + echo " compiled with optimizations enabled." + echo " [Default: Debug]" + echo " --subset (-s) Build a subset, print available subsets with -subset help." + echo " '--subset' can be omitted if the subset is given as the first argument." + echo " [Default: Builds the entire repo.]" + echo " --verbosity (-v) MSBuild verbosity: q[uiet], m[inimal], n[ormal], d[etailed], and diag[nostic]." + echo " [Default: Minimal]" echo "" echo "Actions (defaults to --restore --build):" - echo " --restore Restore dependencies (short: -r)" - echo " --build Build all source projects (short: -b)" - echo " --rebuild Rebuild all source projects" - echo " --test Build and run tests (short: -t)" - echo " --pack Package build outputs into NuGet packages" - echo " --sign Sign build outputs" - echo " --publish Publish artifacts (e.g. symbols)" - echo " --clean Clean the solution" + echo " --build (-b) Build all source projects." + echo " This assumes --restore has been run already." + echo " --clean Clean the solution." + echo " --pack Package build outputs into NuGet packages." + echo " --publish Publish artifacts (e.g. symbols)." + echo " This assumes --build has been run already." + echo " --rebuild Rebuild all source projects." + echo " --restore (-r) Restore dependencies." + echo " --sign Sign build outputs." + echo " --test (-t) Incrementally builds and runs tests." + echo " Use in conjuction with --testnobuild to only run tests." echo "" echo "Libraries settings:" - echo " --framework Build framework: net5.0 or net472 (short: -f)" - echo " --coverage Collect code coverage when testing" - echo " --testscope Test scope, allowed values: innerloop, outerloop, all" - echo " --testnobuild Skip building tests when invoking -test" - echo " --allconfigurations Build packages for all build configurations" + echo " --allconfigurations Build packages for all build configurations." + echo " --coverage Collect code coverage when testing." + echo " --framework (-f) Build framework: net5.0 or net472." + echo " [Default: net5.0]" + echo " --testnobuild Skip building tests when invoking -test." + echo " --testscope Test scope, allowed values: innerloop, outerloop, all." echo "" echo "Native build settings:" - echo " --clang Optional argument to build using clang in PATH (default)" - echo " --clangx.y Optional argument to build using clang version x.y" + echo " --clang Optional argument to build using clang in PATH (default)." + echo " --clangx Optional argument to build using clang version x (used for Clang 7 and newer)." + echo " --clangx.y Optional argument to build using clang version x.y (used for Clang 6 and older)." echo " --cmakeargs User-settable additional arguments passed to CMake." - echo " --gcc Optional argument to build using gcc in PATH (default)" - echo " --gccx.y Optional argument to build using gcc version x.y" + echo " --gcc Optional argument to build using gcc in PATH (default)." + echo " --gccx.y Optional argument to build using gcc version x.y." + echo "" echo "Command line arguments starting with '/p:' are passed through to MSBuild." echo "Arguments can also be passed in with a single hyphen." + echo "" + + echo "Here are some quick examples. These assume you are on a Linux x64 machine:" + echo "" + echo "* Build CoreCLR for Linux x64 on Release configuration:" + echo "./build.sh clr -c release" + echo "" + echo "* Build Debug libraries with a Release runtime for Linux x64." + echo "./build.sh clr+libs -rc release" + echo "" + echo "* Build Release libraries and their tests with a Checked runtime for Linux x64, and run the tests." + echo "./build.sh clr+libs+libs.tests -rc checked -lc release -test" + echo "" + echo "* Build CoreCLR for Linux x64 on Debug configuration using Clang 9." + echo "./build.sh clr -clang9" + echo "" + echo "* Build CoreCLR for Linux x64 on Debug configuration using GCC 8.4." + echo "./build.sh clr -gcc8.4" + echo "" + echo "* Cross-compile CoreCLR runtime for Linux ARM64 on Release configuration." + echo "./build.sh clr.runtime -arch arm64 -c release -cross" + echo "" + echo "However, for this example, you need to already have ROOTFS_DIR set up." + echo "Further information on this can be found here:" + echo "https://github.com/dotnet/runtime/blob/master/docs/workflow/building/coreclr/linux-instructions.md" + echo "" + echo "* Build Mono runtime for Linux x64 on Release configuration." + echo "./build.sh mono -c release" + echo "" + echo "It's important to mention that to build Mono for the first time," + echo "you need to build the CLR and Libs subsets beforehand." + echo "This is done automatically if a full build is performed at first." + echo "" + echo "For more general information, check out https://github.com/dotnet/runtime/blob/master/docs/workflow/README.md" } initDistroRid() @@ -79,6 +132,11 @@ initDistroRid() initDistroRidGlobal ${targetOs} ${buildArch} ${isPortableBuild} ${passedRootfsDir} } +showSubsetHelp() +{ + "$scriptroot/common/build.sh" "-restore" "-build" "/p:Subset=help" "/clp:nosummary" +} + arguments='' cmakeargs='' extraargs='' @@ -95,6 +153,11 @@ while [[ $# > 0 ]]; do opt="$(echo "${1/#--/-}" | awk '{print tolower($0)}')" if [[ $firstArgumentChecked -eq 0 && $opt =~ ^[a-zA-Z.+]+$ ]]; then + if [ $opt == "help" ]; then + showSubsetHelp + exit 0 + fi + arguments="$arguments /p:Subset=$1" shift 1 continue @@ -110,9 +173,14 @@ while [[ $# > 0 ]]; do -subset|-s) if [ -z ${2+x} ]; then - arguments="$arguments /p:Subset=help" - shift 1 + showSubsetHelp + exit 0 else + passedSubset="$(echo "$2" | awk '{print tolower($0)}')" + if [ $passedSubset == "help" ]; then + showSubsetHelp + exit 0 + fi arguments="$arguments /p:Subset=$2" shift 2 fi