plugIns.doxygen

/*
 * Stellarium
 * Copyright (C) 2008 Matthew Gates
 * Copyright (c) 2010 Bogdan Marinov
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */

/*!

@page plugins Plugins

@tableofcontents

@section introduction Introduction

Plugins are extensions to Stellarium. They are potentially more powerful than \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.

We hope that the plugin system will allow third party developers to write extensions to Stellarium which might not otherwise be included in the core program, and that the system will allow for prototyping of new features before inclusion into the core.

@section staticAndDynamicPlugins Static and Dynamic Plugins
Plugins can be built and used in two different ways: 
 - <b>dynamic plugins</b> are stand-alone dynamic libraries (separate files with <tt>.so</tt> extension on Linux, <tt>.dll</tt> in Windows or <tt>.dylib</tt> on Mac OS X) that are loaded at run-time (on start-up) by Stellarium. This allows dynamic plugins to be distributed separately from Stellarium.
 - <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 fixed versions of some "official" plugins together with Stellarium's releases.

As Stellarium's plugin interface has changed over time, plugins for different versions so far are not interchangeable. This is the reason why the official plugins have been linked statically to the official release.

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 requires 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 Stellarium's \ref fileStructure "file tree" to function. Stellarium is looking for plugins in the <tt>/modules</tt> subdirectory of the user data directory or the installation data directory. Each plugin library must be in its own subdiretory of the <tt>/modules</tt> directory. If the plugin is called "MyPlugin", 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 on Windows XP:
 - <tt>C:/Documents and Settings/User/Application Data/Stellarium/</tt> (user data directory)
  - <tt>modules/</tt>
   - <tt>MyPlugin/</tt>
    - <tt>libMyPlugin.dll</tt>

On Windows 7 and later, this would be:	
 - <tt>C:/Users/&lt;YOU&gt;/AppData/Roaming/Stellarium/</tt> (user data directory)
  - <tt>modules/</tt>
   - <tt>MyPlugin/</tt>
    - <tt>libMyPlugin.dll</tt>
	
See the implementation of StelModuleMgr::getPluginsList() for more details.

@section listPlugins List of Static Plugins
You can find some details for static plugins in each item of the list of plugins:
 - @ref angleMeasure
 - @ref compassMarks
 - @ref oculars
 - @ref telescopeControl
 - @ref satellites
 - @ref quasars
 - @ref pulsars
 - @ref exoplanets
 - @ref observability
 - @ref brightNovae
 - @ref historicalSupernovae
 - @ref equationOfTime
 - @ref navigationalStars
 - @ref meteorShowers
 - @ref fieldOfView
 - @ref pointerCoordinates
 - @ref scenery3D
 - @ref archaeoLines
 - @ref remoteControl
 - @ref remoteSync

You can find some untechnical details on our wiki [Plugins](http://www.stellarium.org/wiki/index.php/Plugins) page.

@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 load it. At startup, the StelModuleMgr will load the library, and an instance of the StelModule it contains will be instantiated and added to the list of other "normal" StelModules.

A plugin can interact with the users in many ways, not limited to:
 - painting directly on the viewport like other StelModules (see the examples below);
 - defining [QActions](http://doc.qt.io/qt-5/qaction.html) triggered with keyboard shortcut combinations with StelGui::addGuiActions();
 - buttons (StelButton) added to the bottom button bar (BottomStelBar; see the examples below);
 - windows (subclasses of StelDialog) that can be designed with %Qt's UI editor (see the examples and the configuration windows of the official plugins);
 - custom controls displayed anywhere on the screen based on any of the classes that inherit [QGraphicsItem](http://doc.qt.io/qt-5/qgraphicsitem.html) (see [the documentation of Qt's Graphics View Framework](http://doc.qt.io/qt-5/qgraphicsview.html)). To get a base widget to work on, use StelGui::getSkyGui().

<em>Plugin developers - please note that classes used in plugins must inherit code from the core which is published under the GNU GPL. <strong>If you distribute a binary plugin, you must do so under the terms of the same GNU General Public License that Stellarium uses</strong> (as of August 2011, this is GNU GPL "version 2 or any later version"). No sneaky closed-source shenanigans now.</em>

@section examplePlugins Example Plugins

There are a few simple \b static plugins written and maintained by the Stellarium developer team that can serve as examples.

 - <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/head%3A/plugins/HelloStelModule/">HelloStelModule plugin</a>: minimal plugin, intended as an example.
 - <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/head%3A/plugins/SimpleDrawLine/">SimpleDrawLine</a>: minimal plugin for drawing lines.
 - <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/files/head%3A/plugins/AngleMeasure/">AngleMeasure plugin</a>: simple plugin, intended as a guide to new developers.
 - <a href="http://bazaar.launchpad.net/%7Estellarium/stellarium/trunk/files/head%3A/plugins/CompassMarks/"> CompassMarks plugin</a>: another simple plugin intended as a guide to new developers.

All static plugins incorporated in Stellarium's main code can be found in the <a href="http://bazaar.launchpad.net/~stellarium/stellarium/trunk/files/head%3A/plugins/">/plugins</a> subdirectory of Stellarium's code tree. Note that some of these plugins are under construction and have not been distributed yet with an official release.

There are also a few simple \b dynamic plugins. Their code is hosted in Stellarium's old Subversion repository at SourceForge.net:
 - <a href="http://sourceforge.net/p/stellarium/code/HEAD/tree/trunk/extmodules/ExampleDialog/">ExampleDialog</a> provides an example on how a plugin can create a Stellarium-style window and add a button to the bottom tool bar.
 - <a href="http://sourceforge.net/p/stellarium/code/HEAD/tree/trunk/extmodules/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 extension to Stellarium sponsored by ESO. VirGO is used by professional astronomers to display and analyse data from the ESO archive. Follow the link for more information.

@section buildingPlugins Building Plugins

\b Note: The following section is mostly out of date. It applies to \b dynamic plugins.

The following instructions can be used to build the Angle Measure plugin and the Compass Marks plugin.

<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="http://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/Windows_Build_Instructions">this page</a> for Windows builds).  For the rest of this discussion, I will assume you downloaded the source code in the directory @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 accomplish this:
@verbatim
cd /home/me/builds
svn co https://stellarium.svn.sourceforge.net/svnroot/stellarium/trunk/extmodules
@endverbatim</li>
 
 <li>Build the main Stellarium program according to the instructions for your platform.  Please note that you must build with the @c Release settings, not the @c Debug settings.  You can do this by adding a step after doing @c cmake. On Windows, use the @c cmakegui tool, or on *nix use the @c ccmake tool (or just edit the @c CMakeCache.txt file) to set the value of @c CMAKE_BUILD_TYPE to @c Release.  Then continue with the @c make stage.</li>
 
 <li>Set an environment variable called @c STELROOT which contains the path to the Stellarium source code.
@verbatim
export STELROOT=/home/me/builds/stellarium
@endverbatim</li>
 
 <li>Change into the directory containing the plugin you want to build, then create a build directory.  On *nix systems this should be called @c builds/unix, on Windows it should be called @c builds/msys.  Once made, change into it. e.g. on Linux:
@verbatim
cd /home/me/builds/plugins/AngleMeasure
mkdir -p builds/unix
cd builds/unix
@endverbatim</li>

 <li>The rest of the build procedure should be simple
 <ul>
  <li>On *nix systems:
@verbatim
 cmake ../..
 make
 make install
@endverbatim </li>
  <li>On Windows:
@verbatim
 cmake -G "MSYS Makefiles" ../..
 make
@endverbatim</li>
 </ul>
 </li>
</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> $HOME/.stellarium/modules/AngleMeasure</tt>.

To install a plugin on Windows or OSX, you should locate the User Data Directory, 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 this directory, you should copy the following files:
<ul>
 <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 source directory.</li>
 <li>Any other files which are needed for the plugin (there are no others for the example plugins at time of writing).</li>
</ul>

*/