Skip to content

Add a runnable verification step to the C Setup Guide - #6711

Open
meshinspector-agent[bot] wants to merge 3 commits into
masterfrom
agent/mlib-c-setup-guide-verify-step
Open

Add a runnable verification step to the C Setup Guide#6711
meshinspector-agent[bot] wants to merge 3 commits into
masterfrom
agent/mlib-c-setup-guide-verify-step

Conversation

@meshinspector-agent

@meshinspector-agent meshinspector-agent Bot commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

The C Setup Guide's only success check told the reader to run the MeshLoadSave sample, which hardcodes mesh.stl — so on a correct install it exits 1 with Cannot open file for reading mesh.stl, and the message says nothing about the setup being fine. Reproduced on Linux, Windows and macOS.

What changed

  • CSetupGuide.dox — new Verify the installation section: rationale, \include MeshExport.dox.c, per-platform build+run, the literal expected output, and "anything else means it is not working". Modeled on the Python guide's section (Add a verification step and Troubleshooting to Python Setup Guide #6707). It reuses the existing MeshExport sample rather than adding a program: that sample already builds a cube with MR_makeCube, needs no input file and prints a deterministic result, so the page and CI cannot drift from code only the page has.
  • MeshExport.dox.c — one-word fix: the face loop ran to verticesNum (8) though the cube has 12 faces, so the sample silently printed two thirds of them. The output printed on the page depends on this being right; it is a bug in a shipped example either way.
  • test-distribution.yml / build-test-macos.yml — run MeshExport next to MeshModification in every "Build C examples" step. That makes "works on all three platforms" a standing CI fact about the distributed artifact rather than a claim on a page. (The Windows step also gained the missing $LASTEXITCODE check, without which MeshModification failing was silently ignored.)
  • MeshLoadSave.dox.c — keeps both of its purposes and gains optional arguments: input argv[1] (default mesh.stl), output argv[2] (default mesh.ply). Bare runs behave exactly as before, plus a usage line when the default load fails. Follows the argv idiom in MeshFromText.dox.c; the goto cleanup is untouched.
  • MeshLoadSave.dox — the note now documents the defaults and the C version's arguments. Shared page, so the C++/Python/JS/C# guides get it too.

Also fixes two things the guide got wrong on Linux/macOS: MeshLib::MeshLibC2 does not carry the header path, so the documented CMake snippet stopped at fatal error: MRCMesh/MRCube.h: No such file or directorytarget_include_directories(... ${MESHLIB_INCLUDE_DIR}) added to both. The macOS @rpath/libMeshLibC2.dylib launch failure is noted version-scoped (v3.1.3.429 and earlier) with its DYLD_LIBRARY_PATH workaround, so the note retires itself — the fix is merged but the newest published release still has the bug.

Verification

Built and run here against the real published meshlib_v3.1.3.429_ubuntu22-dev.deb, gcc 11.4, -Wall -Wextra — 0 warnings.

  • The guide's standalone find_package(MeshLib CONFIG REQUIRED) recipe builds verbatim as printed on the page, including the new target_include_directories line.
  • MeshExport → exit 0, and its stdout is byte-for-byte identical to the Expected output block on the page (diffed mechanically, not transcribed by eye): 8 vertex lines + 12 face lines.
  • The face-loop fix is load-bearing: the same binary before it prints face 0face 7 and stops — 8 of 12.
  • MeshLoadSave, all argument states: no args + no mesh.stl → same message as today plus the usage line, exit 1 · no args + mesh.stl present → exit 0, writes mesh.ply (unchanged default behaviour) · in.stl → exit 0 · in.stl out.ply → exit 0, writes out.ply · bad path argument → error with no spurious usage hint.

Not verified here: Windows and macOS — that is what the CI additions in this PR are for, and why it carries full-ci. Page rendering is not checkable in this repo (the Doxyfile lives in MeshInspector.github.io); \include MeshExport.dox.c resolves through the same EXAMPLE_PATH mechanism ExampleMeshExport already uses, and update_doc.sh runs with CHECK_WARNINGS=true so a bad path fails loudly. No runtime or UI surface, so nothing to drive over MCP and nothing to screenshot.

CI

full-ci — deliberate, not the default: test-distribution only runs when upload_artifacts == true, so without it the very steps this PR edits never execute and the macOS/Windows legs go unproven.

The guide's only success check pointed at the MeshLoadSave sample, which
hardcodes mesh.stl and therefore fails on a correct installation. Add a
self-contained cube program that needs no input data and prints a fixed line,
as a real C example so distribution CI compiles and runs it on Linux, macOS
and Windows -- the page and the tested code cannot drift apart -- and build
the guide's verification section around it.

MeshLoadSave keeps both of its purposes and gains optional input/output path
arguments, so it stays usable on a mesh the reader already has.
@meshinspector-agent meshinspector-agent Bot added the full-ci run all steps label Aug 27, 2026
…sample

VerifyInstall was a second copy of MeshExport: both build a cube with
MR_makeCube, need no input file and print a deterministic result. Drop it
and point the guide and the distribution CI at the sample that already
exists, so the page and CI cannot drift from a program only the page has.

MeshExport's face loop ran to verticesNum (8) while the cube has 12 faces,
so the sample silently printed two thirds of them; the output now printed
on the page depends on that being right.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

full-ci run all steps

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants