docs: document the extern "C" module_register() requirement for dynamically loaded modules - #100
Open
MAN$I VERMA (mansiverma897993) wants to merge 2 commits into
Conversation
…ister() with extern "C" The module factory resolves out-of-tree components by looking up the unmangled symbol module_register in the library named by dylib_path (or moduletype). This only works when the hook is declared extern "C", as every in-tree component does, but the requirement was not documented anywhere: a plain C++ definition exports a mangled symbol, registration is silently skipped, and elaboration fails with a misleading "Can't find module type" error. Add a 'Loading Components from Shared Libraries' section to docs/configuration.md describing the lookup and the module_register() contract, and cross-reference it from the dylib_path example in docs/backends.md. Fixes qualcomm#90 Signed-off-by: mansiverma897993 <vmansi756@gmail.com>
… contract in dylib diagnostics When a library loaded via dylib_path exports no module_register symbol (typically because the hook lacks extern "C" and is mangled), the only hint was an easy-to-miss warning, and elaboration then aborted with "Can't find module type" - which suggests a wrong moduletype string rather than a linkage problem. Name the likely cause in the warning, and extend the construct_module error to explain the registration contract when a loaded library did not register the requested type. The warning stays a warning: a library may legitimately register its types from static initializers at load time without exporting module_register. Fixes qualcomm#90 Signed-off-by: mansiverma897993 <vmansi756@gmail.com>
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
1 participant
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.
Summary
Fixes #90
The module factory loads out-of-tree components by resolving the unmangled symbol
module_registerin the shared library named viadylib_path/moduletype(register_module_from_dylib()inmodule_factory_container.h). The hook must therefore be declaredextern "C"-- as every in-tree component does -- but this requirement was not documented, and missing it produces a misleading failure: the library loads, registration is skipped with only a warning, and elaboration aborts withCan't find module type: <X>, which points at the configuration rather than at C++ name mangling.Changes
Documentation
docs/configuration.md: new Loading Components from Shared Libraries section documenting how the library name is resolved (dylib_path, falling back tomoduletype, plus the platform extension) and themodule_register()contract: the hook must be exported with C linkage and must register the component under the same name used asmoduletype(viaGSC_MODULE_REGISTER_C), with a minimal header/source example mirroring the in-tree pattern (e.g.keep_alive.h). It also documents the failure mode whenextern "C"is missing, and the subtlety that the definition picks up C linkage from the declaration in the included header.docs/backends.md: the Lua example there was the only placedylib_pathappeared in the docs -- added a short note next to it cross-referencing the new section.Diagnostics (
module_factory_container.h)SCP_WARNemitted whenmodule_registeris not found in a successfully loaded library now names the likely cause (missingextern "C"linkage, so the exported symbol is mangled).SC_REPORT_ERRORinconstruct_module()-- the message users actually see -- now explains, when a library was loaded but the requested type is still unregistered, that the library must exportextern "C" void module_register()and that the hook must register the exact requested type name.On the issue's suggestion to escalate the warning to an error: it is kept as a warning deliberately. A library can legitimately register its types from static initializers at load time (e.g.
GSC_MODULE_REGISTER_Cat global scope) without exporting amodule_registerhook, and escalating would break that case. Instead, the fatal-by-defaultconstruct_moduleerror now carries the full hint at the point where the failure is certain.Testing
.clang-format.