Skip to content

Commit

Permalink
docs: Mac pkg docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mistydemeo committed Aug 27, 2024
1 parent 5df4d24 commit 0149abc
Show file tree
Hide file tree
Showing 4 changed files with 35 additions and 2 deletions.
1 change: 1 addition & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
- [npm](./installers/npm.md)
- [homebrew](./installers/homebrew.md)
- [msi](./installers/msi.md)
- [pkg](./installers/pkg.md)
- [updater](./installers/updater.md)
- [Artifacts](./artifacts/index.md)
- [archives](./artifacts/archives.md)
Expand Down
3 changes: 2 additions & 1 deletion book/src/installers/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Currently supported installers include:
* [npm][]: an npm project that fetches and runs executables (for `npx`)
* [homebrew][]: a Homebrew formula that fetches and installs executables
* [msi][]: a Windows msi that bundles and installs executables
* [pkg][]: a Mac pkg that bundles and installs executables

These keys can be specified via [`installer` in your cargo-dist config][config-installers]. The [`cargo dist init` command][init] provides an interactive UI for enabling/disabling them.

Expand Down Expand Up @@ -77,8 +78,8 @@ Installers which support bundling:
[msi]: ./msi.md
[npm]: ./npm.md
[homebrew]: ./homebrew.md
[pkg]: ./pkg.md

[archives]: ../artifacts/archives.md
[artifact-url]: ../reference/artifact-url.md
[init]: ../reference/cli.md#cargo-dist-init

31 changes: 31 additions & 0 deletions book/src/installers/pkg.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
# pkg Installer

> Since 0.22.0
<!-- toc -->

This guide will walk you through setting up a [bundling][] macOS `pkg` installer, which is the native graphical installer format on macOS. It assumes you've already done initial setup of cargo-dist, as described in [the way-too-quickstart][quickstart], and now want to add a pkg to your release process.

## Setup

### Setup Step 1: run init and enable "pkg"

Rerun `cargo dist init` and when it prompts you to choose installers, enable "pkg". After you've selected "pkg", you'll be asked for two pieces of information:

- An "identifier": this is a unique identifier for your application in reverse-domain name format. For more information, see [Apple's documentation for `CFBundleIdentifier`](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW1).
- The install location: by default, the pkg installer will place your software in `/usr/local` on the user's system. You can specify an alternate location if you prefer.

Once init completes, some changes will be made to your project, **check all of them in**:

1. `installers = ["pkg]"]` will be added to `[workspace.metadata.dist]`
2. `[package.metadata.dist.mac-pkg-config]` will be added to your packages with distable binaries.

### Setup Step 2: you're done! (time to test)

See [the quickstart's testing guide][testing] for the various testing options.

If the above steps worked, `cargo dist plan` should now include a pkg for each Mac platform you support. You can create an installer by running `cargo dist build` on a Mac; it will be placed next to your software in the `target/distrib` folder, and can be installed just by double-clicking it.

[quickstart]: ../quickstart/index.md
[testing]: ../quickstart/rust.md#test-it-out
[bundling]: ./index.md#bundling-installers
2 changes: 1 addition & 1 deletion cargo-dist/src/errors.rs
Original file line number Diff line number Diff line change
Expand Up @@ -528,7 +528,7 @@ pub enum DistError {

/// Missing configuration for a .pkg
#[error("A Mac .pkg installer was requested, but the config is missing")]
#[diagnostic(help("Please ensure a dist.mac-pkg-config section is present in your config. For more details see: https://example.com"))]
#[diagnostic(help("Please ensure a dist.mac-pkg-config section is present in your config. For more details see: https://opensource.axo.dev/cargo-dist/book/installers/pkg.html"))]
MacPkgConfigMissing {},

/// User left identifier empty in init
Expand Down

0 comments on commit 0149abc

Please sign in to comment.