|Home · All Namespaces · All Classes · Functions · Coding Style · Scripting · Plugins · File Structure|
Plugins are extensions to Stellarium. They are potentially more powerful than scripts, but are more difficult to write and maintain. Unlike scripts, plugins must be compiled for a specific platform, and will typically only be compatible with a particular version of Stellarium.
We hope that the plugin system will allow third party developers to write extensions to Stellarium which might not otherwise be included in the core program, and that the system will allow for prototyping of new features before inclusion into the core.
Plugins can be built and used in two different ways:
.soextension on Linux,
.dllin Windows or
.dylibon Mac OS X) that are loaded at run-time (on start-up) by Stellarium. This allows dynamic plugins to be distributed separately from Stellarium.
As Stellarium's plugin interface has changed over time, plugins for different versions so far are not interchangeable. This is the reason why the official plugins have been linked statically to the official release.
Static plugins require changes in the core code of Stellarium (the addition of Qt macros in several classes). This is why adding a new static plugin requires either asking the developers to add it to the main distribution, or creating and distributing a custom build.
Dynamic plugin libriaries need to be installed in a proper place in Stellarium's file tree to function. Stellarium is looking for plugins in the
/modules subdirectory of the user data directory or the installation data directory. Each plugin library must be in its own subdiretory of the
/modules directory. If the plugin is called "MyPlugin", then its subdirectory should be also called
/MyPlugin and the main name (without the extension) of the plugin binary file should be
libMyPlugin. So, for example, the file tree should look like this on Windows XP:
C:/Documents and Settings/User/Application Data/Stellarium/(user data directory)
See the implementation of StelModuleMgr::getPluginsList() for more details.
A plugin should contain a main class deriving from the StelModule class as well as an instance of the StelPluginInterface which allows Stellarium to load it. At startup, the StelModuleMgr will load the library, and an instance of the StelModule it contains will be instantiated and added to the list of other "normal" StelModules.
Plugin developers - please note that classes used in plugins must inherit code from the core which is published under the GUN GPL. If you distribute a binary plugin, you must do so under the terms of the same GNU GPL license that Stellarium uses. No sneaky closed-source shenanigans now.
There are a few simple static plugins written and maintained by the Stellarium developer team that can serve as examples.
All static plugins incorporated in Stellarium's main code can be found in the /plugins subdirectory of Stellarium's code tree. Note that some of these plugins are under construction and have not been distributed yet with an official release.
There are also a few simple dynamic plugins. Their code is hosted in Stellarium's old Subversion repository at SourceForge.net:
VirGO is a fully featured extension to Stellarium sponsored by ESO. VirGO is used by professional astronomers to display and analyse data from the ESO archive. Follow the link for more information.
Note: The following section is mostly out of date. It applies to dynamic plugins.
The following instructions can be used to build the Angle Measure plugin and the Compass Marks plugin.
First, you will need to download the Stellarium source code from SVN, according to the instructions in the Stellarium build pages (see this page for *nix systems, and this page for Windows builds). For the rest of this discussion, I will assume you downloaded the source code in the directory
/home/me/builds/stellarium. If you put the source code somewhere else, you will need to modify the following instructions accordingly.
After downloading the stellarium source such that it is in
/home/me/builds/stellarium, change into the
/home/me/builds directory and fetch the
extmodules files from SVN. On Linux, you can use these commands to accomplish this:
cd /home/me/builds svn co https://stellarium.svn.sourceforge.net/svnroot/stellarium/trunk/extmodules
Build the main Stellarium program according to the instructions for your platform. Please note that you must build with the
Release settings, not the
Debug settings. You can do this by adding a step after doing
cmake. On Windows, use the
cmakegui tool, or on *nix use the
ccmake tool (or just edit the
CMakeCache.txt file) to set the value of
Release. Then continue with the
Set an environment variable called
STELROOT which contains the path to the Stellarium source code.
Change into the directory containing the plugin you want to build, then create a build directory. On *nix systems this should be called
builds/unix, on Windows it should be called
builds/msys. Once made, change into it. e.g. on Linux:
cd /home/me/builds/plugins/AngleMeasure mkdir -p builds/unix cd builds/unix
cmake ../.. make make install
cmake -G "MSYS Makefiles" ../.. make
To install the plugin on Linux systems, simple add a
make install command after the
make. This will copy the necessary files to
To install a plugin on Windows or OSX, you should locate the User Data Directory, and then create a sub-directory called
modules in it. Inside this, create a subdirectory named for the plugin, e.g.
AngleMeasure. Into this directory, you should copy the following files:
module.inifile from the plugin source directory.
lib<plugin-name>.dll from the
srcsub-directory of the
builds/msysdirectory in the plugin source directory.