diff --git a/Documentation/NativeToolsOnMachine.md b/Documentation/NativeToolsOnMachine.md new file mode 100644 index 00000000000..001671a95a8 --- /dev/null +++ b/Documentation/NativeToolsOnMachine.md @@ -0,0 +1,25 @@ +# Using Native Tools on Machine + +The replacement for [native tools bootstrapping](NativeToolsBootstrapping.md) is having all tools needed come pre-installed on +the build machines. This document describes how to onboard to this new process. + +This document only applies to Windows machines as Linux machines already come with native tools installed via package manager. + +## Steps + +1. Before calling `InitializeNativeTools`, `init-tools-native.ps1`, or `eng/common`'s `build.ps1` in PowerShell, + set `$env:NativeToolsOnMachine = $True`. Alternatively, simply set it as an environment variable when calling + a template such as `jobs.yml` in YAML. +2. Modify your `global.json`'s `native-tools` section to change the version of your tools to one of the following values: + - `latest` (e.g. `"cmake": "latest"`) – Grabs the latest version of the tool on the machine; this should be what you use in the majority of cases + - Major version (e.g. `"cmake": "3"`) – Grabs the latest minor & patch version of a particular major version on the machine; this is useful for artifacts you want to pin to a specific major version + - Minor version (e.g. `"python": "3.10"`) – Grabs the latest patch version of a particular minor version on the machine; this is useful for artifacts you want to pin to a specific minor version (such as Python) +3. Adjust any usage of the artifacts on the machines in your scripts. The artifacts you specify in your `global.json` are promoted to the path, + so in general simply calling `cmake` will work. However, if you need the specific locations of tools, `InitializeNativeTools` will return those to + you as a dictionary, e.g.: + ```pwsh + $nativeToolsLocs = InitializeNativeTools + $cmakeLoc = $nativeToolsLocs["cmake"] + ``` + +Once you've executed these steps, you'll be using the native tools installed on the machines. \ No newline at end of file