Skip to content

docs: rewrite plugin install/troubleshooting guide#6079

Open
DmitryLambin wants to merge 1 commit into
masterfrom
doc-plugin-cross-platform-and-troubleshooting
Open

docs: rewrite plugin install/troubleshooting guide#6079
DmitryLambin wants to merge 1 commit into
masterfrom
doc-plugin-cross-platform-and-troubleshooting

Conversation

@DmitryLambin
Copy link
Copy Markdown
Contributor

Closes #6078.

Summary

Rewrites the two plugin documentation pages that new users land on when adding a plugin to MeshLib or MeshInspector:

What's new

HowtoAddPluginOverview.dox

  • Trust & safety section. Plugins are native code loaded into the host process with full user privileges; the prior text told users to sudo cp arbitrary .dylib files into /Applications/MeshInspector.app without a single word about source verification.
  • Per-platform install sections at parity. Previously only Windows had concrete steps; macOS was missing entirely and Linux was implicit.
  • macOS App Bundle Protection explained, with the user-writable clone (recommended) and sudo-into-/Applications/... (advanced) presented in that order. The sudo path now carries an explicit warning about breaking the bundle's code signature and what to do if Gatekeeper blocks the next launch (codesign --force --sign -).
  • dyld / RPATH / SONAME troubleshooting. CMake INSTALL_RPATH + BUILD_WITH_INSTALL_RPATH ON with rationale, otool -L audit, install_name_tool -change workflow with explicit "read your own deps first" guidance (so users do not blindly paste example versions), libcpr.1.dylib symlink case.
  • Verifying the install with concrete log paths per platform and a matrix of common failure modes mapped to fixes.
  • Uninstall section.
  • Windows: clarified "Run as administrator", added CRT debug/release mismatch and Windows Defender / SmartScreen notes.
  • Linux: dpkg -L meshinspector hint so users on tarball / AppImage / from-source can find their own paths.
  • "What a plugin distribution looks like" so users receiving a precompiled plugin from a third party have a starting point — previously the docs assumed "I just built it".
  • Reformatted the Version Compatibility section (the previous nested bullets did not render).

ExamplePluginOverview.dox

  • Added Linux and macOS Usage sections with CMake invocations against MeshLib.framework / MeshLib_DIR, plus an otool -L verification step.
  • macOS deploy step now recommends the cloned-folder approach; the system-wide install is referenced to HowtoAddPluginOverview rather than duplicated, to keep the code-signature warning in one place.
  • "After install — quick sanity check" with the per-platform log paths.

Test plan

  • Doxygen build of the docs renders without warnings on the new sections (specifically the \warning / \note blocks and \section anchors used for cross-references).
  • Visual check at https://meshinspector.github.io/MeshLib/dev/html/HowtoAddPluginOverview.html after CI publish — TOC shows the new sections, code blocks render with correct syntax highlighting, cross-references between the two pages resolve.
  • Spot-check that no \ref anchors point at sections I renamed (only HowtoAddPluginOverview_VersionCompatibility was added; cross-page references kept).

I have not changed code or build logic, so existing CI should pass unchanged.

Closes #6078.

Reworks two pages that new users hit when adding a plugin:

* HowtoAddPluginOverview.dox
  - new "Trust & safety" section (plugins run with full process privileges)
  - macOS / Linux deployment sections to match the existing Windows one
  - macOS recommends user-writable clone first; sudo-into-/Applications
    documented as advanced with explicit warning about code-signature damage
  - dyld/RPATH/SONAME troubleshooting (otool -L workflow, install_name_tool,
    libcpr.1.dylib symlink case) with the rationale for BUILD_WITH_INSTALL_RPATH
  - "Verifying the install" with concrete log paths per platform and
    common failure modes
  - new "Uninstall" section
  - Windows: clarified "Run as administrator", added CRT mismatch and
    Defender/SmartScreen notes
  - Linux: dpkg -L hint for non-.deb installs
  - reformatted the Version Compatibility section
  - explicit "What a plugin distribution looks like" so users who receive
    a precompiled plugin from a third party also have a starting point

* ExamplePluginOverview.dox
  - Linux and macOS Usage sections with CMake invocations against the
    installed SDK / Frameworks/MeshLib.framework, otool -L verification step
  - macOS deploy now recommends the cloned-folder approach; system-wide
    install delegated to HowtoAddPluginOverview to avoid duplicating the
    code-signature warning
  - "After install — quick sanity check" log paths
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.

Plugin install docs: missing macOS/Linux details, no troubleshooting, no security guidance

1 participant