395
edits
Nasal/CppBind: Difference between revisions
Jump to navigation
Jump to search
m
intros don't need headings! edits from me too
Philosopher (talk | contribs) m (intros don't need headings! edits from me too) |
|||
| Line 2: | Line 2: | ||
{{Stub}} | {{Stub}} | ||
FlightGear's built-in [[Nasal]] scripting language comes with a set of standard libraries, and can be extended using FlightGear specific APIs. | |||
Exposing simulator internals to scripting space is a fairly common and useful thing, because it enables base package developers to access these internals without having to build FlightGear from source, so the barrier to entry is significantly lower and we've seen an increasing number of novel features purely implemented in scripting space, due to powerful APIs being available to aircraft developers and other base package developers. | |||
FlightGear' | |||
Until FlightGear 2.8, the [[Nasal]] scripting engine only provided a C API to expose such hooks/bindings to scripting space or to expose scripting space data structures back to C/C++. | Until FlightGear 2.8, the [[Nasal]] scripting engine only provided a C API to expose such hooks/bindings to scripting space or to expose scripting space data structures back to C/C++. | ||
Unlike the core Nasal engine itself (which is C), FlightGear however is mostly written and being developed in C++. For quite a while, that meant that the Nasal APIs were a bit low-level, and sometimes also awkward to use when making functions, data structures or objects accessible between C++ and Nasal. | Unlike the core Nasal engine itself (which is C), FlightGear however is mostly written and being developed in C++. For quite a while, that meant that the Nasal APIs were a bit low-level, and sometimes also awkward to use when making functions, data structures or objects accessible between C++ and Nasal. | ||
Thanks to Tom's [[Canvas]] system, there's now a new bindings framework to be found in simgear/nasal/cppbind. This is fully object oriented and supports modern C++ features. | Thanks to development on Tom's [[Canvas]] system, there's now a new bindings framework to be found in [[$SG_SRC]]/simgear/nasal/cppbind. This is fully object oriented and supports modern C++ features by operating through classes and methods with full STL support, abstracting most common operations away. | ||
You will find that most of the "old" code in $FG_SRC/Scripting still uses those old C-APIs for interacting with the Nasal engine. Only the new code, #include | You will find that most of the "old" code in [[$FG_SRC]]/Scripting still uses those old C-APIs for interacting with the Nasal engine. Only the new code, those that <tt>#include <simgear/nasal/cppbind></tt> use boost templates to hide low level details. | ||
Most of the code in the Nasal subsystem itself (FGNasalSys) also still uses the legacy C APIs | Most of the code in the Nasal subsystem itself (FGNasalSys) also still uses the legacy C APIs. You will find the old, low-level APIs explained at [[Howto:Extend Nasal]] - this is just to explain the two approaches, to avoid unnecessary confusion. | ||
The cppbind framework is much more generic and high level than the bare C APIs, cppbind includes unit testing support and makes use of modern C++ features like templates and STL support, including SimGear specific types like SGPath/SGGeod etc, its overhead is fairly small (not just performance, but also LoC to create new bindings). The cppbind framework is already extensively used by the Canvas system and the NasalPositioned_cppbind bindings, both of which are a good place to look for code examples. | The cppbind framework is much more generic and high level than the bare C APIs, cppbind includes unit testing support and makes use of modern C++ features like templates and STL support, including SimGear specific types like SGPath/SGGeod etc, its overhead is fairly small (not just performance, but also LoC to create new bindings). The cppbind framework is already extensively used by the Canvas system and the NasalPositioned_cppbind bindings, both of which are a good place to look for code examples. | ||
Meanwhile, we suggest to favor cppbind over the old, low-level, approach, it isn't only much more elegant, but also saves you tons of typing, too - and will do certain error-checking automatically | Meanwhile, we suggest to favor cppbind over the old, low-level, approach, it isn't only much more elegant, but also saves you tons of typing, too - and will do certain error-checking automatically that you would otherwise have to implement manually. | ||
After working through this article, some of the more useful things to play with | After working through this article, some of the more useful things to play with it the beginning, would be exposing additional SG/FG classes to Nasal space, such as for example: | ||
* the SGSubsystem interface to register scripted SGSubsystems | * the SGSubsystem interface to register scripted SGSubsystems | ||
* the autopilot system [http://forum.flightgear.org/viewtopic.php?p=149376#p149376] [http://forum.flightgear.org/viewtopic.php?f=66&t=21217&hilit=cppbind#p193357] [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38172.html] (there are certain [[How the Nasal GC works|Nasal GC issues]], so that we ask people not to implement FDM-coupled Nasal code like autopilots) | * the autopilot system [http://forum.flightgear.org/viewtopic.php?p=149376#p149376] [http://forum.flightgear.org/viewtopic.php?f=66&t=21217&hilit=cppbind#p193357] [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg38172.html] (there are certain [[How the Nasal GC works|Nasal GC issues]], so that we ask people not to implement FDM-coupled Nasal code like autopilots) | ||
| Line 39: | Line 32: | ||
For more technical Nasal questions (C API, internals etc), you'll probably want to refer to Philosopher, TheTom, Zakalawe or Hooray on the forum - TheTom and Zakalawe can also provide help on using cppbind, having both used it extensively during the last months. | For more technical Nasal questions (C API, internals etc), you'll probably want to refer to Philosopher, TheTom, Zakalawe or Hooray on the forum - TheTom and Zakalawe can also provide help on using cppbind, having both used it extensively during the last months. | ||
== Prerequisites == | |||
* [[Building FlightGear]] | |||
* [[Developing using CMake]] | |||
* [[Programming Resources|C++ experience]] | |||
* [[Nasal|Nasal experience]] | |||
== Objective == | == Objective == | ||
Provide a fully annotated step-by-step introduction to Nasal's cppbind framework. This is mostly based on existing code in SimGear/FlightGear. The cppbind framework itself is to be found $SG_SRC/nasal/cppbind and it's pretty well commented, and makes use of Doxygen strings. If you are already familiar with C++ and SG/FG,, you'll want to check out the unit tests in cppbind_test.cxx. | |||
Provide a fully annotated step-by-step introduction to Nasal's cppbind framework. This is mostly based on existing code in SimGear/FlightGear. The cppbind framework itself is to be found $SG_SRC/nasal/cppbind and it's pretty well commented, and makes use of Doxygen strings. If you are already familiar with C++ and SG/FG,, you'll want to check out the unit tests in cppbind_test.cxx. | |||
This write-up should get you started with the basics of the framework. | This write-up should get you started with the basics of the framework. | ||