Plugin Development

(Difference between revisions)
Jump to: navigation, search
(Windows dynamic linking error)
m (Reverted edits by Jamesbzr (talk) to last revision by Alexwolf)
(6 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
==Writing plugins==
 
==Writing plugins==
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 you are a developer, and would like to have a go at writing your own Stellarium plugin(s), the following resources might be helpful:
 
* the [[Plugins]] page in this wiki and the pages that it links to
 
* the [[Plugins]] page in this wiki and the pages that it links to
* the [http://www.stellarium.org/doc/head/plugins.html "Plugins" page in Stellarium's online developers' documentation] (as of 11 October 2010, it is sadly outdated)
+
* the [http://www.stellarium.org/doc/head/plugins.html “Plugins” page in Stellarium’s online developers’ documentation] (as of 11 October 2010, it is sadly outdated)
* the [https://lists.sourceforge.net/lists/listinfo/stellarium-pubdevel stellarium-pubdevel] mailing list - please fee free to subscribe and post questions there
+
* the [http://lists.sourceforge.net/lists/listinfo/stellarium-pubdevel stellarium-pubdevel] mailing list please fee free to subscribe and post questions there
  
 
Plug-ins can be compiled and used in two different ways:
 
Plug-ins can be compiled and used in two different ways:
* '''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
 
  
 
== Tips ==
 
== Tips ==

Revision as of 19:02, 2 June 2011

Contents

Writing plugins

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

Plug-ins can be compiled and used in two different ways:

Dynamic plug-ins
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.

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

Building and installing

These instructions apply only for dynamic plug-ins. Instructions for static plug-ins you can found here.

Linux

  • Build the core Stellarium code according to the Compilation on Linux page. Make sure the build sub-directory is called builds/unix.
  • Set the environment variable STELROOT to be the path of the stellarium source tree, for example:
export STELROOT=/home/bob/stellarium
  • Change to where you have the plugin source code installed, make a sub-directory builds/unix and change into it.
cd /home/bob/stel-plugins/PluginName
mkdir -p builds/unix
cd builds/unix
  • 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.
https://stellarium.svn.sourceforge.net/svnroot/stellarium/trunk/extmodules stel-plugins 
  • 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:
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.
cd /c/msys/1.0/home/bob/stel-plugins/<name of plugin>
mkdir -p builds/msys
cd builds/msys
  • 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.

Personal tools
Namespaces
Variants
Actions
in this wiki
other languages
Toolbox