This document describes how to migrate a FhSim SimObject plugin project from fhsim 2.x to fhsim 3.1.0. It was derived from the migration of fhsim_environment and can serve as a checklist for other projects.

1. Run the automated migration script

The fhsim repository ships a migration script that handles the bulk of mechanical changes automatically. Run it first, review its output, then apply:

# Dry run — shows what would change, no files modified
python3 /path/to/fhsim/scripts/migrate_to_v3.py /path/to/your/project
 
# Apply all changes
python3 /path/to/fhsim/scripts/migrate_to_v3.py /path/to/your/project --apply

The script handles:

File type	Change applied
`conanfile.py` / `conanfile.txt`	Version range updated to `fhsim/[^3.1.0]`
`CMakeLists.txt` / `.cmake`	`FhSim::fhsim` → `FhSim::simobject`; `FhSim::fhsim-testtools` → `FhSim::fhsim_testtools`
`.cpp` / `.h`	Header renames: `CPrintDuringExec.h`, `CFhSimMgr.h`, `CExceptions.h`, `CAttributePath.h`, `CInputReader.h` and the corresponding class names
`*.xml`	`<INTEGRATION>` / `</INTEGRATION>` → `<SIMULATION>` / `</SIMULATION>`; `jtype=` → `jac_type=`

‍Note: The script targets FhSim::fhsim (capital F) in CMake files. Lowercase fhsim::fhsim (Conan CMakeDeps alias used in some older files) is not transformed — fix these manually (see step 3 below).

2. Update the fhsim version in conanfile.py

The script converts exact version numbers but may miss version-range syntax. Verify the requirements() function uses the new coordinates:

# Old (v2)
self.requires("fhsim/[^2.12.0]@sintef/stable", ...)
 
# New (v3)
self.requires("fhsim/[^3.1.0]@sintef/stable", ...)

3. Fix remaining lowercase fhsim::fhsim CMake targets

If any CMakeLists.txt still references fhsim::fhsim (all-lowercase), replace with FhSim::simobject:

# Old
target_link_libraries(${TARGET} PUBLIC fhsim::fhsim)
 
# New
target_link_libraries(${TARGET} PUBLIC FhSim::simobject)

4. Add FhSim::fhsim_vis link for visualization code

In v3, the CMake target FhSim::fhsim has been split. Visualization headers (FhCamera.h, FhVisualization.h, etc.) are now provided by a separate FhSim::fhsim_vis component. Any library that compiles visualization source files must link this target:

# In the CMakeLists.txt that builds your SimObject library
if(FHSIM_FH_VISUALIZATION)
   target_link_libraries(${TARGET} PUBLIC FhSim::fhsim_vis)
endif()

FHSIM_FH_VISUALIZATION is set automatically by fhsim's fhsim-variables.cmake build module when fhsim was built with with_visualization=True.

5. Update visualization header includes

The v3 visualization headers are installed under include/fhsim/visual/renderer/ and must be included with the full fhsim/ prefix:

Old include	New include
`#include <CFhCamera.h>`	`#include <fhsim/visual/renderer/FhCamera.h>`
`#include <CFhCameraController.h>`	`#include <fhsim/visual/renderer/FhCameraController.h>`

The CFhCamera class was also renamed to FhCamera. Update all declarations, definitions, and casts accordingly.

The shared-resource key used by GetSharedResource / SetPtr changed too:

// Old
auto cam = (CFhCamera*)creator->GetSharedResource("CFhCamera");
 
// New
auto cam = (FhCamera*)creator->GetSharedResource("FhCamera");

6. Qualify string as std::string

The old ISimObjectCreator.h contained using std::string; at file scope, allowing unqualified string throughout downstream code. v3 removed this using declaration.

In headers — replace string with std::string:

// Old
MySimObject(string name, ISimObjectCreator* creator);
 
// New
MySimObject(std::string name, ISimObjectCreator* creator);

In .cpp files — add a using declaration after includes (or qualify std::string at usage sites):

#include "MySimObject.h"

using std::string; // add this

7. Rename m_SimObjectName → m_simObjectName

The SimObject base class member that holds the registered object name was renamed from m_SimObjectName (capital S) to m_simObjectName (lowercase s). Search and replace in all source files that access this member directly:

grep -rn 'm_SimObjectName' src/ tests/

8. Rename dllLib.h → DllLib.h

The utility header used by the SimObject DLL entry point was renamed:

// Old
#include <dllLib.h>
 
// New
#include <fhsim/DllLib.h>

9. Build and verify

# Clean build with conan create (commits required — repo must be clean)
git add -A && git commit -m "chore: migrate to fhsim 3.1.0"
 
conan create . -s build_type=Release --build=missing

If additional errors appear, check the error message against the categories in steps 4–8 above. The compiler error messages are usually descriptive enough to identify the root cause.

Summary checklist

[ ] Run migrate_to_v3.py --apply
[ ] Update conanfile.py version to fhsim/[^3.1.0]@sintef/stable
[ ] Replace lowercase fhsim::fhsim CMake targets → FhSim::simobject
[ ] Add FhSim::fhsim_vis link guard in visualization CMakeLists
[ ] Change #include <CFhCamera.h> → #include <fhsim/visual/renderer/FhCamera.h>; update class/cast names
[ ] Update GetSharedResource("CFhCamera") → GetSharedResource("FhCamera")
[ ] Qualify string → std::string in headers; add using std::string; in .cpp files
[ ] Rename m_SimObjectName → m_simObjectName
[ ] Rename #include <dllLib.h> → #include <fhsim/DllLib.h>
[ ] conan create passes cleanly