Add a runnable verification step to the C Setup Guide - #6711
Open
meshinspector-agent[bot] wants to merge 3 commits into
Open
Add a runnable verification step to the C Setup Guide#6711meshinspector-agent[bot] wants to merge 3 commits into
meshinspector-agent[bot] wants to merge 3 commits into
Conversation
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.
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The C Setup Guide's only success check told the reader to run the
MeshLoadSavesample, which hardcodesmesh.stl— so on a correct install it exits 1 withCannot 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— newVerify the installationsection: 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 existingMeshExportsample rather than adding a program: that sample already builds a cube withMR_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 toverticesNum(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— runMeshExportnext toMeshModificationin 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$LASTEXITCODEcheck, without whichMeshModificationfailing was silently ignored.)MeshLoadSave.dox.c— keeps both of its purposes and gains optional arguments: inputargv[1](defaultmesh.stl), outputargv[2](defaultmesh.ply). Bare runs behave exactly as before, plus a usage line when the default load fails. Follows the argv idiom inMeshFromText.dox.c; thegotocleanup 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::MeshLibC2does not carry the header path, so the documented CMake snippet stopped atfatal error: MRCMesh/MRCube.h: No such file or directory—target_include_directories(... ${MESHLIB_INCLUDE_DIR})added to both. The macOS@rpath/libMeshLibC2.dyliblaunch failure is noted version-scoped (v3.1.3.429 and earlier) with itsDYLD_LIBRARY_PATHworkaround, 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.find_package(MeshLib CONFIG REQUIRED)recipe builds verbatim as printed on the page, including the newtarget_include_directoriesline.MeshExport→ exit 0, and its stdout is byte-for-byte identical to theExpected outputblock on the page (diffed mechanically, not transcribed by eye): 8 vertex lines + 12 face lines.face 0…face 7and stops — 8 of 12.MeshLoadSave, all argument states: no args + nomesh.stl→ same message as today plus the usage line, exit 1 · no args +mesh.stlpresent → exit 0, writesmesh.ply(unchanged default behaviour) ·in.stl→ exit 0 ·in.stl out.ply→ exit 0, writesout.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 inMeshInspector.github.io);\include MeshExport.dox.cresolves through the sameEXAMPLE_PATHmechanismExampleMeshExportalready uses, andupdate_doc.shruns withCHECK_WARNINGS=trueso 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-distributiononly runs whenupload_artifacts == true, so without it the very steps this PR edits never execute and the macOS/Windows legs go unproven.