BlueGit

timfa posprint

docs: document macOS build, CLI printing, and posprint:// handler

timfa Omer Pesket · pushed by timfa

Authored 2026-10-26 · 3 weeks ago

Hash
528d4d7aac76b542cbf7a5dcfbee12e7cf716624
Parent
3c4d57ea
4 files changed +20 −6
README.md +4 −3
@@ -2,7 +2,7 @@
2 2
3 3 Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print via raw ESC/POS (USB printer-class, Windows spooler, USB-serial, or Classic Bluetooth SPP after OS pairing).
4 4
5 **Target platforms:** Windows and Linux (x64).
5 **Target platforms:** Windows, Linux (x64), and macOS (Apple Silicon / Intel).
6 6
7 7 ## Status
8 8
@@ -18,7 +18,7 @@ cargo run # launch the designer
18 18 cargo build --release
19 19 ```
20 20
21 **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
21 **Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`, `scripts/build-macos.sh`
22 22 (Interactive shells offer to install missing dependencies.)
23 23
24 24 ### Command-line printing
@@ -30,7 +30,8 @@ posprint list
30 30 # Windows (serial, Bluetooth COM after pairing, or spooler queue name)
31 31 posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
32 32
33 # Linux (USB-serial or RFCOMM after pairing)
33 # Linux / macOS (USB-direct, 'auto', USB-serial, or RFCOMM/Bluetooth SPP)
34 posprint print receipt.pos -p auto --set StoreName="Shop" --set DocumentNumber=42
34 35 posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
35 36
36 37 # Embedded CLI help for this OS
@@ -2,7 +2,7 @@
2
2
3Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print via raw ESC/POS (USB printer-class, Windows spooler, USB-serial, or Classic Bluetooth SPP after OS pairing).
3Cross-platform designer for POS (point-of-sale) receipt documents. Edit templates in a markdown-like syntax, preview output live, substitute runtime parameters, and print via raw ESC/POS (USB printer-class, Windows spooler, USB-serial, or Classic Bluetooth SPP after OS pairing).
4
4
5**Target platforms:** Windows and Linux (x64).
5**Target platforms:** Windows, Linux (x64), and macOS (Apple Silicon / Intel).
6
6
7## Status
7## Status
8
8
@@ -18,7 +18,7 @@ cargo run # launch the designer
18cargo build --release
18cargo build --release
19```
19```
20
20
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`
21**Scripts:** `scripts/build-windows.ps1`, `scripts/build-linux.sh`, `scripts/build-arch.sh`, `scripts/build-macos.sh`
22(Interactive shells offer to install missing dependencies.)
22(Interactive shells offer to install missing dependencies.)
23
23
24### Command-line printing
24### Command-line printing
@@ -30,7 +30,8 @@ posprint list
30# Windows (serial, Bluetooth COM after pairing, or spooler queue name)
30# Windows (serial, Bluetooth COM after pairing, or spooler queue name)
31posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
31posprint print receipt.pos -p COM3 --set StoreName="Shop" --set DocumentNumber=42
32
32
33# Linux (USB-serial or RFCOMM after pairing)
33# Linux / macOS (USB-direct, 'auto', USB-serial, or RFCOMM/Bluetooth SPP)
34posprint print receipt.pos -p auto --set StoreName="Shop" --set DocumentNumber=42
34posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
35posprint print receipt.pos -p /dev/ttyUSB0 --set StoreName="Shop" --set DocumentNumber=42
35
36
36# Embedded CLI help for this OS
37# Embedded CLI help for this OS
docs/BUILD.md +13 −1
@@ -1,6 +1,6 @@
1 1 # Build scripts
2 2
3 Local release builds for Windows and Linux.
3 Local release builds for Windows, Linux, and macOS.
4 4
5 5 ## Toolchain
6 6
@@ -35,6 +35,18 @@ Options:
35 35 .\scripts\build-windows.ps1 -SkipTests
36 36 ```
37 37
38 ## macOS
39
40 ```bash
41 chmod +x scripts/build-macos.sh
42 ./scripts/build-macos.sh # release binary (target/release/posprint)
43 ./scripts/build-macos.sh --app # binary + target/macos/Posprint.app
44 ./scripts/build-macos.sh --dmg # binary + Posprint.app + target/macos/Posprint-<ver>-macos-<arch>.dmg
45 ./scripts/build-macos.sh --install # build Posprint.app, install to /Applications & PATH, register posprint://
46 ```
47
48 `Posprint.app` bundles the native `posprint` binary together with an AppleEvent launcher (`packaging/macos/Info.plist`) so clicking `posprint://` deep links in Safari/Chrome or opening `.pos` files in Finder launches `posprint` automatically.
49
38 50 ## Linux
39 51
40 52 ```bash
@@ -1,6 +1,6 @@
1# Build scripts
1# Build scripts
2
2
3Local release builds for Windows and Linux.
3Local release builds for Windows, Linux, and macOS.
4
4
5## Toolchain
5## Toolchain
6
6
@@ -35,6 +35,18 @@ Options:
35.\scripts\build-windows.ps1 -SkipTests
35.\scripts\build-windows.ps1 -SkipTests
36```
36```
37
37
38## macOS
39
40```bash
41chmod +x scripts/build-macos.sh
42./scripts/build-macos.sh # release binary (target/release/posprint)
43./scripts/build-macos.sh --app # binary + target/macos/Posprint.app
44./scripts/build-macos.sh --dmg # binary + Posprint.app + target/macos/Posprint-<ver>-macos-<arch>.dmg
45./scripts/build-macos.sh --install # build Posprint.app, install to /Applications & PATH, register posprint://
46```
47
48`Posprint.app` bundles the native `posprint` binary together with an AppleEvent launcher (`packaging/macos/Info.plist`) so clicking `posprint://` deep links in Safari/Chrome or opening `.pos` files in Finder launches `posprint` automatically.
49
38## Linux
50## Linux
39
51
40```bash
52```bash
docs/HELP-CLI-LINUX.md +2 −2
@@ -1,4 +1,4 @@
1 # Command-line printing (Linux)
1 # Command-line printing (Linux & macOS)
2 2
3 3 Print a `.pos` template without opening the GUI.
4 4
@@ -24,7 +24,7 @@ posprint link receipt.pos
24 24 ## Rules
25 25
26 26 - **`posprint list`**: print discovered printers (USB, USB-serial, paired Classic Bluetooth SPP). Use the device path from the list as `-p`.
27 - **`--printer` / `-p`** (required): serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/rfcomm0` after OS pairing), or another printer id accepted by discovery.
27 - **`--printer` / `-p`** (required): printer id from `posprint list` (e.g. `usb:28e9:0289:0:1` or `usb:28e9:0289`), `auto` (first discovered printer), or serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/rfcomm0`, `/dev/cu.usbserial-*`).
28 28 - **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` or `$[Name]` in the template.
29 29 - Checkbox params (`$[Name]`): use `true`/`false` (also `1`/`0`, `yes`/`no`).
30 30 - If any text `${Name}` is missing or empty, or a `$[Name]` is omitted / not a boolean, the command **fails**.
@@ -1,4 +1,4 @@
1# Command-line printing (Linux)
1# Command-line printing (Linux & macOS)
2
2
3Print a `.pos` template without opening the GUI.
3Print a `.pos` template without opening the GUI.
4
4
@@ -24,7 +24,7 @@ posprint link receipt.pos
24## Rules
24## Rules
25
25
26- **`posprint list`**: print discovered printers (USB, USB-serial, paired Classic Bluetooth SPP). Use the device path from the list as `-p`.
26- **`posprint list`**: print discovered printers (USB, USB-serial, paired Classic Bluetooth SPP). Use the device path from the list as `-p`.
27- **`--printer` / `-p`** (required): serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/rfcomm0` after OS pairing), or another printer id accepted by discovery.
27- **`--printer` / `-p`** (required): printer id from `posprint list` (e.g. `usb:28e9:0289:0:1` or `usb:28e9:0289`), `auto` (first discovered printer), or serial device path (e.g. `/dev/ttyUSB0`, `/dev/ttyACM0`, `/dev/rfcomm0`, `/dev/cu.usbserial-*`).
28- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` or `$[Name]` in the template.
28- **`--set NAME=VALUE`** (required for every parameter): one flag per `${Name}` or `$[Name]` in the template.
29- Checkbox params (`$[Name]`): use `true`/`false` (also `1`/`0`, `yes`/`no`).
29- Checkbox params (`$[Name]`): use `true`/`false` (also `1`/`0`, `yes`/`no`).
30- If any text `${Name}` is missing or empty, or a `$[Name]` is omitted / not a boolean, the command **fails**.
30- If any text `${Name}` is missing or empty, or a `$[Name]` is omitted / not a boolean, the command **fails**.
docs/POSPRINT-URL.md +1 −0
@@ -143,6 +143,7 @@ const auto = posprintUrl(pos, {
143 143 |----------|-----|
144 144 | **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
145 145 | **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
146 | **macOS (`Posprint.app`)** | `Info.plist` registers `CFBundleURLSchemes = ["posprint"]` with LaunchServices and forwards `open location` AppleEvents to `posprint` |
146 147
147 148 After a Linux package install, if links do not open:
148 149
@@ -143,6 +143,7 @@ const auto = posprintUrl(pos, {
143|----------|-----|
143|----------|-----|
144| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
144| **Windows** | On each launch, posprint registers `HKCU\Software\Classes\posprint` → `"<exe>" "%1"` |
145| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
145| **Linux (deb/Arch)** | Ships `posprint-url.desktop` with `MimeType=x-scheme-handler/posprint` |
146| **macOS (`Posprint.app`)** | `Info.plist` registers `CFBundleURLSchemes = ["posprint"]` with LaunchServices and forwards `open location` AppleEvents to `posprint` |
146
147
147After a Linux package install, if links do not open:
148After a Linux package install, if links do not open:
148
149