Shared-library integration: configuration mismatch is difficult to diagnose

[randomMesh]

When using Jolt as a shared library, it is quite difficult to determine the required preprocessor definitions for the consuming application.

I built Jolt as a shared library with:

JPH_BUILD_SHARED_LIBS=ON
CMAKE_BUILD_TYPE=Release

The generated Jolt library had these relevant defines:

JPH_SHARED_LIBRARY
JPH_DEBUG_RENDERER
JPH_OBJECT_LAYER_BITS=16
JPH_OBJECT_STREAM
JPH_PROFILE_ENABLED
JPH_USE_CPU_COMPUTE

My application initially compiled and linked against libJolt.so, but at runtime RegisterTypesInternal() aborted because the application's Jolt configuration did not match the library configuration.

Adding JPH_PROFILE_ENABLED to the application then resulted in:

undefined reference to JPH::ProfileThread::sInstance'`

The reason for that error was that the application also needed:

JPH_SHARED_LIBRARY

With both definitions present, everything worked:

JPH_SHARED_LIBRARY
JPH_PROFILE_ENABLED
JPH_DEBUG_RENDERER
JPH_OBJECT_LAYER_BITS=16
JPH_OBJECT_STREAM
JPH_USE_CPU_COMPUTE

The problem is that the intermediate errors don't make the required configuration particularly apparent. In particular:

• RegisterTypesInternal() eventually calls abort(), without clearly identifying which configuration differs.
• JPH_PROFILE_ENABLED alone produces a linker error because JPH_SHARED_LIBRARY is also required.
• The need for JPH_SHARED_LIBRARY when consuming the shared library isn't obvious from the linker error.
• The required application-side definitions have to be manually inferred from the Jolt build configuration.

Would it be possible to improve the documentation and/or diagnostics around shared-library integration?

For example, RegisterTypesInternal() could report the specific configuration flags that differ between the application and the library instead of simply aborting. The build documentation could also provide an explicit example of the preprocessor definitions required when consuming a CMake-built shared Jolt library.

This may be especially useful for users integrating Jolt into IDE-managed projects rather than consuming it directly through CMake's exported Jolt target.

[jrouwe]

Thanks for the feedback! I'm always trying to make things as clear as possible, but in this case I feel that the mechanisms I put in place should have triggered.

For example, RegisterTypesInternal() could report the specific configuration flags that differ between the application and the library instead of simply aborting. The build documentation could also provide an explicit example of the preprocessor definitions required when consuming a CMake-built shared Jolt library.

It does:

JoltPhysics/Jolt/RegisterTypes.cpp

Lines 81 to 93 in 439c2b6

	auto check_bit = [mismatch](int inBit, const char *inLabel) { if (mismatch & (uint64(1) << (inBit + 23))) Trace("Mismatching define %s.", inLabel); };
	check_bit(1, "JPH_DOUBLE_PRECISION");
	check_bit(2, "JPH_CROSS_PLATFORM_DETERMINISTIC");
	check_bit(3, "JPH_FLOATING_POINT_EXCEPTIONS_ENABLED");
	check_bit(4, "JPH_PROFILE_ENABLED");
	check_bit(5, "JPH_EXTERNAL_PROFILE");
	check_bit(6, "JPH_DEBUG_RENDERER");
	check_bit(7, "JPH_DISABLE_TEMP_ALLOCATOR");
	check_bit(8, "JPH_DISABLE_CUSTOM_ALLOCATOR");
	check_bit(9, "JPH_OBJECT_LAYER_BITS");
	check_bit(10, "JPH_ENABLE_ASSERTS");
	check_bit(11, "JPH_OBJECT_STREAM");
	std::abort();

If you didn't override Trace it should have triggered a breakpoint here to indicate you forgot to do it:

JoltPhysics/Jolt/Core/IssueReporting.cpp

Line 11 in 439c2b6

JPH_ASSERT(false);

If you override Trace it should log the bits that are different before calling std::abort.

I built Jolt as a shared library with:

JPH_BUILD_SHARED_LIBS=ON
CMAKE_BUILD_TYPE=Release

This should have set the JPH_SHARED_LIBRARY define automatically for all projects using Jolt via this line:

JoltPhysics/Jolt/Jolt.cmake

Line 813 in 439c2b6

target_compile_definitions(Jolt PUBLIC JPH_SHARED_LIBRARY)

as long as you explicitly specify in cmake that you want to link against Jolt:

target_link_libraries(MyProjectName Jolt)

or aren't you using cmake at all for your project?

[randomMesh]

or aren't you using cmake at all for your project?

No, i use a classic C++ project in Eclipse IDE and had to manually add the preprocessor defines. It does not know how Jolt has been built at all.