actions/setup-msbuild
1
0
Fork 0
mirror of https://github.com/microsoft/setup-msbuild.git synced 2024-11-22 11:31:07 +07:00
Code Issues Packages Projects Releases Wiki Activity

Adding runner image doc note [skip ci]

Browse Source
This commit is contained in:
Tim Heuer 2023-08-14 08:38:37 -07:00
parent 1ff57057b5
commit 3404ff3d40
1 changed files with 14 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
README.md
View File

@ -1,4 +1,5 @@
# microsoft/setup-msbuild # microsoft/setup-msbuild
This action will help discover where the `MSBuild` tool is and automatically add it to the `PATH` environment variables for you so future steps in your Actions workflow can just initiate `msbuild` commands without knowing the full path. This action will help discover where the `MSBuild` tool is and automatically add it to the `PATH` environment variables for you so future steps in your Actions workflow can just initiate `msbuild` commands without knowing the full path.
> Please note this tool does NOT add other Visual Studio tools (like VSTest, cl, cmake, or others) to `PATH` > Please note this tool does NOT add other Visual Studio tools (like VSTest, cl, cmake, or others) to `PATH`
@ -13,10 +14,16 @@ This action will help discover where the `MSBuild` tool is and automatically add
run: msbuild src\YourProjectFile.csproj -t:rebuild -verbosity:diag -property:Configuration=Release run: msbuild src\YourProjectFile.csproj -t:rebuild -verbosity:diag -property:Configuration=Release
``` ```
## Runners and included software
This action is intended to be used within the GitHub Actions workflows using the model of 'runners' either hosted (provided by GitHub) or self-hosted (provided by you). The version and parameters you specify below are going to be scoped to what software actually exists on the runner image being used. For example, hosted runner images from GitHub typically do NOT have pre-release versions of Visual Studio on them so using `vs-prerelease` parameter noted below may not have intended effect when using hosted runners. The software included for GitHub-hosted runner iamges can always be found here: <https://github.com/actions/runner-images> which also includes information on when/how software on hosted images gets updated.
## Optional Parameters ## Optional Parameters
There are a few additional parameters that can be set if you need them. These are optional and should only be set if you know that you need them or what you are doing. There are a few additional parameters that can be set if you need them. These are optional and should only be set if you know that you need them or what you are doing.
### Specifying specific versions of Visual Studio (optional) ### Specifying specific versions of Visual Studio (optional)
You may have a situation where your Actions runner has multiple versions of Visual Studio and you need to find a specific version of the tool. Simply add the `vs-version` input to specify the range of versions to find. If looking for a specific version, specify the minimum and maximum versions as shown in the example below, which will look for just 16.4. You may have a situation where your Actions runner has multiple versions of Visual Studio and you need to find a specific version of the tool. Simply add the `vs-version` input to specify the range of versions to find. If looking for a specific version, specify the minimum and maximum versions as shown in the example below, which will look for just 16.4.
```yml ```yml
@ -29,6 +36,7 @@ You may have a situation where your Actions runner has multiple versions of Visu
The syntax is the same used for Visual Studio extensions, where square brackets like "[" mean inclusive, and parenthesis like "(" mean exclusive. A comma is always required, but eliding the minimum version looks for all older versions and eliding the maximum version looks for all newer versions. See the [vswhere wiki](https://github.com/microsoft/vswhere/wiki) for more details. The syntax is the same used for Visual Studio extensions, where square brackets like "[" mean inclusive, and parenthesis like "(" mean exclusive. A comma is always required, but eliding the minimum version looks for all older versions and eliding the maximum version looks for all newer versions. See the [vswhere wiki](https://github.com/microsoft/vswhere/wiki) for more details.
### Use pre-release versions of Visual Studio (optional) ### Use pre-release versions of Visual Studio (optional)
If you need your Actions runner to target a pre-release version of Visual Studio, simply add the `vs-prerelease` input. This is necessary if you want to run an action on a virtual environment that contains a pre-release version of Visual Studio or self-hosted images that you may have that also have pre-release versions of Visual Studio installed. If you need your Actions runner to target a pre-release version of Visual Studio, simply add the `vs-prerelease` input. This is necessary if you want to run an action on a virtual environment that contains a pre-release version of Visual Studio or self-hosted images that you may have that also have pre-release versions of Visual Studio installed.
```yml ```yml
@ -39,6 +47,7 @@ If you need your Actions runner to target a pre-release version of Visual Studio
``` ```
### Specifying MSBuild architecture (optional) ### Specifying MSBuild architecture (optional)
By default the action will use the x86 architecture for MSBuild, but it is possible to target the x64 versions instead. Simply add the `msbuild-architecture` input. Valid input values are `x86` (default), `x64`, and `arm64`. Note that the success of these will rely on the runner OS. By default the action will use the x86 architecture for MSBuild, but it is possible to target the x64 versions instead. Simply add the `msbuild-architecture` input. Valid input values are `x86` (default), `x64`, and `arm64`. Note that the success of these will rely on the runner OS.
```yml ```yml
@ -49,6 +58,7 @@ By default the action will use the x86 architecture for MSBuild, but it is possi
``` ```
## How does this work? ## How does this work?
This makes use of the vswhere tool which is a tool delivered by Microsoft to help in identifying Visual Studio installs and various components. This tool is installed on the hosted Windows runners for GitHub Actions. If you are using a self-hosted runner, you either need to make sure vswhere.exe is in your agent's PATH or specify a full path to the location using: This makes use of the vswhere tool which is a tool delivered by Microsoft to help in identifying Visual Studio installs and various components. This tool is installed on the hosted Windows runners for GitHub Actions. If you are using a self-hosted runner, you either need to make sure vswhere.exe is in your agent's PATH or specify a full path to the location using:
```yml ```yml
@ -59,9 +69,11 @@ This makes use of the vswhere tool which is a tool delivered by Microsoft to hel
``` ```
## Notes on arguments ## Notes on arguments
While the Action enables you to specify a `vswhere` path as well as a `vs-version`, these are more advanced options and when using GitHub-hosted runners you should not need these and is recommended you don't specify them as they are optional. Using these require you to fully understand the runner environment, updates to the tools on the runner, and can cause failures if you are out of sync. For GitHub-hosted runners, omitting these arguments is the preferred usage. While the Action enables you to specify a `vswhere` path as well as a `vs-version`, these are more advanced options and when using GitHub-hosted runners you should not need these and is recommended you don't specify them as they are optional. Using these require you to fully understand the runner environment, updates to the tools on the runner, and can cause failures if you are out of sync. For GitHub-hosted runners, omitting these arguments is the preferred usage.
## Building this repo ## Building this repo
As with most GitHub Actions, this requires NodeJS development tools. After installing NodeJS, you can build this by executing: As with most GitHub Actions, this requires NodeJS development tools. After installing NodeJS, you can build this by executing:
```bash ```bash
@ -73,13 +85,14 @@ npm run pack
which will modify/create the /dist folder with the final index.js output which will modify/create the /dist folder with the final index.js output
# Credits # Credits
Thank you to [Warren Buckley](https://github.com/warrenbuckley) for being a core contributor to this Action for the benefit of all developers! Thank you to [Warren Buckley](https://github.com/warrenbuckley) for being a core contributor to this Action for the benefit of all developers!
# Contributing # Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
When you submit a pull request, a CLA bot will automatically determine whether you need to provide When you submit a pull request, a CLA bot will automatically determine whether you need to provide
a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions