Skip to content

macosx: add relocatable private runtime packaging - #1411

Closed
Dvorf wants to merge 1 commit into
mobile-shell:masterfrom
Dvorf:fix/macos-private-runtime
Closed

Dvorf wants to merge 1 commit into
mobile-shell:masterfrom
Dvorf:fix/macos-private-runtime

Conversation

@Dvorf

@Dvorf Dvorf commented Sep 6, 2026

Copy link
Copy Markdown

Problem and resulting behavior

A native macOS Mosh build can stop launching after a Homebrew upgrade removes a versioned Protobuf or Abseil dynamic library against which it was linked. Changing PATH or unlinking Homebrew's Mosh formula does not repair those missing runtime dependencies.

This PR adds an optional packaging helper that takes an already compiled Mosh build and creates a relocatable directory containing the client, server, launcher, and private copies of their Homebrew runtime libraries. The packaged launcher explicitly selects its sibling client, so another mosh-client on PATH cannot silently replace it.

Implementation

  • Discover the Homebrew prefix with brew --prefix, with an explicit --brew-prefix override. There are no hard-coded user directories, hostnames, network addresses, Homebrew versions, or CPU architecture selections.
  • Traverse the Mach-O dependency graph, including supported @rpath and @loader_path dependencies. Rewrite bundled references to loader-relative paths and remove absolute Homebrew runtime search paths. Apple system libraries remain system dependencies.
  • Reject dependencies outside the selected Homebrew prefix, ambiguous runtime search paths, and library filename collisions rather than producing a silently incomplete bundle.
  • Copy dependency license notices and available terminfo data. Configure the packaged launcher to include its private terminfo database and write a manifest using paths relative to the Homebrew prefix.
  • Ad-hoc sign and verify modified binaries, verify the rewritten dependency graph, and check both executables with --version.
  • Refuse to overwrite an existing destination. Document partial-output handling, installation, reconnection, and dependency maintenance.

The documentation is linked from the main README, the new files are included in source distributions, and the macOS CI job runs the packaging tests and packages the real build.

Validation

Local validation was performed on macOS arm64:

  • Four packaging integration tests passed. A real, compiled transitive dylib graph is packaged, moved to a path containing spaces, and executed after the original library prefix is renamed away. The launcher is invoked through a symlink with a competing client on PATH. Tests also cover signature verification, license preservation, existing-destination protection, and rejection of external or ambiguous dependencies.
  • Five upstream tests passed: ocb-aes, encrypt-decrypt, base64, nonce-incr, and local.test.
  • The helper packaged a real build of current upstream Mosh; all 84 Mach-O files passed dependency/signature verification and both packaged executables started successfully.
  • Source-distribution contents and git diff --check were checked.

Intel macOS has not been tested locally; prefix and path handling are discovered rather than architecture-specific. The full tmux-dependent terminal test suite was not run locally.

Scope and maintenance

This is an optional helper for native macOS/Homebrew builds, not a universal-architecture installer or a cross-platform packaging system. It does not replace the existing macOS installer script, notarize artifacts, modify shell or Homebrew configuration, or change Mosh's terminal protocol and clipboard implementation.

Private dependencies intentionally survive Homebrew upgrades. Users must rebuild their bundles to incorporate dependency security fixes; this tradeoff is documented. No generated binaries, machine configuration, or local diagnostic logs are included in this PR.

@achernya

achernya commented Sep 6, 2026

Copy link
Copy Markdown
Collaborator

We do not support homebrew builds here. The official macos mosh PKG statically links protobuf for this reason. We also don't support "users built against the homebrew dependencies without using a homebrew packaged mosh".

We also are not accepting LLM contributions at this time.

@achernya achernya closed this Sep 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants