BlueGit

timfa posprint

Files

posprint / docs / BUILD.md

BUILD.md

BUILD.md 6.4 KiB Download Raw

Build scripts

Local release builds for Windows, Linux, and macOS.

Toolchain

You need a Rust toolchain (1.88+; CI uses 1.96). Install once:

# Recommended (any distro)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# then restart the shell, or: source "$HOME/.cargo/env"

# Or on Arch Linux
sudo pacman -S --needed rust

Also install the platform build libraries under Linux build dependencies below before cargo test / cargo build.

Interactive shells: the build scripts detect missing requirements (Rust, apt/pacman packages, cargo-deb, base-devel) and ask whether to install them automatically. Non-interactive runs (CI/pipes) never prompt; they print install instructions and exit.

Windows

.\scripts\build-windows.ps1

Output: target\release\posprint.exe

If cargo/rustc are missing and the shell is interactive, the script offers to install Rust via winget (Rustlang.Rustup) or rustup-init.

Options:

.\scripts\build-windows.ps1 -SkipTests

macOS

chmod +x scripts/build-macos.sh
./scripts/build-macos.sh                  # release binary (target/release/posprint)
./scripts/build-macos.sh --app            # binary + target/macos/Posprint.app
./scripts/build-macos.sh --dmg            # binary + Posprint.app + target/macos/Posprint-<ver>-macos-<arch>.dmg
./scripts/build-macos.sh --install        # build Posprint.app, install to /Applications & PATH, register posprint://

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.

Linux

chmod +x scripts/build-linux.sh
./scripts/build-linux.sh                # release binary
./scripts/build-linux.sh --deb          # binary + .deb (prompts to install if interactive)
./scripts/build-linux.sh --deb --install  # build .deb and install with apt

On a TTY, missing apt build packages and (with --deb) cargo-deb are offered for install before building.

On Arch Linux:

chmod +x scripts/build-arch.sh
./scripts/build-arch.sh                 # .pkg.tar.zst (prompts to install if interactive)
./scripts/build-arch.sh --install      # build and install with pacman

On a TTY, missing base-devel, Rust, and common pacman build libs are offered for install before building.

build-arch.sh accepts a rustup toolchain on PATH. If the pacman rust/cargo packages are not installed, it runs makepkg --nodeps after verifying rustc/cargo work (the PKGBUILD still lists those packages for AUR/CI).

After a successful package build, both scripts ask whether to install (TTY only). Pass --install to skip the prompt and install automatically. Non-interactive runs (CI/pipes) never prompt.

Outputs:

ArtifactPath
Binarytarget/release/posprint
Debian packagetarget/debian/posprint_<ver>-1_amd64.deb (cargo-deb revision defaults to 1)
Arch packagepackaging/arch/posprint-<ver>-1-x86_64.pkg.tar.zst (hyphens; not posprint_<ver>)
AUR bin tarballdist/posprint-<ver>-x86_64.tar.gz (packed from the non-debug Arch package)

Linux targets we support

FormatDistrosNotes
.debDebian, Ubuntu, Mint, Pop!_OS, etc.Recommended for apt-based systems; produced by cargo-deb
.pkg.tar.zstArch Linux, Manjaro, EndeavourOS, etc.Recommended for pacman; sudo pacman -U posprint-*.pkg.tar.zst
Raw binaryAny x86_64 LinuxCopy target/release/posprint; needs X11/Wayland libs at runtime
.rpmFedora, RHEL, openSUSENot automated yet; build binary and wrap with fpm if needed
AppImageUniversalNot automated yet; good for portable distribution

Architecture: x86_64 (amd64) only in CI and build scripts today.

Linux build dependencies (Debian/Ubuntu)

sudo apt-get install -y build-essential pkg-config \
  libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev \
  libssl-dev libudev-dev

For .deb:

cargo install cargo-deb --locked

Arch Linux build dependencies

sudo pacman -S --needed base-devel rust pkgconf openssl libxkbcommon libxcb dbus \
  wayland libx11 fontconfig freetype2 libglvnd git rsync

AUR publishing

Normal local Arch packaging uses packaging/arch/PKGBUILD.

Automated AUR publishing uses:

  • packaging/aur/PKGBUILD — source package (posprint)
  • packaging/aur-bin/PKGBUILD — binary package (posprint-bin)
  • scripts/publish-aur.sh — updates both AUR repos on tags (uses the local dist/ tarball from build:linux-arch)
  • scripts/make-linux-bin-tarball.sh — packs usr/ from the non-debug Arch CI .pkg.tar.zst
  • scripts/publish-gitlab-release.sh — uploads real dist/ filenames to the Generic Package Registry and attaches them to the GitLab Release

The source package builds from the GitLab tag tarball. The binary package installs a prebuilt tree from the Generic Package Registry (not jobs/artifacts/<tag> permalinks).

Tag pipelines also keep job artifacts for a year, but Release / Package Registry URLs are the ones that stay downloadable if a later job fails.

Setup and required GitLab secrets are documented in AUR.md. To refresh an already-shipped tag (for example 0.5.7), delete and recreate that tag on a commit that contains the current .gitlab-ci.yml — see AUR.md.

File association (.pos → posprint)

The package installs:

  • /usr/share/mime/packages/posprint.xml → MIME type application/x-posprint for *.pos
  • /usr/share/applications/posprint.desktop → claims that MIME type

After pacman -U, pacman hooks refresh the MIME and desktop databases. To make posprint the default opener (double-click):

xdg-mime default posprint.desktop application/x-posprint
xdg-mime query filetype some.pos          # expect: application/x-posprint
xdg-mime query default application/x-posprint  # expect: posprint.desktop

If query filetype still says text/plain, the MIME package was not installed or the cache is stale:

sudo update-mime-database /usr/share/mime
sudo update-desktop-database /usr/share/applications

Tests before release

cargo test --release
Source
1# Build scripts
2
3Local release builds for Windows, Linux, and macOS.
4
5## Toolchain
6
7You need a Rust toolchain (**1.88+**; CI uses 1.96). Install once:
8
9```bash
10# Recommended (any distro)
11curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
12# then restart the shell, or: source "$HOME/.cargo/env"
13
14# Or on Arch Linux
15sudo pacman -S --needed rust
16```
17
18Also install the platform build libraries under **Linux build dependencies** below before `cargo test` / `cargo build`.
19
20**Interactive shells:** the build scripts detect missing requirements (Rust, apt/pacman packages, `cargo-deb`, `base-devel`) and ask whether to install them automatically. Non-interactive runs (CI/pipes) never prompt; they print install instructions and exit.
21
22## Windows
23
24```powershell
25.\scripts\build-windows.ps1
26```
27
28Output: `target\release\posprint.exe`
29
30If `cargo`/`rustc` are missing and the shell is interactive, the script offers to install Rust via **winget** (`Rustlang.Rustup`) or **rustup-init**.
31
32Options:
33
34```powershell
35.\scripts\build-windows.ps1 -SkipTests
36```
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
50## Linux
51
52```bash
53chmod +x scripts/build-linux.sh
54./scripts/build-linux.sh # release binary
55./scripts/build-linux.sh --deb # binary + .deb (prompts to install if interactive)
56./scripts/build-linux.sh --deb --install # build .deb and install with apt
57```
58
59On a TTY, missing **apt** build packages and (with `--deb`) **cargo-deb** are offered for install before building.
60
61On **Arch Linux**:
62
63```bash
64chmod +x scripts/build-arch.sh
65./scripts/build-arch.sh # .pkg.tar.zst (prompts to install if interactive)
66./scripts/build-arch.sh --install # build and install with pacman
67```
68
69On a TTY, missing **base-devel**, Rust, and common pacman build libs are offered for install before building.
70
71`build-arch.sh` accepts a **rustup** toolchain on `PATH`. If the pacman `rust`/`cargo` packages are not installed, it runs `makepkg --nodeps` after verifying `rustc`/`cargo` work (the PKGBUILD still lists those packages for AUR/CI).
72
73After a successful package build, both scripts ask whether to install (TTY only). Pass `--install` to skip the prompt and install automatically. Non-interactive runs (CI/pipes) never prompt.
74
75Outputs:
76
77| Artifact | Path |
78|----------|------|
79| Binary | `target/release/posprint` |
80| Debian package | `target/debian/posprint_<ver>-1_amd64.deb` (`cargo-deb` revision defaults to `1`) |
81| Arch package | `packaging/arch/posprint-<ver>-1-x86_64.pkg.tar.zst` (hyphens; not `posprint_<ver>`) |
82| AUR bin tarball | `dist/posprint-<ver>-x86_64.tar.gz` (packed from the non-debug Arch package) |
83
84### Linux targets we support
85
86| Format | Distros | Notes |
87|--------|---------|-------|
88| **`.deb`** | Debian, Ubuntu, Mint, Pop!_OS, etc. | **Recommended** for apt-based systems; produced by `cargo-deb` |
89| **`.pkg.tar.zst`** | Arch Linux, Manjaro, EndeavourOS, etc. | **Recommended** for pacman; `sudo pacman -U posprint-*.pkg.tar.zst` |
90| **Raw binary** | Any x86_64 Linux | Copy `target/release/posprint`; needs X11/Wayland libs at runtime |
91| **`.rpm`** | Fedora, RHEL, openSUSE | Not automated yet; build binary and wrap with `fpm` if needed |
92| **AppImage** | Universal | Not automated yet; good for portable distribution |
93
94**Architecture:** `x86_64` (amd64) only in CI and build scripts today.
95
96### Linux build dependencies (Debian/Ubuntu)
97
98```bash
99sudo apt-get install -y build-essential pkg-config \
100 libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev libxkbcommon-dev \
101 libssl-dev libudev-dev
102```
103
104For `.deb`:
105
106```bash
107cargo install cargo-deb --locked
108```
109
110### Arch Linux build dependencies
111
112```bash
113sudo pacman -S --needed base-devel rust pkgconf openssl libxkbcommon libxcb dbus \
114 wayland libx11 fontconfig freetype2 libglvnd git rsync
115```
116
117### AUR publishing
118
119Normal local Arch packaging uses `packaging/arch/PKGBUILD`.
120
121Automated AUR publishing uses:
122
123- `packaging/aur/PKGBUILD` — source package (`posprint`)
124- `packaging/aur-bin/PKGBUILD` — binary package (`posprint-bin`)
125- `scripts/publish-aur.sh` — updates both AUR repos on tags (uses the local `dist/` tarball from `build:linux-arch`)
126- `scripts/make-linux-bin-tarball.sh` — packs `usr/` from the **non-debug** Arch CI `.pkg.tar.zst`
127- `scripts/publish-gitlab-release.sh` — uploads real `dist/` filenames to the Generic Package Registry and attaches them to the GitLab Release
128
129The source package builds from the GitLab tag tarball. The binary package installs a prebuilt tree from the Generic Package Registry (not `jobs/artifacts/<tag>` permalinks).
130
131Tag pipelines also keep job artifacts for a year, but **Release / Package Registry URLs are the ones that stay downloadable** if a later job fails.
132
133Setup and required GitLab secrets are documented in [AUR.md](AUR.md). To refresh an already-shipped tag (for example 0.5.7), delete and recreate that tag on a commit that contains the current `.gitlab-ci.yml` — see [AUR.md](AUR.md#refreshing-tag-057-or-any-already-pushed-tag).
134
135### File association (`.pos` → posprint)
136
137The package installs:
138
139- `/usr/share/mime/packages/posprint.xml` → MIME type `application/x-posprint` for `*.pos`
140- `/usr/share/applications/posprint.desktop` → claims that MIME type
141
142After `pacman -U`, pacman hooks refresh the MIME and desktop databases. To make posprint the **default** opener (double-click):
143
144```bash
145xdg-mime default posprint.desktop application/x-posprint
146xdg-mime query filetype some.pos # expect: application/x-posprint
147xdg-mime query default application/x-posprint # expect: posprint.desktop
148```
149
150If `query filetype` still says `text/plain`, the MIME package was not installed or the cache is stale:
151
152```bash
153sudo update-mime-database /usr/share/mime
154sudo update-desktop-database /usr/share/applications
155```
156
157## Tests before release
158
159```bash
160cargo test --release
161```