Skip to content

Commit

Permalink
Merge pull request #859 from axodotdev/updater_docs
Browse files Browse the repository at this point in the history
doc: add updater docs
  • Loading branch information
mistydemeo authored Mar 21, 2024
2 parents 1e10d9f + ac331a9 commit 706b295
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 0 deletions.
1 change: 1 addition & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
- [npm](./installers/npm.md)
- [homebrew](./installers/homebrew.md)
- [msi](./installers/msi.md)
- [updater](./installers/updater.md)
- [Artifacts](./artifacts/index.md)
- [archives](./artifacts/archives.md)
- [checksums](./artifacts/checksums.md)
Expand Down
30 changes: 30 additions & 0 deletions book/src/installers/updater.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# Self-updater

> since 0.12.0
NOTE: This feature is currently experimental.

Ordinarily, your users will need to visit your website and download an installer for the latest release in order to upgrade. Users who installed your software via a package manager, like Homebrew and npm, can use that package manager to upgrade to the latest release. For users of the [shell] and [PowerShell] installers, you can provide your users with a standalone installation program to upgrade more conveniently.

If you add `install-updater = true` to your `Cargo.toml`, cargo-dist's shell and PowerShell installers will include an updater program alongside your program itself. This standalone program will be installed as the name `yourpackage-update`, and users can simply run it to poll for new releases and have them installed. The source code for this program is open source in the [axoupdater] repository.

Users will interact with this updater by running the `yourpackage-update` command. It takes no options or arguments, and will automatically perform an upgrade without further input from the user. If your program supports custom external subcommands via the executable naming structure, like `git` and `cargo` do, then your user can also run `yourpackage update`. Here's a sample `axolotlsay-update` session as a demonstration of what your users will experience:

```
$ axolotlsay-update
Checking for updates...
downloading axolotlsay 0.2.114 aarch64-apple-darwin
installing to /Users/mistydemeo/.cargo/bin
axolotlsay
axolotlsay-update
everything's installed!
New release installed!
```

If you would prefer to handle polling for updates yourself, for example in order to incorporate it as an internal subcommand of your own software, axoupdater is available as a [crate] which can be used as a library within your program. More information about how to use axoupdater as a library in your own program can be found in its README and in its [API documentation][axoupdater-docs].

[axoupdater]: https://github.com/axodotdev/axoupdater
[axoupdater-docs]: https://docs.rs/axoupdater/
[crate]: https://crates.io/crates/axoupdater
[shell]: ../shell.md
[PowerShell]: ../powershell.md
17 changes: 17 additions & 0 deletions book/src/reference/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -459,6 +459,21 @@ Future Improvements:

(Please file an issue if you have other requirements!)

### install-updater

> since 0.12.0
Example: `install-updater = true`

Defaults to false.

NOTE: this feature is currently experimental.

Determines whether to install a standalone updater program alongside your program. This program will be named `yourpackage-update`, and can be run by the user to automatically check for newer versions and install them without needing to visit your website. This updater will only be installed for users who use the shell or Powershell installers; users who received your package from a package manager, such as Homebrew or npm, will need to use the same package manager to perform upgrades.

This updater is the commandline tool contained in the open source [axoupdater] package.

For more information, see the [updater] documentation.

### local-artifacts-jobs

Expand Down Expand Up @@ -734,3 +749,5 @@ Caveat: the default "host" Artifact Mode does something fuzzier with `--target`
[platforms]: https://doc.rust-lang.org/nightly/rustc/platform-support.html
[scope]: https://docs.npmjs.com/cli/v9/using-npm/scope
[crt-static]: https://github.com/rust-lang/rfcs/blob/master/text/1721-crt-static.md#future-work
[axoupdater]: https://github.com/axodotdev/axoupdater
[updater]: ../installers/updater.md

0 comments on commit 706b295

Please sign in to comment.