Merge pull request #230 from kevinaboos/extract-before-packaging-command

Extract before packaging command to `robius-packaging-commands` crate

Cargo.toml

@@ -124,7 +124,7 @@ macOS, Windows, Linux, Android, and iOS.
 icons = ["./packaging/robrix_logo_alpha.png"]
 out_dir = "./dist"
 
-## The below command uses cargo-metadata to determine the path of the `makepad_widgets` crate on the host build system,
+## The below command primarily uses cargo-metadata to determine the path of the `makepad_widgets` crate on the host build system,
 ## and copies the `makepad-widgets/resources` directory to the `./dist/resources/makepad_widgets` directory.
 ## We also copy the Robrix project's `resources/` directory to the `./dist/resources/robrix` directory.
 ##
@@ -133,19 +133,20 @@ out_dir = "./dist"
 ## so we need to copy the resources to a known fixed (static) path before packaging,
 ## such that cargo-packager can locate them and include them in the final package.
 before-packaging-command = """
-cargo run --manifest-path packaging/before-packaging-command/Cargo.toml \
-    before-packaging \
+robius-packaging-commands before-packaging \
+    --force-makepad \
     --binary-name robrix \
     --path-to-binary ./target/release/robrix
 """
 
+
 ## See the above paragraph comments for more info on how we create/populate the below `src` directories.
 resources = [
     { src = "./dist/resources/makepad_widgets", target = "makepad_widgets" },
     { src = "./dist/resources/robrix", target = "robrix" },
 ]
 
-## We then build the entire Robrix project and set the `MAKEPAD_PACKAGE_DIR` env var to the proper value.
+## We then build the entire Robrix project and set the `MAKEPAD`/`MAKEPAD_PACKAGE_DIR` env vars to the proper value.
 ## * For macOS app bundles, this should be set to `.` because we set the `apple_bundle` cfg option
 ##   for Makepad, which causes Makepad to look for resources in the `Contents/Resources/` directory,
 ##   which is where the resources are located for an Apple app bundle (`.app` and `.dmg`).
@@ -156,8 +157,8 @@ resources = [
 ##   * For Debian and Pacman (still a to-do!) packages, we also auto-generate the list of dependencies required by Robrix.
 ##
 before-each-package-command = """
-cargo run --manifest-path packaging/before-packaging-command/Cargo.toml \
-    before-each-package \
+robius-packaging-commands before-each-package \
+    --force-makepad \
     --binary-name robrix \
     --path-to-binary ./target/release/robrix
 """

README.md

@@ -133,3 +133,72 @@ These are generally sorted in order of priority. If you're interested in helping
 ## Known problems/issues
  - Matrix-specific links are not yet fully handled (https://matrix.to/...)
  - Ignoring/unignoring a user clears all timelines  (see: https://github.com/matrix-org/matrix-rust-sdk/issues/1703); the timeline will be re-filled using gradual pagination, but the viewport is not maintained
+
+
+## Packaging Robrix for Distribution on Desktop Platforms
+
+> [!TIP]
+> We already have [pre-built releases of Robrix](https://github.com/project-robius/robrix/releases) available for download.
+
+
+1. Install `cargo-packager`:
+```sh
+rustup update stable  ## Rust version 1.79 or higher is required
+cargo +stable install --force --locked cargo-packager
+```
+For posterity, these instructions have been tested on `cargo-packager` version 0.10.1, which requires Rust v1.79.
+
+2. Install the `robius-packaging-commands` crate with the `makepad` feature enabled:
+```sh
+cargo install --locked --git https://github.com/project-robius/robius-packaging-commands.git
+```
+
+3. Then run the packaging command, which must build in release mode:
+```sh
+cargo packager --release ## --verbose is optional
+```
+
+
+### Platform-specific considerations
+Note that due to platform restrictions, you can currently only build:
+* Linux packages on a Linux OS machine
+* Windows installer executables on a Windows OS machine
+* macOS disk images / app bundles on a macOS machine
+* iOS apps on a macOS machine.
+* Android, on a machine with any OS!
+
+There are some additional considerations when packaging Robrix for macOS:
+
+> [!IMPORTANT]
+> You will see a .dmg window pop up — please leave it alone, it will auto-close once the packaging procedure has completed.
+
+> [!TIP]
+> If you receive the following error:
+>
+> ```
+> ERROR cargo_packager::cli: Error running create-dmg script: File exists (os error 17)
+> ```
+>
+> then open Finder and unmount any Robrix-related disk images, then try the above `cargo packager` command again.
+
+> [!TIP]
+> If you receive an error like so:
+>
+> ```
+> Creating disk image...
+> hdiutil: create failed - Operation not permitted
+> could not access /Volumes/Robrix/Robrix.app - Operation not permitted
+> ```
+>
+> then you need to grant "App Management" permissions to the app in which you ran the `cargo packager` command, e.g., Terminal, Visual Studio Code, etc.
+> To do this, open `System Preferences` → `Privacy & Security` → `App Management`,
+> and then click the toggle switch next to the relevant app to enable that permission.
+> Then, try the above `cargo packager` command again.
+
+After the command completes, you should see both the `Robrix.app` and the `.dmg` in the `dist/` directory.
+You can immediately double-click the `Robrix.app` bundle to run it, or you can double-click the `.dmg` file to
+
+> Note that the `.dmg` is what should be distributed for installation on other machines, not the `.app`.
+
+If you'd like to modify the .dmg background, here is the [Google Drawings file used to generate the MacOS .dmg background image](https://docs.google.com/drawings/d/10ALUgNV7v-4bRTIE5Wb2vNyXpl2Gj3YJcl7Q2AGpvDw/edit?usp=sharing).
+