Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions Documentation/NativeToolsOnMachine.md
Original file line number Diff line number Diff line change
@@ -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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we actually provide multiple pythons ? WHy?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this was just an example of a minor version specification. Python's the only case I could think of for that lol, but hypothetically there are other cases where you'd want to pin a minor version.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider combining lines here, this may look odd on some column widths.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do separate lines so it's easy to pinpoint comments in a PR; it all looks the same when it's rendered in markdown

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.