axodotdev / axodotdev/cargo-dist
document/bless installer args, and make sure they're consistent
- Dominant language
- Rust
- Stars
- 2.1k
- Forks
- 149
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 32
Description
Although our installers are largely designed to just be run without any user input, they *do* support several useful inputs.
We've never guaranteed/documented these arguments, as they largely fall into 2 major buckets:
* protocol between the installer and axoupdater
* something used for internal testing/debugging of installers
The former are defacto API we should document and are confident work consistently. The latter are inconsistent and I wouldn't rely on today, but some of them contain useful functionality that we *should* bless and make consistent. In general env-vars should be preferred since powershell and shell disagree on conventional cli argument naming so it's more straightforward to tell users "this is how you set vars in xyz, now here are the vars".
# Definitely Works
These are definitely tested protocol, and we should document/guarantee them. Although INSTALLER_NO_MODIFY_PATH maybe wants to be renamed to match INSTALL_DIR? If it is we'll keep the old one working fine since there's no maintenance cost on that.
* `{APP_NAME}_INSTALL_DIR=/path/to/dir/`: used to tell the installer the "base" dir to install to (this may have things like `./bin/` appended to them to satisfy your [install dir structure](https://opensource.axo.dev/cargo-dist/book/reference/config.html#install-path), so it's not necessarily the dir the bins get installed to. Formalizing/documenting this is #934 and #1233).
* aka `CARGO_DIST_FORCE_INSTALL_DIR`
* `INSTALLER_NO_MODIFY_PATH=1`: used to tell the installer to skip all the logic that tries to edit rcfiles or the registry to persistently add the dir to PATH
* `--no-modify-path` in shell
* `-NoModifyPath` in powershell
# Sourced As A Matter Of Course
Some other env-vars get read as a matter of course, and are not per se "configuration".
See #934 and #1233 for some planned changes here.
* install path vars
* `$HOME` is you use either the [CARGO_HOME or `~/sub/dir` install-path](https://opensource.axo.dev/cargo-dist/book/reference/config.html#install-path)
* `$CARGO_HOME` if you have the [CARGO_HOME install-path](https://opensource.axo.dev/cargo-dist/book/reference/config.html#install-path)
* `$MY_ENV_VAR` if you have the [`$MY_ENV_VAR/sub/dir` install-path](https://opensource.axo.dev/cargo-dist/book/reference/config.html#install-path)
* path vars
* `$GITHUB_PATH` will be modified if we see it, to force CI tasks to immediately put the installed app on PATH without a source/restart
* `$PATH` may be checked to see if the install dir is already on PATH
* receipt vars (used to write install receipt used by updater)
* `$HOME` (`$HOME/.config/{app_name}`) in shell
* `$LOCALAPPDATA` for (`$LOCALAPPDATA/{{ app_name }}` in powershell
* #1355
# Debug Stuff
* base download url: a url to a "directory" containing all the artifacts we might want to fetch. download urls are created by appending the artifact name to the url. This is not something users should really be messing with.
* `INSTALLER_DOWNLOAD_URL` in shell
* `-ArtifactDownloadUrl` in powershell
* verbose: print extra messages to debug the installer
* `INSTALLER_PRINT_VERBOSE` in shell
* `-v, --verbose` in shell
* [`-Verbose` in powershell](https://learn.microsoft.com/en-ca/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-5.1)
* quiet: print less messages
* `INSTALLER_PRINT_QUIET` in shell
* `-q, --quiet` in shell
* [probably some equivalent in powershell from builtin params, but it's non-obvious](https://learn.microsoft.com/en-ca/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-5.1)
Contributor guide
Assessment
This issue has not been assessed yet.