[skip changelog] Document Arduino CLI's configuration methods #748
Conversation
|
I really like this! 👍 It answers a lot of my longstanding questions about arduino-cli configuration, both in understanding what keys are available and what they mean, and how to effect change in configuration. Thanks for the documentation, people who document deserve extra good karma! |
docs/configuration.md
Outdated
|
|
||
| #### Supported formats | ||
|
|
||
| * [YAML] |
There was a problem hiding this comment.
Actually, we support all these formats:
JSON, TOML, YAML, HCL, envfile and Java properties config files
thanks to the spf13/Viper module!
There was a problem hiding this comment.
I'm very glad you raised this point. I was aware that Viper claimed to support all these, but when I tried to test it, I was disappointed to find I couldn't get any of the alternative formats other than JSON to be recognized. It turns out the problem was either a bug in Arduino CLI, or me not understanding the way it works. If there are multiple configuration files in the path, there is an order of precedence, even if you specify a file using --config-file:
$ ./arduino-cli config dump --verbose --config-file arduino-cli.toml
INFO[0000] Using config file: /home/per/ArduinoIDE/arduino-cli_nightly/arduino-cli.json
(note that I specified the .toml file, but the .json file was used instead)
The problem was that I had a JSON file in the same folder as all the configuration files of other formats, so that JSON file always took precedence, even though the rest of the files were perfectly valid and supported.
I have updated the "Supported formats" section of the document accordingly.
Is this a bug? If so, I can submit a dedicated issue for it. If not, maybe we need to document this behavior? I'll concede it's likely a very rare occurrence for someone to have multiple configuration files. I did put the list of supported formats in their order of precedence.
The --config-file option's documentation seems somewhat misleading to me:
--config-file string The custom config file (if not specified the default will be used).
From reading that, I would expect to be able to specify any filename, but it turns out that it's required to be arduino-cli.whatever:
$ ./arduino-cli config dump --verbose --config-file foo.json
INFO[0000] Config file not found, using default values
Although you can specify the filename, with the current behavior it seems to be more of a config path option rather than a config file option:
$ ./arduino-cli config dump --verbose --config-file ./config
INFO[0000] Using config file: /home/per/ArduinoIDE/arduino-cli_nightly/config/arduino-cli.json
Specifying the filename only has an effect if the file doesn't exist:
$ ./arduino-cli config dump --verbose --config-file nonexistent.json
INFO[0000] Config file not found, using default values
Otherwise, Arduino CLI disregards the filename and uses its preferred configuration file from that path.
I have updated the "File name" section of the document accordingly.
There was a problem hiding this comment.
Thanks @per1234 for pointing that out!
IMHO from the docs perspective, this PR is correct.
Regarding the config file loading, I think you discovered a bug 😸
Please open an issue, as you said, whit this comment content. This is something we need to fix together wit other config file loading related small issues.
The ability to configure Arduino CLI via environment variables is only documented by a mention in the integration options article, which is not an obvious place to look for that information. Since this information didn't fit well in any of the existing pages, it makes sense to add a dedicated page, and add some documentation for the other two configuration methods as well. Although there is existing documentation for the other configuration methods elsewhere in the docs, it is missing some useful specifics, which wouldn't be appropriate to add there.
The ability to configure Arduino CLI via environment variables is only documented by a mention in the integration options article, which is not an obvious place to look for that information. Since this information didn't fit well in any of the existing pages, it makes sense to add a dedicated page, and add some documentation for the other two configuration methods as well. Although there is existing documentation for the other configuration methods elsewhere in the docs, it is missing some useful specifics, which wouldn't be appropriate to add there.
Please check if the PR fulfills these requirements
Add page to documentation describing the various options for configuring Arduino CLI.
The ability to configure Arduino CLI via environment variables is only documented by a mention in the integration options article, which is not an obvious place to look for that information. Other aspects of configuration are undocumented.
Since this information didn't fit well in any of the existing pages, it makes sense to add a dedicated page, and add some documentation for the other two configuration methods as well. Although there is existing documentation for the other configuration methods elsewhere in the docs, it is missing some useful specifics, which wouldn't be appropriate to add there.
No
Fixes #713 (in conjunction with the already merged #732)
@itsayellow, I welcome your feedback on this.
An alternative to the "Configuration keys" section of this document would be to create a JSON schema for the configuration file (#587), then generate the user documentation of the configuration file keys from the JSON schema file.