From c31f56c616914aebf53a9d0c8dfcb3dc1785ae51 Mon Sep 17 00:00:00 2001 From: "Denis Kuzmin (github/3F)" Date: Thu, 8 Feb 2024 21:32:36 +0300 Subject: [PATCH] New Readme and -help information --- .github/FUNDING.yml | 2 +- Readme.md | 224 +++++++++++++++++++++++++------------------- frontend.bat | 36 +++---- 3 files changed, 147 insertions(+), 115 deletions(-) diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index f6ab812..f817a07 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -4,4 +4,4 @@ # /___/ \; Yours, github.com/3F # -custom: ['3F.github.io/Donation'] +custom: ['3F.github.io/fund'] diff --git a/Readme.md b/Readme.md index 78080d3..8dd5cb6 100644 --- a/Readme.md +++ b/Readme.md @@ -1,153 +1,174 @@ # [hMSBuild](https://github.com/3F/hMSBuild) -Compiled text-based embeddable pure batch-scripts (no powershell, no dotnet-cli) for searching of available MSBuild tools. VS2019+, VS2017 (it does not require local vswhere.exe [[?](https://github.com/Microsoft/vswhere/issues/41)]), VS2015, VS2013, VS2012, VS2010, other versions from .NET Framework. Contains [gnt.core](https://github.com/3F/GetNuTool) for work with NuGet packages and more... +*.bat* scripts with full [Package Manager](https://github.com/3F/GetNuTool) inside for searching and wrapping MSBuild tools. All *Visual Studio* and *.NET Framework* versions. +You do NOT need *powershell* or *dotnet-cli* or local [*vswhere.exe* [?]](https://github.com/Microsoft/vswhere/issues/41) +```r +Copyright (c) 2017-2024 Denis Kuzmin github/3F +``` + +[ 「 ❤ 」 ](https://3F.github.io/fund) [![License](https://img.shields.io/badge/License-MIT-74A5C2.svg)](https://github.com/3F/hMSBuild/blob/master/License.txt) [![Build status](https://ci.appveyor.com/api/projects/status/8ac1021k385eyubm/branch/master?svg=true)](https://ci.appveyor.com/project/3Fs/hmsbuild-github/branch/master) -[![release-src](https://img.shields.io/github/release/3F/hMSBuild.svg)](https://github.com/3F/hMSBuild/releases/latest) -[![License](https://img.shields.io/badge/License-MIT-74A5C2.svg)](https://github.com/3F/hMSBuild/blob/master/License.txt) -[![GetNuTool](https://img.shields.io/badge/GetNuTool-v1.8-93C10B.svg)](https://github.com/3F/GetNuTool) +[![release](https://img.shields.io/github/release/3F/hMSBuild.svg)](https://github.com/3F/hMSBuild/releases/latest) +[![GetNuTool](https://img.shields.io/badge/GetNuTool-v1.9-93C10B.svg)](https://github.com/3F/GetNuTool) [![Build history](https://buildstats.info/appveyor/chart/3Fs/hmsbuild-github?buildCount=15&includeBuildsFromPullRequest=true&showStats=true)](https://ci.appveyor.com/project/3Fs/hmsbuild-github/history) -**Download:** Latest stable batch-script [ [hMSBuild](https://3F.github.io/hMSBuild/releases/latest/) ] -* Stable: [/releases](https://github.com/3F/hMSBuild/releases) [ [latest](https://github.com/3F/hMSBuild/releases/latest) ] +```bat +hMSBuild -only-path -no-vs -notamd64 -no-less-4 +hMSBuild -debug ~x ~c Release +hMSBuild -GetNuTool "Conari;regXwild;Fnv1a128" +hMSBuild -GetNuTool vsSolutionBuildEvent/1.16.0:../SDK & SDK\GUI +hMSBuild -cs -no-less-15 /t:Rebuild +``` + +**[Download](https://github.com/3F/hMSBuild/releases)** all editions: *Full, Minified, ...* -* CI builds: [`/artifacts` page](https://ci.appveyor.com/project/3Fs/hmsbuild-github/history) ( [old CI](https://ci.appveyor.com/project/3Fs/hmsbuild/history) ) or find as `Pre-release` with mark `🎲 Nightly build` on [GitHub Releases](https://github.com/3F/hmsbuild/releases) page. +Official Direct Links: +* (Windows) Latest stable compiled batch-script [ [hMSBuild.bat](https://3F.github.io/hMSBuild/releases/latest/) ] `https://3F.github.io/hMSBuild/releases/latest/` -## Why hMSBuild ? -*because you need simple access to msbuild tools and more...* +## Why hMSBuild -Based on **GetNuTool core** https://github.com/3F/GetNuTool +*because you need easy access to msbuild tools and more...* -* Initially, it was part of this tool like a small msbuild-helper. Then, it has been extracted into the new project after major changes from MS for their products. Now we have more support of all this. +Based on [GetNuTool](https://github.com/3F/GetNuTool) and back in those days it was part of it like a small msbuild-helper inside. + But finally it was extracted into a new independent project after major changes from MS ecosystem with their products. -Today's [hMSBuild](https://github.com/3F/hMSBuild) provides flexible way to access to msbuild tools for any type of your projects. Just specify what you need in different environments. Look at *#Algorithm of searching* below. +Today's [hMSBuild](https://github.com/3F/hMSBuild) provides the most flexible way to access and preparing msbuild tools in different environments. You just specify what you need ... and hMSBuild prepares it for you. [![{Screencast - hMSBuild in action. Demo via RunIlAsm error}](https://raw.githubusercontent.com/3F/hMSBuild/master/resources/screencast_hMSBuild_in_action.jpg)](https://www.youtube.com/watch?v=zUejJ4vUPGw&t=10) -## License -Licensed under the [MIT License (MIT)](https://github.com/3F/hMSBuild/blob/master/License.txt) +### Key Features -``` -Copyright (c) 2017-2024 Denis Kuzmin github/3F -``` -hMSBuild contributors https://github.com/3F/hMSBuild/graphs/contributors +* Single *.bat file, no less, no more. +* Manage all versions, including before install-API/2017+ +* *Visual Studio* versions support: VS2022+, VS2019, VS2017, VS2015, VS2013, VS2012, VS2010 +* *.NET Framework* versions support: 4.0 (2010), 3.5, 2.0 +* Lightweight and text-based, about ~8 KB + ~11 KB +* Does not require *powershell* or *dotnet-cli* or even local [*vswhere.exe* [?]](https://github.com/Microsoft/vswhere/issues/41) +* Support hot updating / custom vswhere at any request for the most modern environments. +* Provides some useful aliases. +* Full [package manager](https://github.com/3F/GetNuTool) inside .bat to Create or Distribute using basic shell scripts; +* Request to the server only if the package is not installed. +* Support *packages.config* (+extra: output, sha1 if used unsecured channels ~windows xp). +* Easy integration into any scripts such as pure batch-script [netfx4sdk](https://github.com/3F/netfx4sdk), [DllExport](https://github.com/3F/DllExport/wiki/DllExport-Manager) -[ [ ☕ Donate ](https://3F.github.io/Donation/) ] +### hMSBuild's algorithm -### Features +The basic process is to provide the most suitable instance by explicitly eliminating unnecessary ones. -Just a **single batch file** and no more for your happy build. +**2.0+** -Combine this with your other available scripts or just type `hMSBuild {arguments to original msbuild}` and have fun. +* Versions: + * VS2022, ..., VS2017 ➟ VS2015, VS2013, ... ➟ .netfx +* Instance Architecture (configure via `-notamd64` key): + * x64 ➟ x32 -Start with `hMSBuild -h` +* Extra restrictions via `-no-less-4` (Windows XP+), `-no-less-15` (install-API/2017+) +* Priorities (configure via `-priority`, `-vc`, `cs`, `-stable`, ... keys). *Specific workload components in more priority than pre-release products. See [Issue #8](https://github.com/3F/hMSBuild/issues/8)* -### What supports ? + 1. Stable releases with selected workload components (C++ etc) ➟ Same via beta releases if allowed. + 1. Stable releases with any available components ➟ Same via beta releases if allowed. -* Versions from VS2019+, VS2017 - * Full support even if you still have no any [local `vswhere.exe`](https://github.com/Microsoft/vswhere/issues/41) [[?](https://github.com/Microsoft/vswhere/issues/41)] - -* Versions from VS2015, VS2013, VS2012 -* Versions from .NET Framework, including for VS2010 +## Syntax -### Algorithm of searching +Keys to *hMSBuild* are optional. You can still command like it is official *msbuild.exe* *(MSBuild Tools)*. -**v2.0+** +> hMSBuild [keys to hMSBuild] [keys to msbuild.exe] -* Versions: - * VS2019+, VS2017 ➟ VS2015, VS2013, ... ➟ .netfx -* Architectures (configure via `-notamd64` key): - * x64 ➟ x32 -* Priorities (configure via `-vsw-priority` and `-stable` keys). *Specific workload components in more priority than pre-release products. See [Issue #8](https://github.com/3F/hMSBuild/issues/8)* +For example, - 1. Stable releases with selected workload components (C++ etc) ➟ Same via beta releases if allowed. - 1. Stable releases with any available components ➟ Same via beta releases if allowed. +* The *Clean* target in current directory: `hmsbuild /t:Clean` +* Set property *Configuration* and *minimal* verbosity: `hmsbuild /p:Configuration=Debug /v:m` + * via hMSBuild it can also be like: `hmsbuild ~x ~c Debug` + +In order to use [package manager](https://github.com/3F/GetNuTool), + +> hMSBuild **-GetNuTool** keys to it ... + +* Get latest packages: `hmsbuild -GetNuTool "Conari;regXwild;Fnv1a128"` +* Activate GUI script editor: `hMSBuild -GetNuTool vsSolutionBuildEvent/1.16.0:../SDK & SDK\GUI` +* Create new package: `hmsbuild -GetNuTool /t:pack /p:ngin=packages/Fnv1a128` + +### -... or /... + +MSBuild Tools supports both key format */...* and *-...*; hMSBuild, in turn, can override some of *-...*; in this case you need to use */...* for example, + +* */version* will be addressed to found MSBuild; +* *-version* will be addressed to hMSBuild; -## Usage +### "..." -Usage is same as it would be same for msbuild. But you also have an additional keys to configure hMSBuild and to access to GetNuTool. +Any value for specific key must be protected inside `"..."` if contains either whitespaces or delimiters like `;` For example: +```bat +hmsbuild ~p "Any CPU" ``` -hMSBuild 2.3.0 -Copyright (c) 2017-2020 Denis Kuzmin [ x-3F@outlook.com ] GitHub/3F -Copyright (c) hMSBuild contributors -Licensed under the MIT License -https://github.com/3F/hMSBuild +### -help + +For the most up-to-date information, use `hMSBuild -h` + +``` +hMSBuild 2.4.0 +Copyright (c) 2017-2024 Denis Kuzmin github/3F +Copyright (c) hMSBuild contributors https://github.com/3F/hMSBuild +Under the MIT License https://github.com/3F/hMSBuild -Usage: hMSBuild [args to hMSBuild] [args to msbuild.exe or GetNuTool core] ------- +Syntax: hMSBuild [keys to hMSBuild] [keys to MSBuild.exe or GetNuTool] -Arguments: ----------- +Keys +~~~~ -no-vs - Disable searching from Visual Studio. -no-netfx - Disable searching from .NET Framework. -no-vswhere - Do not search via vswhere. + -no-less-15 - Do not include versions less than 15.0 (install-API/2017+) + -no-less-4 - Do not include versions less than 4.0 (Windows XP+) - -vsw-priority {IDs} - Non-strict components preference: C++ etc. - Separated by space: https://aka.ms/vs/workloads + -priority {IDs} - 15+ Non-strict components preference: C++ etc. + Separated by space "a b c" https://aka.ms/vs/workloads - -vsw-version {arg} - Specific version of vswhere. Where {arg}: - * 2.6.7 ... - * Keywords: - `latest` - To get latest remote version; - `local` - To use only local versions; - (.bat;.exe /or from +15.2.26418.1 VS-build) + -vswhere {v} + * 2.6.7 ... + * latest - To get latest remote vswhere.exe + * local - To use only local + (.bat;.exe /or from +15.2.26418.1 VS-build) -no-cache - Do not cache vswhere for this request. -reset-cache - To reset all cached vswhere versions before processing. + -cs - Adds to -priority C# / VB Roslyn compilers. + -vc - Adds to -priority VC++ toolset. + ~c {name} - Alias to p:Configuration={name} + ~p {name} - Alias to p:Platform={name} + ~x - Alias to m:NUMBER_OF_PROCESSORS-1 v:m -notamd64 - To use 32bit version of found msbuild.exe if it's possible. -stable - It will ignore possible beta releases in last attempts. -eng - Try to use english language for all build messages. -GetNuTool {args} - Access to GetNuTool core. https://github.com/3F/GetNuTool -only-path - Only display fullpath to found MSBuild. - -force - Aggressive behavior for -vsw-priority, -notamd64, etc. + -force - Aggressive behavior for -priority, -notamd64, etc. -vsw-as "args..." - Reassign default commands to vswhere if used. - -debug - To show additional information from hMSBuild. + -debug - To show additional information from hMSBuild -version - Display version of hMSBuild. - -help - Display this help. Aliases: -help -h - - ------- -Flags: ------- - __p_call - Tries to eliminate the difference for the call-type invoking hMSBuild.bat - --------- -Samples: --------- -hMSBuild -notamd64 -vsw-version 2.6.7 "Conari.sln" /t:Rebuild -hMSBuild -vsw-version latest "Conari.sln" - -hMSBuild -no-vswhere -no-vs -notamd64 "Conari.sln" -hMSBuild -no-vs "DllExport.sln" -hMSBuild vsSolutionBuildEvent.sln - -hMSBuild -GetNuTool -unpack -hMSBuild -GetNuTool /p:ngpackages="Conari;regXwild" - -hMSBuild -no-vs "DllExport.sln" || goto by + -help - Display this help. Aliases: -? -h ``` -## Integration with other scripts +## Integration with scripts -### batch +### batch (.bat, .cmd) -hMSBuild is a pure batch script. Therefore, you can combine this even inside your other batch scripts. Or simply invoke this externally as you need: - -~ +hMSBuild is a pure batch script. Therefore, you can easily combine this even inside other batch scripts. Or invoke this externally, there's nothing special: ```bat -set msbuild=hMSBuild -notamd64 +set msbuild=hMSBuild -notamd64 ~c Release ... -%msbuild% Conari.sln /m:4 /t:Rebuild +%msbuild% Conari.sln /t:Rebuild ``` ```bat @@ -156,23 +177,34 @@ for /F "tokens=*" %%i in ('hMSBuild -only-path -notamd64') do set msbuild="%%i" %msbuild% /version ``` -... +```bat +hmsbuild -cs -no-less-15 ~c Debug ~x || goto failed +``` +More actual examples can be found in [tests/](tests/) folder. -## Build & Tests +Note: for some cases, if you know what you're doing, you can also configure *__p_call* flag to eliminate the difference for the call-type invoking *hMSBuild.bat* + +```bat +set __p_call=1 +``` -Our build was based on [vssbe](https://github.com/3F/vsSolutionBuildEvent) scripts. -You don't need to do anything else, just navigate to root directory of this project, and: +## Build & Tests + +build and tests was based on batch and [vssbe](https://github.com/3F/vsSolutionBuildEvent) scripts. You don't need to do anything else, just build and test it ```bat -.\build +build & tests ``` -Available tests can be raised by command: +### Build and Use from source ```bat -.\tests +git clone https://github.com/3F/hMSBuild.git src +cd src & build & bin\Release\hMSBuild -help ``` -We're waiting for your awesome contributions! \ No newline at end of file +## Contributing + +[*hMSBuild*](https://github.com/3F/hMSBuild) is waiting for your awesome contributions! \ No newline at end of file diff --git a/frontend.bat b/frontend.bat index 6cff515..a662c4b 100644 --- a/frontend.bat +++ b/frontend.bat @@ -90,12 +90,10 @@ echo Copyright (c) hMSBuild contributors https://github.com/3F/hMSBuild echo. echo Under the MIT License https://github.com/3F/hMSBuild echo. +echo Syntax: %~n0 [keys to %~n0] [keys to MSBuild.exe or GetNuTool] echo. -echo Usage: hMSBuild [args to hMSBuild] [args to msbuild.exe or GetNuTool] -echo ~~~~~~ -echo. -echo Arguments -echo ~~~~~~~~~ +echo Keys +echo ~~~~ echo -no-vs - Disable searching from Visual Studio. echo -no-netfx - Disable searching from .NET Framework. echo -no-vswhere - Do not search via vswhere. @@ -125,21 +123,23 @@ echo -GetNuTool {args} - Access to GetNuTool core. https://github.com/3F/GetNuT echo -only-path - Only display fullpath to found MSBuild. echo -force - Aggressive behavior for -priority, -notamd64, etc. echo -vsw-as "args..." - Reassign default commands to vswhere if used. -echo -debug - To show additional information from hMSBuild. -echo -version - Display version of hMSBuild. -echo -help - Display this help. Aliases: -help -h +echo -debug - To show additional information from %~n0 +echo -version - Display version of %~n0. +echo -help - Display this help. Aliases: -? -h +echo. +echo. +echo MSBuild switches +echo ~~~~~~~~~~~~~~~~ +echo /help or /? or /h +echo Use /... if %~n0 overrides some -... MSBuild switches echo. -echo Flags -echo ~~~~~~ -echo set __p_call=1 to eliminate the difference for the call-type invoking %~nx0 echo. echo Try to execute: -echo ~~~~~~~~~~~~~~~ -echo hMSBuild -only-path -no-vs -notamd64 -no-less-4 -echo hMSBuild -debug ~x ~c Release -echo hMSBuild -GetNuTool "Conari;regXwild;Fnv1a128" -echo hMSBuild -GetNuTool vsSolutionBuildEvent/1.16.0:../SDK ^& SDK\GUI -echo hMSBuild -cs -no-less-15 /t:Rebuild +echo %~n0 -only-path -no-vs -notamd64 -no-less-4 +echo %~n0 -debug ~x ~c Release +echo %~n0 -GetNuTool "Conari;regXwild;Fnv1a128" +echo %~n0 -GetNuTool vsSolutionBuildEvent/1.16.0:../SDK ^& SDK\GUI +echo %~n0 -cs -no-less-15 /t:Rebuild goto endpoint @@ -694,7 +694,7 @@ exit /B 0 :: :batOrExe :obsolete {in:old} {in:new} [{in:new2}] - call :warn "'%~1' is obsolete. Use alternative: %~2 %~3" + call :warn "'%~1' is obsolete. Use: %~2 %~3" exit /B 0 :: :obsolete