From c17d9377f8da51e9ad57dfecb5a3f25f29782d5c Mon Sep 17 00:00:00 2001 From: Florent Rougon <f.rougon@free.fr> Date: Sat, 10 Feb 2018 19:50:00 +0100 Subject: [PATCH] Add-ons: more specific file names for the interface between FG core and add-ons 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. --- Docs/README.add-ons | 33 +++++++++++++++++---------------- Nasal/addons.nas | 16 +++++++++------- 2 files changed, 26 insertions(+), 23 deletions(-) diff --git a/Docs/README.add-ons b/Docs/README.add-ons index 8ffddfaa5..a77d3122c 100644 --- a/Docs/README.add-ons +++ b/Docs/README.add-ons @@ -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 diff --git a/Nasal/addons.nas b/Nasal/addons.nas index 8ad3a0bca..5d3baeaaf 100644 --- a/Nasal/addons.nas +++ b/Nasal/addons.nas @@ -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 ~