build_cache.path correction

[mcspr]

Please check if the PR fulfills these requirements

See how to contribute

• The PR has no duplicates (please search among the Pull Requests
  before creating one)
• The PR follows
  our contributing guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)
• UPGRADING.md has been updated with a migration guide (for breaking changes)
• configuration.schema.json updated if new parameters are added.

What kind of change does this PR introduce?

Correction for #2919 and using $VAR

These are values from Go docs
https://pkg.go.dev/os#UserCacheDir

Actual CLI code falls back to /tmp when neither $HOME or XDG variables are available

arduino-cli/internal/cli/configuration/defaults.go

Line 56 in 55f86b5

setDefaultValueAndKeyTypeSchema("build_cache.path", getDefaultBuildCacheDir())

arduino-cli/internal/cli/configuration/configuration.go

Lines 105 to 114 in 55f86b5

	func getDefaultBuildCacheDir() string {
	var cacheDir *paths.Path
	if p, err := os.UserCacheDir(); err == nil {
	cacheDir = paths.New(p)
	} else {
	// fallback to /tmp
	cacheDir = paths.TempDir()
	}
	return cacheDir.Join("arduino").String()
	}

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change, and is [titled accordingly]

Other information

[CLAassistant]

All committers have signed the CLA.

[per1234]

The change you propose from the brace-wrapped placeholders that are currently the established style to environment variables is reasonable, but it must be done comprehensively rather than only in this specific passage of the documentation.

[per1234]

Suggested change

	- on Windows is: `%LocalAppData%/arduino`
	- on Windows is: `%LOCALAPPDATA%/arduino`

This is the canonical capitalization:

> Get-Item -Path Env:LocalAppData

Name                           Value
----                           -----
LOCALAPPDATA                   C:\Users\per\AppData\Local

[mcspr]

True, but Windows is case insensitive here.
It is more readable that just all upper or lower case though?

[per1234]

If we are going down the path of discussing which of arbitrary forms of the variable name are most clear, I will argue that all caps most effectively communicates that we are referring to an environment variable, as that is the standard convention.

[per1234]

Suggested change

	If neither `$HOME` nor `$XDG_CACHE_HOME` are defined, a temporary directory will be used.

This is an emergency "belt and suspenders" fallback measure. We don't need to clutter up the documentation with information that will only be relevant for the <0.01% of users who have a completely borked operating system.

[mcspr]

Seems more evil than reasonable by hiding vital implementation detail :)
The goal is not to please 0.01%, but to have an actual code implementation referenced as doc. In case implementation changes, I would urge to update the doc as well.

[per1234]

My decision stands. If you don't remove this then the pull request will be rejected.

[mcspr]

It is not belt and suspenders, if we are explaining in depth how the system works for the specific reason to avoid misunderstanding it.

Consider container with incorrectly configured env, or incorrectly sandboxed shell session
(...and how I got included in the 0.01% use-cases here...). Not truly impossible thing to happen.

Or a 2nd opinion, perhaps? I am truly misunderstanding the reasoning here, and the harsh response.

[mcspr]

The change you propose from the brace-wrapped placeholders that are currently the established style to environment variables is reasonable, but it must be done comprehensively rather than only in this specific passage of the documentation.

Do you mean that PR should change {HOME} in other keys as well? Could always update in a separate one.
In this case it is referencing multiple platform-dependent variables, so $ / % seemed more appropriate. Plus, { and } are not part of the name

For configuration.md this is indeed the used pattern, but not on other pages. One used style is simply environment variable "FOO". Another one is `FOO`: this does something / | FOO | description | table
https://github.com/search?q=repo%3Aarduino%2Farduino-cli+environment+variable+language%3AMarkdown&type=code&l=Markdown

{foo} style is used more often than not for platform properties, not OS environment

[per1234]

Do you mean that PR should change {HOME} in other keys as well?

Yes.

Could always update in a separate one.

Pull requests should be atomic. This means it completely accomplishes a single task. Using multiple pull requests to perform this trivial change would only clutter up the project's commit history.

$ / % seemed more appropriate.

I agree. I have been bothered by the use of that brace wrapped placeholder style and very much welcome your proposal to change it to something more standardized.

{foo} style is used more often than not for platform properties

To be clear, I am not requesting you to change the format of platform properties in the documentation. This is only about the placeholders that have an equivalent system environment variable.

In the case of platform properties, the brace wrapped format is less unreasonable than $ would be. I do feel that the practice of wrapping platform properties in braces in the documentation was a poor decision and that the documentation would be made significantly more clear by their removal, except in cases where we are actually talking about a property reference. However, such a change is out of scope for this pull request.