2017-12-02 22:33:18 +00:00
-*- coding: utf-8; fill-column: 72; -*-
Add-ons in FlightGear
=====================
This document explains how add-ons work in FlightGear. The add-on
feature was first added in FlightGear 2017.3. This document describes an
evolution of the framework that appeared in FlightGear 2017.4.
Contents
--------
1. Terminology
2018-02-23 09:04:04 +00:00
2017-12-02 22:33:18 +00:00
2. The addon-metadata.xml file
2018-02-23 09:04:04 +00:00
3. Add-ons and the Property Tree
a) Add-on metadata
b) Subtree reserved for add-on developers
2018-01-18 08:49:16 +00:00
4. Resources under the add-on directory
2018-02-23 09:04:04 +00:00
2018-03-21 07:39:47 +00:00
5. Persistent storage location for add-ons
6. Add-on-specific menus and dialogs
2018-02-23 09:04:04 +00:00
2018-02-27 12:14:00 +00:00
a) Add-on-specific menus
b) Add-on-specific dialogs
2018-02-23 09:04:04 +00:00
2018-03-21 07:39:47 +00:00
7. How to run code after an add-on is loaded
2018-02-27 12:14:00 +00:00
2018-03-21 07:39:47 +00:00
8. Overview of the C++ API
2018-02-27 12:14:00 +00:00
2018-03-21 07:39:47 +00:00
9. Nasal API
2017-12-02 22:33:18 +00:00
2018-12-05 11:33:58 +00:00
10. Add-on development; in-sim reload of Nasal code
2017-12-02 22:33:18 +00:00
Introduction
------------
fgfs can be passed the --addon=<path> option, where <path> indicates an
add-on directory. Such a directory, when used as the argument of
--addon, receives special treatment :
1) The add-on directory is added to the list of aircraft paths.
2) The add-on directory must contain a PropertyList file called
addon-metadata.xml that gives the name of the add-on, its
identifier (id), its version and possibly a few other things (see
details below).
3) The add-on directory may contain a PropertyList file called
2018-02-10 18:50:00 +00:00
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
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.
2017-12-02 22:33:18 +00:00
Also, the Property Tree is populated (under /addons) with information
about registered add-ons. More details will be given below.
The --addon option can be specified zero or more times; each of the
operations indicated above is carried out for every specified add-on in
the order given by the --addon options used: that's what we call add-on
registration order, or add-on load order. In other words, add-ons are
registered and loaded in the order specified by the --addon options
used.
1. Terminology
~~~~~~~~~~~
add-on base path
Path to a directory containing all of the add-on files. This is the
path passed to the --addon fgfs option, when one wants to load the
add-on in question.
add-on identifier (id)
A string such as org.flightgear.addons.ATCChatter or
user.joe.MyGreatAddon, used to uniquely identify an add-on. The add-on
identifier is declared in <path>/addon-metadata.xml, where <path> is
the add-on base path.
add-on registration
When a --addon option is processed, FlightGear ensures that the add-on
identifier found in the corresponding addon-metadata.xml file isn't
already used by an add-on from a previous --addon option on the same
command line, and stores the add-on metadata inside dedicated C++
objects. This process is called add-on registration.
add-on loading
The following sequence of actions:
2018-02-10 18:50:00 +00:00
a) loading an add-on's addon-main.nas file in the namespace
2017-12-02 22:33:18 +00:00
__addon[ADDON_ID]__
b) calling its main() function
is performed later (see $FG_ROOT/Nasal/addons.nas) and called add-on
loading.
2. The addon-metadata.xml file
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every add-on must have in its base directory a file called
2017-12-25 20:19:01 +00:00
'addon-metadata.xml'. This section explains how to write this file.
Sample addon-metadata.xml file
==============================
Here is an example of an addon-metadata.xml file, for a hypothetical
2018-10-11 03:11:00 +00:00
add-on called “Flying Turtle” distributed by Joe User:
2017-12-02 22:33:18 +00:00
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
2017-12-10 21:38:38 +00:00
<meta>
<file-type type="string">FlightGear add-on metadata</file-type>
<format-version type="int">1</format-version>
</meta>
2017-12-02 22:33:18 +00:00
<addon>
2017-12-09 12:49:20 +00:00
<identifier type="string">user.joe.FlyingTurtle</identifier>
<name type="string">Flying Turtle</name>
<version type="string">1.0.0rc2</version>
2017-12-30 11:23:34 +00:00
<authors>
<author>
<name type="string">Joe User</name>
<email type="string">optional_address@example.com</email>
<url type="string">http://joe.example.com/foobar/</url>
</author>
<author>
<name type="string">Jane Maintainer</name>
<email type="string">jane@example.com</email>
<url type="string">https://jane.example.com/</url>
</author>
2017-12-25 20:19:01 +00:00
</authors>
2017-12-30 11:23:34 +00:00
<maintainers>
<maintainer>
<name type="string">Jane Maintainer</name>
<email type="string">jane@example.com</email>
<url type="string">https://jane.example.com/</url>
</maintainer>
2017-12-25 20:19:01 +00:00
</maintainers>
2017-12-09 12:49:20 +00:00
<short-description type="string">
Allow flying with new foobar powers.
</short-description>
<long-description type="string">
This add-on enables something really great involving turtles...
</long-description>
2020-07-10 12:10:49 +00:00
<localized>
<fr>
<short-description type="string">
Permet de voler avec de nouveaux pouvoirs foobar.
</short-description>
<name>
Tortue volante
</name>
</fr>
<de>
<short-description type="string">
Erlaube das Fliegen mit neuen Foobar-Kräften.
</short-description>
</de>
</localized>
2017-12-25 20:19:01 +00:00
<license>
<designation type="string">
GNU GPL version 2 or later
</designation>
<file type="string">
COPYING
</file>
2017-12-09 12:49:20 +00:00
2017-12-25 20:19:01 +00:00
<url type="string">
https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
</url>
</license>
2017-12-09 12:49:20 +00:00
2017-12-25 20:19:01 +00:00
<min-FG-version type="string">2017.4.0</min-FG-version>
<max-FG-version type="string">none</max-FG-version>
2017-12-09 12:49:20 +00:00
2017-12-25 20:19:01 +00:00
<urls>
<home-page type="string">
https://example.com/quux
</home-page>
<download type="string">
https://example.com/quux/download
</download>
<support type="string">
https://example.com/quux/support
</support>
<code-repository type="string">
https://example.com/quux/code-repository
</code-repository>
</urls>
<tags>
<tag type="string">first tag</tag>
<tag type="string">second tag</tag>
<tag type="string">etc.</tag>
</tags>
2017-12-02 22:33:18 +00:00
</addon>
</PropertyList>
2017-12-25 20:19:01 +00:00
General rules
=============
2018-10-11 03:11:00 +00:00
We use the terms “field” or “node” interchangeably here to refer to
2017-12-25 20:19:01 +00:00
nodes of the addon-metadata.xml PropertyList file (technically, a field
always has a value, possibly empty, therefore fields are all leaf
nodes).
Leading and trailing whitespace in each field of addon-metadata.xml is
removed. All other whitespace is a priori preserved (this could depend
on the particular field, though).
Most fields are optional. In most cases, omitting a field is the same as
leaving it empty. But don't write empty tag fields, it is really too
ugly. ;-)
Name and id
===========
Nodes: /addon/name and /addon/identifier
2017-12-02 22:33:18 +00:00
The add-on name is the pretty form. It should not be overly long, but
otherwise isn't constrained. On the other hand, the add-on identifier
(id), which serves to uniquely identify an add-on:
- must contain only ASCII letters (A-Z, a-z) and dots ('.');
- must be in reverse DNS style (even if the domain doesn't exist),
e.g., org.flightgear.addons.ATCChatter for an add-on distributed in
2018-10-11 03:11:00 +00:00
FGAddon, or user.joe.FlyingTurtle for Joe User's “Flying Turtle”
2017-12-02 22:33:18 +00:00
add-on. Of course, if Joe User owns a domain name and uses it to
distribute his add-on, he should put it here.
2017-12-25 20:19:01 +00:00
Authors and maintainers
=======================
Nodes: /addon/authors and /addon/maintainers
Authors are people who contributed significantly to the add-on.
2017-12-30 11:23:34 +00:00
Maintainers are people currently in charge of maintaining it.
It is possible to declare any number of authors and any number of
maintainers---the example above shows only one maintainer for shortness,
but this is not a restriction.
For each author and maintainer, you can give a name, an email address
and a URL. The name must be non-empty, but the email address and URL
need not be specified or may be left empty, which is equivalent.
Obviously, if no email address nor URL is given for any maintainer, it
is highly desirable that /addon/urls/support contains a usable URL for
contacting the add-on maintainers.
The data in children nodes of /addon/maintainers may refer either to
real persons or to more abstract entities such as mailing-lists. In case
of a real person, the corresponding URL, if specified, is expected to be
2018-10-11 03:11:00 +00:00
the person's home page. On the other hand, if a declared “maintainer” is
2017-12-30 11:23:34 +00:00
a mailing-list, a good use for the 'url' field is to indicate the
address of a web page from which people can subscribe to the
mailing-list.
2017-12-25 20:19:01 +00:00
Short and long descriptions
===========================
Nodes: /addon/short-description and /addon/long-description
2017-12-02 22:33:18 +00:00
The short description should fit on one line (try not to exceed, say, 78
characters), and in general consist of only one sentence.
2017-12-25 20:19:01 +00:00
The long description is essentially free-form, but only break lines when
you do want a line break at this point. In other words, don't wrap lines
manually in the XML file: this will be automatically done by the
software displaying the add-on description, according to the particular
line width it uses (which can depend on the user's screen or
configuration, etc.). A single \n inside a paragraph (see footnote [1])
means a hard line break. Two \n in a row (i.e., a blank line) should be
used to separate paragraphs. Example:
This is a paragraph.
2018-10-11 03:11:00 +00:00
This is the second line of the same paragraph. It can be very, very, very long and contain several sentences.
2017-12-25 20:19:01 +00:00
2018-10-11 03:11:00 +00:00
This is a different paragraph. Again, don't break lines (i.e., don't press Enter) unless a particular formatting reason makes it necessary. For instance, it is okay to break lines in order to present a list of items, but not for line wrapping.
2017-12-25 20:19:01 +00:00
Licensing terms
===============
Nodes: /addon/license/designation
/addon/license/file
/addon/license/url
The /add-on/license/designation node should describe the add-on
licensing terms in a short but accurate way, if possible. If this is not
2018-10-11 03:11:00 +00:00
practically doable, use the value “Custom”. If the add-on is distributed
under several licenses, use the value “Multiple”. In all cases, make
2017-12-25 20:19:01 +00:00
sure the licensing terms are clearly specified in other files of the
add-on (typically, at least README.txt or COPYING). Values for
2018-10-11 03:11:00 +00:00
/add-on/license/designation could be “GNU GPL version 2 or later”, “CC0
1.0 Universal”, “3-clause BSD”, etc.
2017-12-25 20:19:01 +00:00
In most cases, the add-on should contain a file containing the full
license text. Use the /add-on/license/file node to point to this file:
it should contain a file path that is relative to the add-on base
directory. This path must use slash separators ('/'), even if you use
Windows.
The /add-on/license/url node should contain a single URL if there is an
official, stable URL for the license under which the add-on is
2018-10-11 03:11:00 +00:00
distributed. The term “official” here is to be interpreted in the
2017-12-25 20:19:01 +00:00
context of the particular license. For instance, for a GNU license
(GPL2, LGPL2.1, etc.), the URL domain must be gnu.org; for a CC license
(CC0 1.0 Universal, CC-BY-SA 4.0...), it must be creativecommons.org,
etc.
Minimum and maximum FlightGear versions
=======================================
Nodes: /addon/min-FG-version and /addon/max-FG-version
These two nodes are optional and may be omitted unless the add-on is
known not to work with particular FlightGear versions.
/addon/min-FG-version defaults to 2017.4.0 and /addon/max-FG-version to
the special value 'none' (only allowed for /addon/max-FG-version). Apart
from this special case, every non-empty value present in one of these
two fields must be a proper FlightGear version number usable with
2017-12-02 22:33:18 +00:00
simgear::strutils::compare_versions(), for instance '2017.4.1'.
2017-12-25 20:19:01 +00:00
Add-on version
==============
Node: /addon/version
The /addon/version node gives the version of the add-on and must obey a
strict syntax[2], which is a subset of what is described in PEP 440:
2017-12-02 22:33:18 +00:00
https://www.python.org/dev/peps/pep-0440/
Valid examples are, in increasing sort order:
1.2.5.dev1 # first development release of 1.2.5
1.2.5.dev4 # fourth development release of 1.2.5
1.2.5
1.2.9
1.2.10a1.dev2 # second dev release of the first alpha release of 1.2.10
1.2.10a1 # first alpha release of 1.2.10
1.2.10b5 # fifth beta release of 1.2.10
1.2.10rc12 # twelfth release candidate for 1.2.10
1.2.10
1.3.0
2017.4.12a2
2017.4.12b1
2017.4.12rc1
2017.4.12
.devN suffixes can of course be used on beta and release candidates too,
just as with the 1.2.10a1.dev2 example given above for an alpha release.
Note that a development release always sorts before the corresponding
non-development release (e.g., 2017.2.1b5.dev4 comes before 2017.2.1b5).
2020-07-10 12:10:49 +00:00
Translations
============
Certain nodes can be translated based on the active languages within FlightGear.
Especially, the name and descriptions can be translated, by adding them to
a language node beneath 'localized', as show in the example above. Where there is
no translation for a particular value, the default one is used.
2017-12-25 20:19:01 +00:00
Other fields
============
The other nodes of 'addon-metadata.xml' should be self-explanatory. :-)
2017-12-02 22:33:18 +00:00
2018-02-23 09:04:04 +00:00
3. Add-ons and the Property Tree
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a) Add-on metadata
^^^^^^^^^^^^^^^
2017-12-02 22:33:18 +00:00
The most important metadata for each registered add-on is made
accessible in the Property Tree under /addons/by-id/ADDON_ID and the
property /addons/by-id/ADDON_ID/loaded can be checked or listened to, in
order to determine when a particular add-on is loaded. There is also a
Nasal interface to access add-on metadata in a convenient way (see
below).
More precisely, when an add-on is registered, its name, id, base path,
version (converted to a string), loaded status (boolean) and load
sequence number (int) become available in the Property Tree as
/addons/by-id/ADDON_ID/{name,id,path,version,loaded,load-seq-num}. The
loaded status is initially false, and set to true when the add-on
loading phase is complete.
There are also /addons/addon[i]/path nodes where i is 0 for the first
registered add-on, 1 for the second one, etc.
2018-02-23 09:04:04 +00:00
b) Subtree reserved for add-on developers
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
For each add-on, the subtree of the global Property Tree starting at
/addons/by-id/ADDON_ID/addon-devel is reserved for the specific needs of
the add-on, where ADDON_ID stands for the add-on identifier. For
instance, developers of the add-on whose identifier is
user.joe.FlyingTurtle can store whatever they want under
/addons/by-id/user.joe.FlyingTurtle/addon-devel with the assurance that
doing this won't clash with properties used by the add-on framework.
Example:
/addons/by-id/user.joe.FlyingTurtle/addon-devel/some/property and
/addons/by-id/user.joe.FlyingTurtle/addon-devel/other/property
could be two properties used for the specific needs of the
add-on whose identifier is user.joe.FlyingTurtle.
Add-on developers should *not* use other places in the /addons subtree
of the Property Tree for their custom properties.
2018-01-18 08:49:16 +00:00
4. Resources under the add-on directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many functions in FlightGear use files that are located using the
SimGear ResourceManager class. This class allows one to point to files
by relative path in aircraft source files and other places. The resource
manager queries a set of providers, some of which look inside aircraft
paths (starting with the current aircraft), others inside scenery paths,
others under $FG_ROOT, etc. The first file that matches the specified
resource path is used.
One of these providers only handles resource paths with a very specific
syntax, which is:
[addon=ADDON_ID]path/relative/to/the/addon/directory
(for instance, [addon=user.joe.FlyingTurtle]images/eject-button.png)
When you use such a syntax in a place that is expected to contain a
resource path, it will only find the specified file under the directory
of the add-on whose identifier is ADDON_ID. This allows one to
specifically target a particular file inside a particular add-on,
instead of crossing fingers and hoping that the specified resource won't
be found by coincidence in another place such as an aircraft directory,
a scenery directory or inside $FG_ROOT (such mistakes can easily happen
when unrelated places use files with rather generic names, such as
button.png, system.xml, etc.).
The [addon=ADDON_ID]relative/path syntax is useful where resources are
specified inside non-Nasal files (e.g., in property-rule configuration
files, which use the XML format). For the particular case of Nasal code,
2018-10-11 03:11:00 +00:00
there is a better way that is explained below (see “Nasal API”): the
2018-01-18 08:49:16 +00:00
resourcePath() method of addons.Addon objects returns a string like
"[addon=ADDON_ID]relative/path" when you pass it the string
"relative/path". This is a good thing to use, because then your Nasal
code doesn't need to know about the particular syntax for
add-on-specific resources and, more interestingly, doesn't have to
hardcode the add-on identifier every time you need to access a resource
inside the add-on directory.
2020-07-10 12:10:49 +00:00
4.1 Resources extending $FG_ROOT
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Add-ons can options supply a special sub-directory which is searched when
FlightGear looks for files normally residing in $FG_ROOT. For example input
configurations, network protocols and other non-aircraft resources. Since
these files cannot use the scheme above, a different approach is used. If
an add-on defines a subdirectory called 'FGData', this is becomes an
additional data directory to be searched for any such standard files. For
security reasons, add-on FGData extensions are searched after the main
$FG_ROOT location, so that an addon cannot maliciously replace a core resource.
Only some files currently support being added via this mechanism, so if you
find a non-working case which would be useful, please request it via the
developer mailing list.
2018-02-27 12:14:00 +00:00
2018-03-21 07:39:47 +00:00
5. Persistent storage location for add-ons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If an add-on needs to store data that persists across FlightGear
sessions, it can use a specific directory tree whose path is obtained
with addon.storagePath, where 'addon' is an addons.Addon instance. This
corresponds to $FG_HOME/Export/Addons/ADDON_ID, however it is simpler
and better to use addon.storagePath instead of hardcoding and manually
assembling this path in each add-on. Since the directory is likely not
to exist until the add-on creates it, the recommended usage pattern is
the following:
1) Create the add-on-specific storage directory if it doesn't already
exist, and optionally get its path at the same time:
storageDir = addon.createStorageDir();
Typically, you'll run this in the add-on main() function (at least,
early enough) if your add-on uses the storage directory. Note that
there is no need to check yourself whether the directory already
exists: addon.createStorageDir() does that for you.
2) At any time, you can get a path to the add-on-specific storage
directory with:
storageDir = addon.storagePath
Accessing addon.storagePath doesn't check for the existence nor the
type of $FG_HOME/Export/Addons/ADDON_ID, thus it is a bit faster
than addon.createStorageDir(). Use addon.storagePath whenever you
know that the directory has already been created.
The features described in this section were added in FlightGear 2018.2.
6. Add-on-specific menus and dialogs
2018-02-27 12:14:00 +00:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a) Add-on-specific menus
^^^^^^^^^^^^^^^^^^^^^
Add-ons can easily provide their own menus. If an add-on is loaded that
has a file named 'addon-menubar-items.xml' in its base directory, the
menus described in this file are added to the FlightGear menu bar. The
file should look like this:
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<meta>
<file-type type="string">FlightGear add-on menu bar items</file-type>
<format-version type="int">1</format-version>
</meta>
<menubar-items>
<menu>
...
</menu>
2018-02-27 19:31:10 +00:00
...
2018-02-27 12:14:00 +00:00
<menu>
...
</menu>
</menubar-items>
</PropertyList>
In this file, each <menu> element must be a valid menu description for
the FlightGear menu system (the FlightGear standard menubar in
$FG_ROOT/gui/menubar.xml provides good examples). Here is an example
that adds one menu with an entry for running some Nasal code and another
entry for opening a custom dialog (see below for add-on-specific dialogs):
<menu>
<label>My Menu</label>
<enabled type="bool">true</enabled>
<item>
<label>Run Foobar Nasal</label>
<binding>
<command>nasal</command>
<script>foobar.doBaz();</script>
</binding>
</item>
2018-02-27 19:31:10 +00:00
2018-02-27 12:14:00 +00:00
<item>
<label>My Foobar Dialog</label>
<binding>
<command>dialog-show</command>
<dialog-name>my-foobar-dialog</dialog-name>
</binding>
</item>
</menu>
This feature was added in FlightGear 2018.2.
For older versions, one can add menus via addon-config.xml, but it's a
bit hackish because of the menu index problem.
b) Add-on-specific dialogs
^^^^^^^^^^^^^^^^^^^^^^^
As is the case for aircraft, add-ons can provide their own dialogs by
shipping the corresponding XML files in the subfolder gui/dialogs of the
add-on base directory. In other words, with a file like
<addon-base-path>/gui/dialogs/my-foobar-dialog.xml
starting with:
<?xml version="1.0" encoding="UTF-8"?>
<PropertyList>
<name>my-foobar-dialog</name>
...
the following <item> element inside 'addon-menubar-items.xml' (see
above) describes a valid menu entry for showing the custom dialog.
<item>
<label>My Foobar Dialog</label>
<binding>
<command>dialog-show</command>
<dialog-name>my-foobar-dialog</dialog-name>
</binding>
</item>
See $FG_ROOT/gui/dialogs to get inspiration from FlightGear's standard
dialogs.
This feature was added in FlightGear 2018.2.
2018-03-21 07:39:47 +00:00
7. How to run code after an add-on is loaded
2017-12-02 22:33:18 +00:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You may want to set up Nasal code to be run after an add-on is loaded;
here is how to do that:
var addonId = "user.joe.FlyingTurtle";
var loadedFlagNode = props.globals.getNode("/addons")
.getChild("by-id", 0, 1)
.getChild(addonId, 0, 1)
.getChild("loaded", 0, 1);
if (loadedFlagNode.getBoolValue()) {
logprint(5, addonId ~ " is already loaded");
} else {
# Define a function to be called after the add-on is loaded
var id = setlistener(
loadedFlagNode,
func(changedNode, listenedNode) {
if (listenedNode.getBoolValue()) {
removelistener(id);
logprint(5, addonId ~ " is loaded");
};
},
0, 0);
}
2018-03-21 07:39:47 +00:00
8. Overview of the C++ API
2017-12-02 22:33:18 +00:00
~~~~~~~~~~~~~~~~~~~~~~~
The add-on C++ infrastructure mainly relies on the following classes:
AddonManager, Addon and AddonVersion. AddonManager is used to register
add-ons, which later leads to their loading. AddonManager relies on an
std::map<std::string, AddonRef>, where keys are add-on identifiers and
AddonRef is SGSharedPtr<Addon> at the time of this writing (changing it
to another kind of smart pointer should be a mere one-line change). This
map holds the metadata of each registered add-on. Accessor methods are
available for:
- retrieving the lists of registered and loaded add-ons;
- checking if a particular add-on has already been registered or
loaded;
- for each add-on, obtaining an Addon instance which can be queried
for its identifier, its name, identifier, version, base path, the
minimum and maximum FlightGear versions it requires, its base node
in the Property Tree, its order in the load sequence...
The AddonVersion class handles everything about add-on version numbers:
- initialization from the individual components or from a string;
- conversion to a string and output to an std::ostream;
- access to every component;
- comparisons using the standard operators: ==, !=, <, <=, >, >=.
Registering an add-on using AddonManager::registerAddon() ensures
uniqueness of the add-on identifier and makes its name, identifier, base
path, version (converted to a string), loaded status (boolean) and load
sequence number (int) available in the Property Tree as
/addons/by-id/ADDON_ID/{name,id,path,version,loaded,load-seq-num}.
Note: if C++ code needs to use the add-on base path, better use
AddonManager::addonBasePath() or Addon::getBasePath(), whose
return values can't be tampered with by Nasal code.
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
2018-02-10 18:50:00 +00:00
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().
2017-12-02 22:33:18 +00:00
2018-03-21 07:39:47 +00:00
9. Nasal API
2017-12-02 22:33:18 +00:00
~~~~~~~~~
The Nasal add-on API all lives in the 'addons' namespace. It gives Nasal
code easy access to add-on metadata, for instance like this:
var myAddon = addons.getAddon("user.joe.FlyingTurtle");
print(myAddon.id);
print(myAddon.name);
print(myAddon.version.str());
2017-12-30 11:23:34 +00:00
foreach (var author; myAddon.authors) {
2018-01-08 08:49:27 +00:00
print(author.name, " ", author.email, " ", author.url);
2017-12-30 11:23:34 +00:00
}
foreach (var maintainer; myAddon.maintainers) {
2018-01-08 08:49:27 +00:00
print(maintainer.name, " ", maintainer.email, " ", maintainer.url);
2017-12-30 11:23:34 +00:00
}
2017-12-02 22:33:18 +00:00
print(myAddon.shortDescription);
print(myAddon.longDescription);
2017-12-25 20:19:01 +00:00
print(myAddon.licenseDesignation);
print(myAddon.licenseFile);
print(myAddon.licenseUrl);
2017-12-02 22:33:18 +00:00
print(myAddon.basePath);
print(myAddon.minFGVersionRequired);
print(myAddon.maxFGVersionRequired);
print(myAddon.homePage);
print(myAddon.downloadUrl);
print(myAddon.supportUrl);
2017-12-25 20:19:01 +00:00
print(myAddon.codeRepositoryUrl);
foreach (var tag; myAddon.tags) {
print(tag);
}
2017-12-02 22:33:18 +00:00
print(myAddon.loadSequenceNumber);
# myAddon.node is a props.Node object for /addons/by-id/ADDON_ID
print(myAddon.node.getPath());
Among other things, the Nasal add-on API allows one to get the version
of any registered add-on as a ghost and reliably compare it to another
instance of addons.AddonVersion:
var myAddon = addons.getAddon("user.joe.FlyingTurtle");
var firstVersionOK = addons.AddonVersion.new("2.12.5rc1");
# Or alternatively:
# var firstVersionOK = addons.AddonVersion.new(2, 12, 5, "rc1");
if (myAddon.version.lowerThan(firstVersionOK)) {
...
Here follows the complete Nasal add-on API, at the time of this writing.
2017-12-25 20:19:01 +00:00
All strings are encoded in UTF-8.
2017-12-02 22:33:18 +00:00
Queries to the AddonManager:
addons.isAddonRegistered(string addonId) -> bool (1 or 0)
addons.registeredAddons() -> vector<addons.Addon>
(in registration/load order)
addons.isAddonLoaded(string addonId) -> bool (1 or 0)
addons.loadedAddons() -> vector<addons.Addon>
(in lexicographic order)
addons.getAddon(string addonId) -> addons.Addon instance (ghost)
Read-only data members (attributes) of addons.Addon objects:
id the add-on identifier, in reverse DNS style (string)
2018-10-11 03:11:00 +00:00
name the add-on “pretty name” (string)
2017-12-02 22:33:18 +00:00
version the add-on version (instance of addons.AddonVersion,
ghost)
2017-12-30 11:23:34 +00:00
authors the add-on authors (vector of addons.Author ghosts)
maintainers the add-on maintainers (vector of addons.Maintainer
ghosts)
2017-12-02 22:33:18 +00:00
shortDescription the add-on short description (string)
longDescription the add-on long description (string)
2017-12-25 20:19:01 +00:00
licenseDesignation licensing terms: "GNU GPL version 2 or later",
"CC0 1.0 Universal", etc. (string)
licenseFile relative, slash-separated path to a file under
the add-on base directory containing the license
text (string)
licenseUrl stable, official URL for the add-on license text
(string)
basePath path to the add-on base directory (string)
2018-03-21 07:39:47 +00:00
storagePath path to the add-on storage directory (string)
This is $FG_HOME/Export/Addons/ADDON_ID.
[added in FlightGear 2018.2]
2017-12-02 22:33:18 +00:00
minFGVersionRequired minimum required FG version for the add-on (string)
maxFGVersionRequired max. required FG version... or "none" (string)
homePage add-on home page (string)
downloadUrl add-on download URL (string)
supportUrl add-on support URL (string)
2017-12-25 20:19:01 +00:00
codeRepositoryUrl URL pointing to the development repository of
the add-on (Git, Subversion, etc.; string)
tags vector containing the add-on tags used to help
users find add-ons (vector of strings)
2017-12-02 22:33:18 +00:00
node base node for the add-on in the Property Tree:
2017-12-25 20:19:01 +00:00
/addons/by-id/ADDON_ID (props.Node object)
2017-12-02 22:33:18 +00:00
loadSequenceNumber 0 for the first registered add-on, 1 for the
second one, etc. (integer)
2018-01-10 13:13:25 +00:00
Member functions (methods) of addons.Addon objects:
2018-03-21 07:39:47 +00:00
createStorageDir() -> string
Create the add-on storage directory if it
doesn't already exist (that is,
$FG_HOME/Export/Addons/ADDON_ID). Return its
path as a string.
[added in FlightGear 2018.2]
2018-01-10 13:13:25 +00:00
resourcePath(string relPath) -> string
Return a resource path suitable for use with the
simgear::ResourceManager. 'relPath' must be
relative to the add-on base directory, and
2018-01-10 18:10:03 +00:00
mustn't start with a '/'. You can use this
method for instance to specify an image file for
display in a Canvas widget.
2018-01-10 13:13:25 +00:00
In you want a full path to the resource file
(e.g., for troubleshooting), call resolvepath()
with the return value of addons.Addon.resourcePath().
2017-12-02 22:33:18 +00:00
Read-only data members (attributes) of addons.AddonVersion objects:
majorNumber non-negative integer
minorNumber non-negative integer
patchLevel non-negative integer
suffix string such as "", "a1", "b2.dev45", "rc12"...
Member functions (methods) of addons.AddonVersion objects:
new(string version) | construct from string
new(int major, int minor=0, int patchLevel=0, | construct
string suffix="") | from components
str() | string representation
equal(addons.AddonVersion other) |
nonEqual(addons.AddonVersion other) | compare to another
lowerThan(addons.AddonVersion other) | addons.AddonVersion
lowerThanOrEqual(addons.AddonVersion other) | instance
greaterThan(addons.AddonVersion other) |
greaterThanOrEqual(addons.AddonVersion other) |
2017-12-30 11:23:34 +00:00
Read-only data members (attributes) of addons.Author objects:
name author name (non-empty string)
email email address of the author (string)
url home page of the author (string)
Read-only data members (attributes) of addons.Maintainer objects:
name maintainer name (non-empty string)
email email address of the maintainer (string)
url home page of the maintainer, if a person; if the
maintainer is a mailing-list, the URL can point
to a web page from which people can subscribe to
that mailing-list (string)
2017-12-02 22:33:18 +00:00
2018-12-05 11:33:58 +00:00
10. Add-on development; in-sim reload of Nasal code
---------------------------------------------------
!!! WARNING:
!!! The reload feature is meant for developers only, it should not be made
!!! visible to end users. Unexpected side effects may occur due to reload,
!!! if not implemented correctly.
!!! We really don't want users to send bug reports due to reload going wrong.
To make development of add-ons less time consuming, you can reload the
2018-12-10 14:24:03 +00:00
Nasal part of your add-on without having to restart FlightGear. When an
add-on is loaded, setlistener() and maketimer() wrappers are installed
in the add-on's own namespace; these wrappers shadow and call themselves
the standard setlistener() and maketimer() functions. The setlistener()
and maketimer() wrapper functions keep track of every listener and timer
they create. When the add-on is removed (e.g., as part of its reload
sequence), removelistener() is called for each of these listeners, and
each timer has its stop() method called.
_
2018-12-05 11:33:58 +00:00
For the time being, you have to track any other resources outside the
namespace of your add-on by yourself and clean them up in the unload()
function, e.g. delete canvas or close any files you opened.
You can define this unload() function in the addon-main.nas file. When
your add-on is reloaded, its unload() function, if defined, will be
called with one argument: the addons.Addon object (a Nasal ghost)
corresponding to your add-on. unload() is run in the add-on's own
2018-12-10 14:24:03 +00:00
namespace.
2020-04-17 07:46:06 +00:00
In FlightGear Versions before 2020.1 the reload is triggered by setting the
property /addon/by-id/ADDON_ID/reload to true (replace ADDON_ID with your
particular add-on identifier).
!!! Since version 2020.1 reload should be done like this:
!!! fgcommand("addon-reload", props.Node.new({'id': 'ADDON_ID'}));
You can add a menu item to trigger the reload easily, but it should be removed
before publishing your add-on to endusers (see the above warning).
2018-12-05 11:33:58 +00:00
Please have a look at the skeleton add-on at
https://sourceforge.net/p/flightgear/fgaddon/HEAD/tree/trunk/Addons/Skeleton/
2017-12-25 20:19:01 +00:00
Footnotes
---------
[1] \n represents end-of-line in string literals of languages such as C,
C++, Python and many others. We use this convention here to
represent the end-of-line character sequence in the XML data.
2017-12-02 22:33:18 +00:00
2017-12-25 20:19:01 +00:00
[2] MAJOR.MINOR.PATCHLEVEL[{a|b|rc}N1][.devN2] where MAJOR, MINOR and
2017-12-02 22:33:18 +00:00
PATCHLEVEL are non-negative integers, and N1 and N2 are positive
integers.
