0073 — The v3 migration guide and the tutorial pages miss what porting fhsim_tutorial and fhsim_maritime needed

ID	0073
Class	DOCUMENTATION
Severity	2
Status	ready

Models: —

Found: 2026-10-22, porting fhsim_tutorial 1.4.0 to fhsim 3.4.0 (fhsim_tutorial branch feature/recycle, commits fc44c00..64cda7c)

Evidence

Each item was hit while porting; items 4–6 were checked against the pages at HEAD.

1. doc/user/migration-v3.md does not cover the test tools: fhSimTestTools/TestSetup.h, testTools::SetUpTest, testTools::RmsComparison and _exp.txt became <fhsim/testtools/FhsimTest.h>, RunTest/CompareRegression, .ref + _ref.csv, and a test main must define GetTestRuntimeConfig(). fh_add_gtest_tests is not mentioned; step 6 covers only the target rename.
2. The XML section does not map the v2 <Engine> attributes TOutput, FileOutput, NumCores, LogStates, UseRSSNormInsteadOfInfNorm. v2 TOutput was "TStart, schedule, TEnd"; v3 <FileOutput TOutput> reads a comma list as explicit times, so a pasted v2 string gives extra rows. scripts/migrate_to_v3.py writes LogStates and UseRSSNorm on <Integrator> (ignored with a warning), leaves FileOutput as a TODO comment and drops the output schedule.
3. Step 3 says SimObject.h, SimObjectInclude.h, ISimObjectCreator.h and others are unchanged. They are installed under include/fhsim/simobject/, and the include dirs are include and include/fhsim, so #include "SimObject.h" should not resolve (inferred from the include dirs, not tried).
4. "What the script does NOT handle" (migration-v3.md:692) numbers item 3 twice.
5. doc/user/cheat_sheet.md:46 shows TOutput="0.1" as an output interval; the parser reads one number as one explicit time.
6. doc/user/tutorials/simobjects_fhsimtutorial.md still uses m_SimObjectName in the CMass RenderInit code; doc/user/tutorials/compiling_tutorial_project.md:46 says the tutorial XML files are in input/, they are in examples/input/.
7. A Select of objects:state.<Name> is rejected with "a signal can only be named for a single object"; the guide does not say so.

Found porting fhsim_maritime 2.0.0 (branch feature/recycle, 2bcf695..68fd427):

1. The "CFhVis" shared resource is gone; the guide does not say what replaces it (kSimMgrKeyFhVisualization, see FHSIM-0075).
2. The rename tables miss CInputManager → InputManager (<fhsim/visual/renderer/InputManager.h>), and the string key "CPrintDuringExec" → kSimMgrKeyPrinter (string literals are not renamed by the script; the guide says so for CFhCamera only).
3. Port functions stay non-const, so a const OdeFcn that calls its own output-port functions needs a const_cast or a restructure. Not mentioned.
4. Output is written at t0 before any OdeFcn call, so a port that returns a value OdeFcn caches gives NaN or an uninitialised value in the first row (fhsim_maritime CIEngine). Not mentioned.
5. Step 7 suggests FhSim::fhsim_vis for plugins; it is a static library that pulls in the engine, so a plugin that links it gets a second copy of singletons such as InputManager::getSingletonPtr().
6. The TinyXML section maps to raw libxml2 but not to the recommended fhsim::xml::XmlDoc (FromFile, Root, FirstChildElement, ChildElements, Attribute).
7. The <Engine> mapping also misses InitialStatesFile/FinalStatesFile (they stay on <Integrator>) and the v2 spelling Stepsize.
8. There is no note for fhsim_environment 2 → 3 (include root <fhsim_environment/...>, transitive_headers), which every library on environment 2 needs.

Effect

Every SimObject library still on fhsim 2 (fhsim_bio, fhsim_aquaculture, fhsim_aquarobotics) will hit the same gaps.

Possible fix

Add the test-tools and <Engine> mappings to the guide, correct step 3, the numbering, the cheat sheet and the two tutorial pages; make migrate_to_v3.py write a <FileOutput> with the schedule and drop the two ignored attributes.

Test that would prove it

Port fhsim_maritime with only the guide; nothing outside it should be needed.

Risk

None to results.