feat: pkg followups

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

cargo-dist/src/init.rs

@@ -733,6 +733,7 @@ fn get_new_dist_metadata(
                 InstallerStyle::Npm,
                 InstallerStyle::Homebrew,
                 InstallerStyle::Msi,
+                InstallerStyle::Pkg,
             ]
         } else {
             eprintln!("{notice} no CI backends enabled, most installers have been hidden");
@@ -849,6 +850,72 @@ fn get_new_dist_metadata(
         }
     }
 
+    // Special handling of the pkg installer
+    if meta
+        .installers
+        .as_deref()
+        .unwrap_or_default()
+        .contains(&InstallerStyle::Pkg)
+    {
+        let pkg_is_new = !orig_meta
+            .installers
+            .as_deref()
+            .unwrap_or_default()
+            .contains(&InstallerStyle::Pkg);
+
+        if pkg_is_new && orig_meta.mac_pkg_config.is_none() {
+            let prompt = r#"you've enabled a Mac .pkg installer. This requires a unique bundle ID;
+    please enter one now. This is in reverse-domain name format.
+    For more information, consult the Apple documentation:
+    https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html#//apple_ref/doc/uid/10000123i-CH101-SW1"#;
+            let default = "".to_string();
+
+            let identifier: String = if args.yes {
+                default
+            } else {
+                let res = Input::with_theme(&theme)
+                    .with_prompt(prompt)
+                    .allow_empty(true)
+                    .interact_text()?;
+                eprintln!();
+                res
+            };
+            let identifier = identifier.trim();
+            if identifier.is_empty() {
+                return Err(DistError::MacPkgBundleIdentifierMissing {});
+            }
+
+            let prompt = r#"Please enter the installation prefix this .pkg should use."#;
+            let prefix = if args.yes {
+                None
+            } else {
+                let res: String = Input::with_theme(&theme)
+                    .with_prompt(prompt)
+                    .allow_empty(true)
+                    .interact_text()?;
+                eprintln!();
+
+                let trimmed = res.trim();
+                if trimmed.is_empty() {
+                    None
+                } else {
+                    Some(trimmed.to_owned())
+                }
+            };
+
+            meta.mac_pkg_config = Some(config::MacPkgConfig {
+                identifier: Some(identifier.to_owned()),
+                install_location: prefix,
+            })
+        }
+    }
+
+    meta.publish_jobs = if publish_jobs.is_empty() {
+        None
+    } else {
+        Some(publish_jobs.to_owned())
+    };
+
     // Special handling of the npm installer
     if meta
         .installers