;Dynamic plug-ins:Stand-alone dynamic libraries (separate files with <code>.so</code> extension on GNU/Linux, <code>.dll</code> in Windows or <code>.dylib</code> on Mac OS X) that are loaded at run-time by Stellarium. This allows plug-ins to be are distributed separately from Stellarium.

+

;Static plug-ins:Linked statically at build-time. They become “built-in”, a part of Stellarium’s binary files. This is used to release fixed versions of some “official” plug-ins together with Stellarium’s releases.

+

+

As Stellarium’s plug-in interface has changed over time, plug-ins for different versions are not interchangeable. This is the reason why the official plug-ins have been linked statically to the official release.

+

+

Nothing prevents someone from developing an independent static plug-in, but have in mind that this requires building a custom version of Stellarium. A much better choice, for an independent plug-in, is to make it dynamic.

+

+

If you want to propose a new plug-in to be added to the official ones and distributed with Stellarium, the best choice is to start a personal <code>Bazaar</code> branch of [http://www.launchpad.net/stellarium/ Stellarium in Launchpad], develop the plug-in in it and propose the branch for a merge into the trunk when you are read. ([http://code.launchpad.net/~daggerstab/stellarium/comets-asteroids-importer Example of what such a branch looks like])

+

+

==Example code==

+

Examples for static plug-ins are the "official" plug-ins and the HelloStelModule example plug-in. All can be found in the "plugins" subdirectory of Stellarium's trunk branch.

+

+

Examples for dynamic plug-ins can be found in the old Subversion repository at SourceForge.

+

+

For further information and links to those places, see the "[[How to get Stellarium's source code#Plug-ins|Plug-ins]]" section in [[How to get Stellarium's source code]].

+

==Building and installing==

==Building and installing==

+

These instructions apply only for dynamic plug-ins. Instructions for static plug-ins you can found [[Static Plugin Development|here]].

===Linux===

===Linux===

*Build the core Stellarium code according to the [[Compilation on Linux]] page. Make sure the build sub-directory is called ''builds/unix''.

*Build the core Stellarium code according to the [[Compilation on Linux]] page. Make sure the build sub-directory is called ''builds/unix''.

Line 16:

Line 40:

===Windows===

===Windows===

−

*To get the full suite of external modules source code enter this URL in the Tortoise SVN check out from your development root directory as you did for the stellarium source. This will create a folder containing all the subdirectories of plugin modules sources.

+

*To get the full suite of external modules source code enter this URL in the Tortoise SVN check out from your development root directory as you did for the stellarium source. This will create a folder "stel-plugins" containing all the subdirectories of plugin modules sources.

*Build the core Stellarium code according to the [[Windows Build Instructions]] page. Make sure the build sub-directory is called ''builds/msys''.

*Build the core Stellarium code according to the [[Windows Build Instructions]] page. Make sure the build sub-directory is called ''builds/msys''.

*Set the environment variable STELROOT to be the path of the stellarium source tree, for example:

*Set the environment variable STELROOT to be the path of the stellarium source tree, for example:

export STELROOT=/c/msys/1.0/home/bob/stellarium

export STELROOT=/c/msys/1.0/home/bob/stellarium

*Change to where you have the plugin source code installed, make a sub-directory ''builds/msys'' and change into it.

*Change to where you have the plugin source code installed, make a sub-directory ''builds/msys'' and change into it.

−

cd /c/msys/1.0/home/bob/stel-plugins

+

cd /c/msys/1.0/home/bob/stel-plugins/<name of plugin>

mkdir -p builds/msys

mkdir -p builds/msys

cd builds/msys

cd builds/msys

Line 29:

Line 53:

make

make

*Several of the plugins have a file called "installer.iss" in the main plugin directory. This can be used with the INNO installer generator to generate a windows installer for the plugin.

*Several of the plugins have a file called "installer.iss" in the main plugin directory. This can be used with the INNO installer generator to generate a windows installer for the plugin.

−

*NOTE: If the plugin source has been loaded into a clean folder the first call on Cmake -G "MSYS Makefiles" ../.. will generate a basic cmakecache.txt file. This may need to be edited to provide some more information. Some need to be directed to the boost files and the location of the path to qmake Qt/4.5.2/bin/qmake.exe. There is now a requirement to nominate whether to build the static or dynamic module. Also the generated lib??????.a file name will need to be the same as the file called in the stellarium//cmakecache.txt file

−

==Writing Plugins==

+

== Tips ==

−

If you are a developer, and would like to have a go at writing your own Stellarium plugin, the following resources might be helpful:

If your plug-in stores its configuration data in a subdirectory of "modules" (in the user data directory), make sure that this directory exists. This can be easily done with the static function [http://www.stellarium.org/doc/head/classStelFileMgr.html StelFileMgr::makeSureDirExistsAndIsWritable()].

For dynamic plug-ins, this is not strictly necessary, because to install the plug-in in the "modules" directory, such a sub-directory must be created by the install script. But when you are writing a static plug-in, or adapting a dynamic plug-in for static linking, don't forget that this time the directory does not exist by default!

−

== Windows dynamic linking error ==

+

=== Windows dynamic linking error ===

If a plugin uses a class that inherits a Stellarium class that contains the Q_OBJECT macro (for example, a dialog windows that inherits StelDialog), Stellarium will refuse to load it on Windows, returning an "Invalid access to memory location" error. The workaround is to copy the parent class (for example, StelDialog) to the plugin's sources and rename it appropriately.

If a plugin uses a class that inherits a Stellarium class that contains the Q_OBJECT macro (for example, a dialog windows that inherits StelDialog), Stellarium will refuse to load it on Windows, returning an "Invalid access to memory location" error. The workaround is to copy the parent class (for example, StelDialog) to the plugin's sources and rename it appropriately.

Stand-alone dynamic libraries (separate files with .so extension on GNU/Linux, .dll in Windows or .dylib on Mac OS X) that are loaded at run-time by Stellarium. This allows plug-ins to be are distributed separately from Stellarium.

Static plug-ins

Linked statically at build-time. They become “built-in”, a part of Stellarium’s binary files. This is used to release fixed versions of some “official” plug-ins together with Stellarium’s releases.

As Stellarium’s plug-in interface has changed over time, plug-ins for different versions are not interchangeable. This is the reason why the official plug-ins have been linked statically to the official release.

Nothing prevents someone from developing an independent static plug-in, but have in mind that this requires building a custom version of Stellarium. A much better choice, for an independent plug-in, is to make it dynamic.

If you want to propose a new plug-in to be added to the official ones and distributed with Stellarium, the best choice is to start a personal Bazaar branch of Stellarium in Launchpad, develop the plug-in in it and propose the branch for a merge into the trunk when you are read. (Example of what such a branch looks like)

Example code

Examples for static plug-ins are the "official" plug-ins and the HelloStelModule example plug-in. All can be found in the "plugins" subdirectory of Stellarium's trunk branch.

Examples for dynamic plug-ins can be found in the old Subversion repository at SourceForge.

Run cmake, specifying the build type to be the same as that which was used to build the core code (Debug or Release). Then run make

cmake -DCMAKE_BUILD_TYPE=Debug ../..
make

To install, just do:

make install

This will put the files for the plugin in ~/.stellarium/modules/PluginName

Windows

To get the full suite of external modules source code enter this URL in the Tortoise SVN check out from your development root directory as you did for the stellarium source. This will create a folder "stel-plugins" containing all the subdirectories of plugin modules sources.

Run cmake, specifying the build type to be the same as that which was used to build the core code (Debug or Release). Then run make

cmake -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Debug ../..
make

Several of the plugins have a file called "installer.iss" in the main plugin directory. This can be used with the INNO installer generator to generate a windows installer for the plugin.

Tips

Creating the plug-in directory

If your plug-in stores its configuration data in a subdirectory of "modules" (in the user data directory), make sure that this directory exists. This can be easily done with the static function StelFileMgr::makeSureDirExistsAndIsWritable().

For dynamic plug-ins, this is not strictly necessary, because to install the plug-in in the "modules" directory, such a sub-directory must be created by the install script. But when you are writing a static plug-in, or adapting a dynamic plug-in for static linking, don't forget that this time the directory does not exist by default!

Windows dynamic linking error

If a plugin uses a class that inherits a Stellarium class that contains the Q_OBJECT macro (for example, a dialog windows that inherits StelDialog), Stellarium will refuse to load it on Windows, returning an "Invalid access to memory location" error. The workaround is to copy the parent class (for example, StelDialog) to the plugin's sources and rename it appropriately.

Advice on how to solve this issue in another way will be much appreciated.