docs: Mac pkg docs

Author: mistydemeo

book/src/SUMMARY.md

@@ -18,6 +18,7 @@
   - [npm](./installers/npm.md)
   - [homebrew](./installers/homebrew.md)
   - [msi](./installers/msi.md)
+  - [pkg](./installers/pkg.md)
   - [updater](./installers/updater.md)
   - [Usage](./installers/usage.md)
 - [Artifacts](./artifacts/index.md)

book/src/installers/index.md

@@ -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 dist config][config-installers]. The [`dist init` command][init] provides an interactive UI for enabling/disabling them.
 
@@ -80,6 +81,7 @@ Our installers are meant to be usable as-is, without requiring any special optio
 [msi]: ./msi.md
 [npm]: ./npm.md
 [homebrew]: ./homebrew.md
+[pkg]: ./pkg.md
 [usage]: ./usage.md
 
 [archives]: ../artifacts/archives.md

book/src/installers/pkg.md

@@ -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

cargo-dist/src/errors.rs

@@ -603,7 +603,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