plugIns.doxygen   plugIns.doxygen 
/* /*
* Stellarium * Stellarium
* Copyright (C) 2008 Matthew Gates * Copyright (C) 2008 Matthew Gates
* Copyright (c) 2010 Bogdan Marinov
* *
* This program is free software; you can redistribute it and/or * This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License * modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either version 2 * as published by the Free Software Foundation; either version 2
* of the License, or (at your option) any later version. * of the License, or (at your option) any later version.
* *
* This program is distributed in the hope that it will be useful, * This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details. * GNU General Public License for more details.
skipping to change at line 26 skipping to change at line 27
* along with this program; if not, write to the Free Software * along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, U SA. * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, U SA.
*/ */
/*! /*!
@page plugins Plugins @page plugins Plugins
@section introduction Introduction @section introduction Introduction
Plugins are extensions to Stellarium which are dynamically loaded into to t he program at runtime. Plugins are extensions to Stellarium. They are potentially more powerful th an \ref scripting "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.
Plugins are potentially more powerful than scripts, but are more difficult to write and maintain. Unlike scripts, Plugins must be compiled for a speci fic platform, and will typically only be compatible with a particular versi on of Stellarium.
We hope that the plugin system will allow third party developers to write e xtensions to Stellarium which might not otherwise be included in the core p rogram, and that the system will allow for prototyping of new features befo re inclusion into the core. We hope that the plugin system will allow third party developers to write e xtensions to Stellarium which might not otherwise be included in the core p rogram, and that the system will allow for prototyping of new features befo re inclusion into the core.
Stellarium plugins are created from C++ code compiled separately as a dynam @section staticAndDynamicPlugins Static and Dynamic Plugins
ic library ( <tt>.so</tt> on linux, <tt>.dll</tt> in windows or <tt>.dylib< Plugins can be built and used in two different ways:
/tt> on MacOSX). A plugin should contain a main class deriving from the Ste - <b>dynamic plugins</b> are stand-alone dynamic libraries (separate files
lModule class as well as an instance of the StelPluginInterface which allow with <tt>.so</tt> extension on Linux, <tt>.dll</tt> in Windows or <tt>.dyl
s stellarium to dynamically load it. At startup, the StelModuleMgr will loa ib</tt> on Mac OS X) that are loaded at run-time (on start-up) by Stellariu
d the library (provided that the @c .dll is put at the proper place in the m. This allows dynamic plugins to be distributed separately from Stellarium
stellarium file tree), and an instance of the StelModule it contains will b .
e instanciated and added to the list of other "normal" StelModules. - <b>static plugins</b> are linked statically at build-time. They become "
built-in", a part of Stellarium's binary files. This is used to release fix
ed versions of some "official" plugins together with Stellarium's releases.
<em>Plugin developers - please note that while plugins are linked at runtim As Stellarium's plugin interface has changed over time, plugins for differe
e, classes used in plugins must inherit code from the core which is publish nt versions so far are not interchangeable. This is the reason why the offi
ed under the GUN GPL. If you distribute a binary plugin, you must do so un cial plugins have been linked statically to the official release.
der the terms of the GNU GPL license. No sneaky closed-source shenanigans
now.</em> 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 r
equires 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 Stellar
ium's \ref fileStructure "file tree" to function. Stellarium is looking for
plugins in the <tt>/modules</tt> subdirectory of the user data directory o
r the installation data directory. Each plugin library must be in its own s
ubdiretory of the <tt>/modules</tt> directory. If the plugin is called "MyP
lugin", then its subdirectory should be also called <tt>/MyPlugin</tt> and
the main name (without the extension) of the plugin binary file should be <
tt>libMyPlugin</tt>. So, for example, the file tree should look like this o
n Windows XP:
- <tt>C:/Documents and Settings/User/Application Data/Stellarium/</tt> (us
er data directory)
- <tt>modules/</tt>
- <tt>MyPlugin/</tt>
- <tt>libMyPlugin.dll</tt>
See the implementation of StelModuleMgr::getPluginsList() for more details.
@section code Coding
A plugin should contain a main class deriving from the StelModule class as
well as an instance of the StelPluginInterface which allows Stellarium to l
oad it. At startup, the StelModuleMgr will load the library, and an instanc
e of the StelModule it contains will be instantiated and added to the list
of other "normal" StelModules.
<em>Plugin developers - please note that classes used in plugins must inher
it code from the core which is published under the GUN GPL. <b>If you distr
ibute a binary plugin, you must do so under the terms of the same GNU GPL l
icense that Stellarium uses.</b> No sneaky closed-source shenanigans now.</
em>
@section examplePlugins Example Plugins @section examplePlugins Example Plugins
There are a few plugins which are written by and maintained by the Stellari um developer team. There are a few simple \b static plugins written and maintained by the Stel larium developer team that can serve as examples.
<ul> - <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/
<li><a href="http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk head%3A/plugins/HelloStelModule/">HelloStelModule plugin</a>: minimal plugi
/extmodules/HelloStelModule/">HelloStelModule plugin</a>: minimal plugin, i n, intended as an example.
ntended as an example.</li> - <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/file
<li><a href="http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk s/head%3A/plugins/AngleMeasure/">AngleMeasure plugin</a>: simple plugin, in
/extmodules/AngleMeasure/">AngleMeasure plugin</a>: simple plugin, intended tended as a guide to new developers.
as a guide to new developers.</li> - <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/file
<li><a href="http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk s/head%3A/plugins/CompassMarks/"> CompassMarks plugin</a>: simple plugin, i
/extmodules/CompassMarks/"> CompassMarks plugin</a>: simple plugin, intende ntended as a guide to new developers.
d as a guide to new developers.</li>
<li><a href="http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk All static plugins incorporated in Stellarium's main code can be found in t
/extmodules/VirGO/"> VirGO plugin</a>: fully featured extension to Stellari he <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/
um sponsored by ESO. VirGO is used by professional astronomers to display a head%3A/plugins/">/plugins</a> subdirectory of Stellarium's code tree. Note
nd analyse data from the ESO archive. Follow <a href="http://archive.eso.or that some of these plugins are under construction and have not been distri
g/cms/virgo/">this link</a> for more info.</li> buted yet with an official release.
</ul>
There are also a few simple \b dynamic plugins. Their code is hosted in Ste
llarium's old Subversion repository at SourceForge.net:
- <a href="http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk/e
xtmodules/ExampleDialog/">ExampleDialog</a> provides an example on how a pl
ugin can create a Stellarium-style window and add a button to the bottom to
ol bar.
- <a href="http://stellarium.svn.sourceforge.net/viewvc/stellarium/trunk/e
xtmodules/ExamplePainter/">ExamplePainter</a> provides an example on how a
plugin can draw on the viewport.
<a href="http://archive.eso.org/cms/virgo/">VirGO</a> is a fully featured e
xtension to Stellarium sponsored by ESO. VirGO is used by professional astr
onomers to display and analyse data from the ESO archive. Follow the link f
or more information.
@section buildingPlugins Building Plugins @section buildingPlugins Building Plugins
\b Note: The following section is mostly out of date. It applies to \b dyna
mic plugins.
The following instructions can be used to build the Angle Measure plugin an d the Compass Marks plugin. The following instructions can be used to build the Angle Measure plugin an d the Compass Marks plugin.
<ul> <ul>
<li>First, you will need to download the Stellarium source code from SVN, according to the instructions in the Stellarium build pages (see <a href="h ttp://www.stellarium.org/wiki/index.php/Compilation_on_Linux">this page</a> for *nix systems, and <a href="http://www.stellarium.org/wiki/index.php/Wi ndows_Build_Instructions">this page</a> for Windows builds). For the rest of this discussion, I will assume you downloaded the source code in the dir ectory @c /home/me/builds/stellarium. If you put the source code somewhere else, you will need to modify the following instructions accordingly.</li> <li>First, you will need to download the Stellarium source code from SVN, according to the instructions in the Stellarium build pages (see <a href="h ttp://www.stellarium.org/wiki/index.php/Compilation_on_Linux">this page</a> for *nix systems, and <a href="http://www.stellarium.org/wiki/index.php/Wi ndows_Build_Instructions">this page</a> for Windows builds). For the rest of this discussion, I will assume you downloaded the source code in the dir ectory @c /home/me/builds/stellarium. If you put the source code somewhere else, you will need to modify the following instructions accordingly.</li>
<li>After downloading the stellarium source such that it is in @c /home/me /builds/stellarium, change into the @c /home/me/builds directory and fetch the @c extmodules files from SVN. On Linux, you can use these commands to a ccomplish this: <li>After downloading the stellarium source such that it is in @c /home/me /builds/stellarium, change into the @c /home/me/builds directory and fetch the @c extmodules files from SVN. On Linux, you can use these commands to a ccomplish this:
@verbatim @verbatim
cd /home/me/builds cd /home/me/builds
svn co https://stellarium.svn.sourceforge.net/svnroot/stellarium/trunk/extm odules svn co https://stellarium.svn.sourceforge.net/svnroot/stellarium/trunk/extm odules
@endverbatim</li> @endverbatim</li>
skipping to change at line 92 skipping to change at line 117
@verbatim @verbatim
cmake -G "MSYS Makefiles" ../.. cmake -G "MSYS Makefiles" ../..
make make
@endverbatim</li> @endverbatim</li>
</ul> </ul>
</li> </li>
</ul> </ul>
To install the plugin on Linux systems, simple add a <tt>make install</tt> command after the @c make. This will copy the necessary files to <tt> $HOM E/.stellarium/modules/AngleMeasure</tt>. To install the plugin on Linux systems, simple add a <tt>make install</tt> command after the @c make. This will copy the necessary files to <tt> $HOM E/.stellarium/modules/AngleMeasure</tt>.
To install a plugin on Windows or OSX, you should locate the [[User Data Di rectory]], and then create a sub-directory called @c modules in it. Inside this, create a subdirectory named for the plugin, e.g. @c AngleMeasure. Int o this directory, you should copy the following files: To install a plugin on Windows or OSX, you should locate the User Data Dire ctory, and then create a sub-directory called @c modules in it. Inside this , create a subdirectory named for the plugin, e.g. @c AngleMeasure. Into th is directory, you should copy the following files:
<ul> <ul>
<li>@c module.ini file from the plugin source directory.</li> <li>@c module.ini file from the plugin source directory.</li>
<li>@c lib<plugin-name>.so or @c lib<plugin-name>.dll from the @c src sub- directory of the @c builds/unix or @c builds/msys directory in the plugin s ource directory.</li> <li>@c lib<plugin-name>.so or @c lib<plugin-name>.dll from the @c src sub- directory of the @c builds/unix or @c builds/msys directory in the plugin s ource directory.</li>
<li>Any other files which are needed for the plugin (there are no others f or the example plugins at time of writing).</li> <li>Any other files which are needed for the plugin (there are no others f or the example plugins at time of writing).</li>
</ul> </ul>
*/ */
 End of changes. 9 change blocks. 
33 lines changed or deleted 85 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/