Plugin Development

(Difference between revisions)
Jump to: navigation, search
(Windows)
m (Reverted edits by Jamesbzr (talk) to last revision by Alexwolf)
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
==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:
 +
* 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://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:
 +
;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.
  https://stellarium.svn.sourceforge.net/svnroot/stellarium/trunk/extmodules extmodules
+
  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''.
 
*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:
+
=== Creating the plug-in directory ===
*[http://www.stellarium.org/doc/head/plugins.html the "Plugins" page in Stellarium's online developers' documentation]
+
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()].
*The existing plugin's source code in subversion [http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk/extmodules/ browse it here]
+
 
*The stellarium-pubdevel mailing list - please fee free to subscribe and post questions there
+
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.
  

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