@@ -7,156 +7,4 @@ Basilisk SDK Version 1
77Purpose
88-------
99
10- The Basilisk SDK (``bsk-sdk ``) defines the public surface that external plugin
11- authors can rely on when integrating new simulation capabilities with the
12- core runtime. Version 1 focuses on establishing a stable contract for Python
13- and C++ plugin authors and capturing the minimal tooling that ships inside the
14- Basilisk source tree.
15-
16- Scope and Deliverables
17- ----------------------
18-
19- Version 1 guarantees the following artifacts:
20-
21- - ``bsk_core.plugins ``: the runtime registry responsible for discovering
22- entry-point advertised plugins and exposing them under ``Basilisk.modules ``.
23- - ``bsk-sdk ``: a small Python package that publishes the SDK headers, declares a
24- dependency on the ``pybind11 `` headers required by the helper macros, and
25- provides :func: `bsk_sdk.include_dir ` / :func: `bsk_sdk.include_dirs ` helpers for
26- build scripts.
27- - A companion ``sync_headers.py `` utility (``sdk/tools ``) keeps the vendored
28- Basilisk ``architecture `` headers in sync with the main source tree.
29- - ``sdk/include/bsk/sdk.hpp ``: a single header that wraps the pybind11
30- boilerplate required for C++ factories and enforces the default constructible
31- + ``Reset ``/``UpdateState `` interface contract. The same header is shipped by
32- :mod: `bsk-sdk `.
33- - A consolidated ``plugins `` example package containing both Python and C++
34- implementations that demonstrate the expected packaging and registration
35- patterns.
36-
37- Any other files in the repository are explicitly *not * part of the SDK
38- agreement for this release.
39-
40- Plugin Registry API
41- -------------------
42-
43- The ``bsk_core.plugins.PluginRegistry `` class is the primary integration
44- point for third-party plugins. The registry is responsible for staging plugin
45- definitions until the runtime exports them under ``Basilisk.modules ``.
46-
47- The public methods guaranteed in v1 are:
48-
49- .. code-block :: python
50-
51- class PluginRegistry :
52- def register_python_module (self name : str , cls : type[sysModel.SysModel]) -> None : ...
53- def register_factory (self name : str , factory : Any) -> None : ...
54-
55- register_python_module `` accepts any subclass of
56- ``Basilisk.architecture.sysModel.SysModel `` and exposes it as a class on
57- ``Basilisk.modules `` using the provided name. ``register_factory `` stores an
58- opaque object under the supplied name. Factories are expected to be callables
59- returning Basilisk-compatible module instances, but v1 defers any runtime shape
60- validation to keep the surface area small.
61-
62- Plugins must advertise a ``register(registry) `` callable through the
63- ``basilisk.plugins `` entry-point group. During startup Basilisk resolves the
64- entry-point, imports the containing module, and invokes the callable with the
65- shared registry instance.
66-
67- Python Plugin Pattern
68- ---------------------
69-
70- Pure-Python plugins should follow the pattern demonstrated in
71- ``plugins/src/python/Basilisk/ExternalModules/customPythonModule.py ``:
72-
73- .. code-block :: python
74-
75- from Basilisk.architecture import sysModel
76-
77- class ExamplePluginModule (sysModel .SysModel ):
78- def Reset (self current_sim_nanos ):
79- ...
80-
81- def UpdateState (self current_sim_nanos , call_time ):
82- ...
83-
84- def register (registry ):
85- registry.register_python_module(" ExamplePluginModule"
86-
87- pyproject.toml `` must expose the ``register `` function via
88-
89- .. code-block :: toml
90-
91- [project.entry-points."basilisk.plugins"]
92- example = "bsk_example_plugin.simple:register"
93-
94- Basilisk.modules ``:
95-
96- .. code-block :: python
97-
98- from Basilisk import modules
99-
100- plugin_cls = modules.ExamplePluginModule
101- instance = plugin_cls()
102- instance.Reset(0 )
103- instance.UpdateState(0 , 0 )
104-
105-
106- ------------------
107-
108- Native extensions should include ``sdk/include/bsk/sdk.hpp `` to inherit
109- the pybind11 binding helpers. When building outside the Basilisk source tree
110- the :mod: `bsk-sdk ` package exposes the headers via
111- ``import bsk_sdk; bsk_sdk.include_dir() `` (or ``include_dirs() `` to also capture
112- the ``Basilisk `` subdirectory and ``pybind11 `` include path). Version 1
113- guarantees the availability of:
114-
115- - ``bsk::plugin::register_basic_plugin ``
116- - ``BSK_PLUGIN_PYBIND_MODULE ``
117-
118- The ``BSK_PLUGIN_PYBIND_MODULE `` macro defines both the pybind11 module and the
119- ``create_factory `` callable consumed by the Basilisk runtime. The expected class
120- contract mirrors the Python case: default constructible with ``Reset `` and
121- ``UpdateState `` methods.
122-
123- .. code-block :: cpp
124-
125- #include <bsk/sdk.hpp>
126-
127- class ExampleCppModule {
128- public:
129- void Reset(double current_sim_nanos);
130- void UpdateState(double current_sim_nanos, double call_time);
131- };
132-
133- BSK_PLUGIN_PYBIND_MODULE(_example_cpp, ExampleCppModule, "ExampleCppModule");
134-
135-
136- factory, and register it:
137-
138- .. code-block :: python
139-
140- from importlib import import_module
141-
142- def register (registry ):
143- ext = import_module(" bsk_example_plugin_cpp._example_cpp"
144- factory = ext.create_factory()
145- registry.register_factory(" ExampleCppFactory"
146-
147-
148- ---------------------------
149-
150- Version 1 intentionally leaves several items out of scope so they can be
151- designed with real-world feedback:
152-
153- - The SDK header is distributed from the Basilisk source tree and is not
154- published as a standalone artifact.
155- - Factories registered via ``register_factory `` are treated as opaque callables;
156- Basilisk does not verify their type or interface beyond name collisions.
157- - The helper header requires C++17 and a compatible pybind11 toolchain.
158- - Plugin lifecycle hooks beyond ``Reset ``/``UpdateState `` will be designed as
159- future Basilisk modules adopt richer interfaces.
160-
161- Feedback on these gaps is welcome and will inform the roadmap for subsequent
162- SDK revisions.
10+ TODO, this all changed now since just using SWIG directly.
0 commit comments