[PR #7019] [CLOSED] docs(ghidra): explain buildNatives for macOS and Linux arm64 hosts #7580

Closed
opened 2026-11-03 13:38:51 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7019
Author: @danieljustus
Created: 10/24/2026
Status: ❌ Closed

Base: main ← Head: docs/macos-ghidra-buildnatives


📝 Commits (1)

  • ef7f745 docs(ghidra): explain buildNatives for macOS and Linux arm64 hosts

📊 Changes

3 files changed (+59 additions, -3 deletions)

View changed files

📝 docs/installation.md (+5 -2)
📝 src/ghidra/GhidraInstallation.test.ts (+40 -0)
📝 src/ghidra/GhidraInstallation.ts (+14 -1)

📄 Description

Summary

Fixes #7018. On macOS the official Ghidra release archive has no native decompiler, but the installation docs only mention Linux ARM64 needing a user-built native component, and the native_decompiler doctor remediation names the expected path without saying how to produce it. This PR documents Ghidra's own buildNatives step for macOS and Linux ARM64 and adds that command to the remediation on those hosts.

Problem and expected behavior

Trigger: GHIDRA_INSTALL_DIR points at an unzipped official 12.1.4 archive on macOS arm64. rea providers --json reports native_decompiler failed with "Matching native decompiler for darwin/arm64 was not found" and a remediation that only names os/mac_arm_64/decompile. Expected: the docs and the remediation tell the user to run support/gradle/gradlew buildNatives, whose output (build/os/<platform>/) REA already accepts.

Change and scope

  • docs/installation.md: state that official archives include natives only for Windows and Linux x86-64; macOS (mac_arm_64/mac_x86_64) and Linux ARM64 build them once with support/gradle/gradlew buildNatives (or gradle buildNatives), output in build/os/<platform>/.
  • src/ghidra/GhidraInstallation.ts: userBuiltNativeHint(platform, architecture) appends that sentence to the missing-decompiler remediation for darwin and linux/arm64 only. The admission logic, paths and the "REA does not build or install native tools" sentence are unchanged.
  • Not included: accepting Ghidra 12.2 (tracked in #6921) or any automatic build.

Follow the contribution scope.
Maintainer scope decision: not applicable (documentation and remediation text within existing boundaries).

Contract and boundary impact

  • Semantic owner and earliest changed stage: nativeDecompilerCheck remediation string in src/ghidra/GhidraInstallation.ts.
  • Contribution scope fit and linked maintainer decision: documentation/usability fix, not applicable.
  • CLI and MCP/tool-catalog contract: unchanged; only the remediation text of a failed native_decompiler check changes on macOS and Linux arm64.
  • Provider, bridge, target-format, or platform compatibility: unchanged.
  • Evidence, artifact, provenance, or reconstruction contract: none.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: src/ghidra/GhidraInstallation.test.ts, "Ghidra missing native decompiler remediation": darwin/arm64, darwin/x64 and linux/arm64 must name gradlew buildNatives; linux/x64 must not.
  • Base reproduction or other evidence: with only the test applied (source change stashed) the three hint cases fail (Tests 3 failed | 111 passed (114)); with the change all 114 pass. Real-host observation: official ghidra_12.1.4_PUBLIC_20260921.zip (SHA-256 ddac49f9…d2d4db) on macOS 27.0.1 arm64 contains only os/linux_x86_64 and os/win_x86_64; after support/gradle/gradlew --no-daemon buildNatives (JDK 25, Apple clang, BUILD SUCCESSFUL in 28 s) rea providers --json reports Ghidra available with native_decompiler ... build/os/mac_arm_64/decompile reports mach-o arm64, which matches darwin/arm64. Source for the release contents: Ghidra 12.1.4 docs/GettingStarted.md, "Building Native Components".
  • User-visible CLI/MCP output (if applicable): new remediation on macOS arm64: Provide an executable Ghidra/Features/Decompiler/os/mac_arm_64/decompile, or its build/os equivalent. Official Ghidra release archives include native binaries only for Windows and Linux x86-64; build them once with support/gradle/gradlew buildNatives in the Ghidra installation. REA does not build or install native tools. (derived from the source change; covered by the unit test, not re-captured from a live doctor run).
  • Remaining proof gaps: no live run on macOS x64 or Linux arm64 hosts; Windows ARM64 unchanged.

Validation performed

  • npx vitest run src/ghidra/GhidraInstallation.test.ts — 114 passed.
  • Same with the source change stashed — 3 failed (the new hint cases), 111 passed.
  • npx tsc --noEmit -p tsconfig.json — no errors.
  • npx oxfmt --check on the three changed files — all formatted.
  • npx oxlint src/ghidra/GhidraInstallation.ts — 8 warnings, identical count to the base revision (pre-existing complexity/length warnings).
  • npm run docs:check — passed (readmeConsistency 9/9).
  • Not run: full npm run check:pr (Node 22.22.3 locally, below the engines floor; ran with --engine-strict=false).

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: real Ghidra 12.1.4 on macOS 27.0.1 arm64 for the build step and provider admission; unit coverage for the remediation text.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: none; text only, REA still never builds or installs tools.

Author readiness

Human owner: @danieljustus

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/7019 **Author:** [@danieljustus](https://github.com/danieljustus) **Created:** 10/24/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/macos-ghidra-buildnatives` --- ### 📝 Commits (1) - [`ef7f745`](https://github.com/morluto/rea/commit/ef7f7455d79fa7063bb1a3b4d215334c14e1532a) docs(ghidra): explain buildNatives for macOS and Linux arm64 hosts ### 📊 Changes **3 files changed** (+59 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `docs/installation.md` (+5 -2) 📝 `src/ghidra/GhidraInstallation.test.ts` (+40 -0) 📝 `src/ghidra/GhidraInstallation.ts` (+14 -1) </details> ### 📄 Description ## Summary Fixes #7018. On macOS the official Ghidra release archive has no native decompiler, but the installation docs only mention Linux ARM64 needing a user-built native component, and the `native_decompiler` doctor remediation names the expected path without saying how to produce it. This PR documents Ghidra's own `buildNatives` step for macOS and Linux ARM64 and adds that command to the remediation on those hosts. ## Problem and expected behavior Trigger: `GHIDRA_INSTALL_DIR` points at an unzipped official 12.1.4 archive on macOS arm64. `rea providers --json` reports `native_decompiler` failed with "Matching native decompiler for darwin/arm64 was not found" and a remediation that only names `os/mac_arm_64/decompile`. Expected: the docs and the remediation tell the user to run `support/gradle/gradlew buildNatives`, whose output (`build/os/<platform>/`) REA already accepts. ## Change and scope - `docs/installation.md`: state that official archives include natives only for Windows and Linux x86-64; macOS (`mac_arm_64`/`mac_x86_64`) and Linux ARM64 build them once with `support/gradle/gradlew buildNatives` (or `gradle buildNatives`), output in `build/os/<platform>/`. - `src/ghidra/GhidraInstallation.ts`: `userBuiltNativeHint(platform, architecture)` appends that sentence to the missing-decompiler remediation for `darwin` and `linux/arm64` only. The admission logic, paths and the "REA does not build or install native tools" sentence are unchanged. - Not included: accepting Ghidra 12.2 (tracked in #6921) or any automatic build. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Maintainer scope decision: not applicable (documentation and remediation text within existing boundaries). ## Contract and boundary impact - Semantic owner and earliest changed stage: `nativeDecompilerCheck` remediation string in `src/ghidra/GhidraInstallation.ts`. - Contribution scope fit and linked maintainer decision: documentation/usability fix, not applicable. - CLI and MCP/tool-catalog contract: unchanged; only the `remediation` text of a failed `native_decompiler` check changes on macOS and Linux arm64. - Provider, bridge, target-format, or platform compatibility: unchanged. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. Expected effects: - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `src/ghidra/GhidraInstallation.test.ts`, "Ghidra missing native decompiler remediation": darwin/arm64, darwin/x64 and linux/arm64 must name `gradlew buildNatives`; linux/x64 must not. - Base reproduction or other evidence: with only the test applied (source change stashed) the three hint cases fail (`Tests 3 failed | 111 passed (114)`); with the change all 114 pass. Real-host observation: official `ghidra_12.1.4_PUBLIC_20260921.zip` (SHA-256 `ddac49f9…d2d4db`) on macOS 27.0.1 arm64 contains only `os/linux_x86_64` and `os/win_x86_64`; after `support/gradle/gradlew --no-daemon buildNatives` (JDK 25, Apple clang, BUILD SUCCESSFUL in 28 s) `rea providers --json` reports Ghidra `available` with `native_decompiler ... build/os/mac_arm_64/decompile reports mach-o arm64, which matches darwin/arm64`. Source for the release contents: Ghidra 12.1.4 `docs/GettingStarted.md`, "Building Native Components". - User-visible CLI/MCP output (if applicable): new remediation on macOS arm64: `Provide an executable Ghidra/Features/Decompiler/os/mac_arm_64/decompile, or its build/os equivalent. Official Ghidra release archives include native binaries only for Windows and Linux x86-64; build them once with support/gradle/gradlew buildNatives in the Ghidra installation. REA does not build or install native tools.` (derived from the source change; covered by the unit test, not re-captured from a live doctor run). - Remaining proof gaps: no live run on macOS x64 or Linux arm64 hosts; Windows ARM64 unchanged. ## Validation performed - `npx vitest run src/ghidra/GhidraInstallation.test.ts` — 114 passed. - Same with the source change stashed — 3 failed (the new hint cases), 111 passed. - `npx tsc --noEmit -p tsconfig.json` — no errors. - `npx oxfmt --check` on the three changed files — all formatted. - `npx oxlint src/ghidra/GhidraInstallation.ts` — 8 warnings, identical count to the base revision (pre-existing complexity/length warnings). - `npm run docs:check` — passed (readmeConsistency 9/9). - Not run: full `npm run check:pr` (Node 22.22.3 locally, below the engines floor; ran with `--engine-strict=false`). ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: real Ghidra 12.1.4 on macOS 27.0.1 arm64 for the build step and provider admission; unit coverage for the remediation text. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none; text only, REA still never builds or installs tools. ## Author readiness Human owner: @danieljustus - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-03 13:38:51 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#7580
No description provided.