* '''dynamic plug-ins''' are stand-alone dynamic libraries (separate files with .so extension on 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.

+

;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''' are 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.

+

;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.

+

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 stops you 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 independent plug-in is to make it dynamic.

+

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 create 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 what such a branch looks like: [http://code.launchpad.net/~daggerstab/stellarium/comets-asteroids-importer])

+

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==

==Example code==

Line 23:

Line 23:

==Building and installing==

==Building and installing==

−

These instructions apply only for dynamic plug-ins.

+

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 53:

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

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.