fly/fgdata
1
0
Fork 0
Code Activity

Add-ons: more specific file names for the interface between FG core and add-ons

Browse source 
The add-on framework now uses the following files in each add-on
directory:
  - addon-config.xml (previously: config.xml)
  - addon-main.nas   (previously: main.nas)

This is consistent with the addon-metadata.xml file that is already part
of the interface between FG core and add-ons. The goal is to make it
clearer, when browsing an add-on directory, which files belong to the
"FG core <-> add-on" interface and which files belong to the add-on
proper. This will be beneficial also when more files are added to the
"FG core <-> add-on" interface, such as possibly addon-events.xml in the
future.

This change is incompatible, thus it is the right time to do *before*
2018.2.1 is out, especially considering that this upcoming release
already has incompatible changes in the add-on API, namely the
requirement of the addon-metadata.xml file and the type of the argument
passed to each add-on's main() function. We'll try harder not to break
compatibility in the add-on API once 2018.2.1 is out. For now, it is
still a good time to try to get the API as clean as possible.
This commit is contained in:
Florent Rougon 2018-02-10 19:50:00 +01:00
parent 3bab3b120e
commit c17d9377f8
2 changed files with 26 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
Docs/README.add-ons
View file

@ -35,18 +35,18 @@ add-on directory. Such a directory, when used as the argument of
details below).
3) The add-on directory may contain a PropertyList file called
config.xml, in which case it will be loaded into the Property Tree
at FlightGear startup, as if it were passed to the --config fgfs
option.
addon-config.xml, in which case it will be loaded into the Property
Tree at FlightGear startup, as if it were passed to the --config
fgfs option.
4) The add-on directory must contain a Nasal file called main.nas.
This file will be loaded at startup too, and its main() function
run in the namespace __addon[ADDON_ID]__, where ADDON_ID is the
add-on identifier specified in the addon-metadata.xml file. The
main() function is passed one argument: the addons.Addon object
(a Nasal ghost, see below) corresponding to the add-on being
loaded. This operation is done by $FG_ROOT/Nasal/addons.nas at the
time of this writing.
4) The add-on directory must contain a Nasal file called
addon-main.nas. This file will be loaded at startup too, and its
main() function run in the namespace __addon[ADDON_ID]__, where
ADDON_ID is the add-on identifier specified in the
addon-metadata.xml file. The main() function is passed one
argument: the addons.Addon object (a Nasal ghost, see below)
corresponding to the add-on being loaded. This operation is done by
$FG_ROOT/Nasal/addons.nas at the time of this writing.
Also, the Property Tree is populated (under /addons) with information
about registered add-ons. More details will be given below.
@ -87,7 +87,7 @@ add-on loading
The following sequence of actions:
a) loading an add-on's main.nas file in the namespace
a) loading an add-on's addon-main.nas file in the namespace
__addon[ADDON_ID]__
b) calling its main() function
@ -484,10 +484,11 @@ Note: if C++ code needs to use the add-on base path, better use
AddonManager::registerAddon() fails with a specific exception if the
running FlightGear instance doesn't match the min-FG-version and
max-FG-version requirements declared in the addon-metadata.xml file, as
well as in the obvious other cases (config.xml or addon-metadata.xml not
found, invalid syntax in any of these files, etc.). The code in
options.cxx (fgOptAddon()) catches such exceptions and displays the
appropriate error message with SG_LOG() and fatalMessageBoxThenExit().
well as in the obvious other cases (required files such as
addon-metadata.xml not found, invalid syntax in such files, etc.). The
code in options.cxx (fgOptAddon()) catches such exceptions and displays
the appropriate error message with SG_LOG() and
fatalMessageBoxThenExit().
7. Nasal API

16
Nasal/addons.nas
View file

@ -1,9 +1,10 @@
##
# Initialize addons configured with --addon=foobar command line switch:
# - get the list of registered add-ons
# - load the main.nas file of each add-on into namespace __addon[ADDON_ID]__
# - call function main() from every such main.nas with the add-on ghost as
# argument (an addons.Addon instance).
# - load the addon-main.nas file of each add-on into namespace
# __addon[ADDON_ID]__
# - call function main() from every such addon-main.nas with the add-on ghost
# as argument (an addons.Addon instance).
# Example:
#
@ -11,11 +12,12 @@
#
# - AddonManager.cxx parses /foo/bar/baz/addon-metadata.xml
# - AddonManager.cxx creates prop nodes under /addons containing add-on metadata
# - AddonManager.cxx loads /foo/bar/baz/config.xml into the Property Tree
# - AddonManager.cxx loads /foo/bar/baz/addon-config.xml into the Property Tree
# - AddonManager.cxx adds /foo/bar/baz to the list of aircraft paths (to get
# permissions to read files from there)
# - this script loads /foo/bar/baz/main.nas into namespace __addon[ADDON_ID]__
# - this script calls main(addonGhost) from /foo/bar/baz/main.nas.
# - this script loads /foo/bar/baz/addon-main.nas into namespace
# __addon[ADDON_ID]__
# - this script calls main(addonGhost) from /foo/bar/baz/addon-main.nas.
# - the add-on ghost can be used to retrieve most of the add-on metadata, for
# instance:
# addonGhost.id the add-on identifier
@ -31,7 +33,7 @@ var id = _setlistener("/sim/signals/fdm-initialized", func {
removelistener(id);
foreach (var addon; addons.registeredAddons()) {
var main_nas = addon.basePath ~ "/main.nas";
var main_nas = addon.basePath ~ "/addon-main.nas";
var namespace = "__addon" ~ "[" ~ addon.id ~ "]__";
logprint(5, "Initializing addon '" ~ addon.name ~
"' version " ~ addon.version.str() ~ " from " ~ main_nas ~