/* * Stellarium * Copyright (C) 2008 Matthew Gates * * 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 @section introduction Introduction Plugins are extensions to Stellarium which are dynamically loaded into to the program at runtime. Plugins are potentially more powerful than 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. Stellarium plugins are created from C++ code compiled separately as a dynamic library ( .so on linux, .dll in windows or .dylib on MacOSX). A plugin should contain a main class deriving from the StelModule class as well as an instance of the StelPluginInterface which allows stellarium to dynamically load it. At startup, the StelModuleMgr will load the library (provided that the @c .dll is put at the proper place in the stellarium file tree), and an instance of the StelModule it contains will be instanciated and added to the list of other "normal" StelModules. Plugin developers - please note that while plugins are linked at runtime, classes used in plugins must inherit code from the core which is published under the GUN GPL. If you distribute a binary plugin, you must do so under the terms of the GNU GPL license. No sneaky closed-source shenanigans now. @section examplePlugins Example Plugins There are a few plugins which are written by and maintained by the Stellarium developer team.

HelloStelModule plugin: minimal plugin, intended as an example.
AngleMeasure plugin: simple plugin, intended as a guide to new developers.
CompassMarks plugin: simple plugin, intended as a guide to new developers.
VirGO plugin: fully featured extension to Stellarium sponsored by ESO. VirGO is used by professional astronomers to display and analyse data from the ESO archive. Follow this link for more info.

@section buildingPlugins Building Plugins The following instructions can be used to build the Angle Measure plugin and the Compass Marks plugin.

First, you will need to download the Stellarium source code from SVN, according to the instructions in the Stellarium build pages (see this page for *nix systems, and this page 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.
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
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.
Set an environment variable called @c STELROOT which contains the path to the Stellarium source code. @verbatim export STELROOT=/home/me/builds/stellarium @endverbatim
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
The rest of the build procedure should be simple
- On *nix systems: @verbatim cmake ../.. make make install @endverbatim
- On Windows: @verbatim cmake -G "MSYS Makefiles" ../.. make @endverbatim

To install the plugin on Linux systems, simple add a make install command after the @c make. This will copy the necessary files to $HOME/.stellarium/modules/AngleMeasure. 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:

@c module.ini file from the plugin source directory.
@c lib.so or @c lib.dll from the @c src sub-directory of the @c builds/unix or @c builds/msys directory in the plugin source directory.
Any other files which are needed for the plugin (there are no others for the example plugins at time of writing).