In this article, I'll assume that you're familiar with c/c++ and Qt. if not, there are plenty of complete tutorials and resources on the Internet.
As we wanted to modify Stellarium's telescope plugin to make it fit its use with Picastro, I was kind of afraid for Stellarium compilation. As you may know, it's often difficult for the average joe to compile open-source softwares, especially when no documentation is available. By chance, there is a lot of documentation for Stellarium. The bad part is that it's kind of out-dated, so you'll need to put your hands in dirt areas. Nothing impossible, through.
Download all the things !
The first thing to do is to get the Stellarium source code. Two ways are possible, depending on what you want to do. You can first download the current release source code, which is stable. Or you can download the "under development" source code. You'll conveniently use a CSV soft, Bazaar, to do this. To retrieve the updated version, you should go to the official web site . Click on Linux (Source), for the current version 1.3, will give you a link to the sourceforge project.
The second thing you'll do is to get the software QTCreator. Even it's not your favorite one, I didn't find an easy way to pass through it. (for example, you can't compile it with Microsoft Visual Studio compiler, since there are parts in the Stellarium source code that aren't compatible with this compiler). But as you'll probably see, it's a pretty nice IDE. Download the whole SDK, including the desktop compiler for QT, this is the one that will be used to compile stellarium. Install it under its default path (C:\QtSDK) and choose a custom installation. Under Development tools, only select the last Desktop QT for MinGW compiler. You can select the documentation of Qt as it will be a nice help if you're unfamiliar with Qt development process.
Then, there are 4 open source softwares you'll need for compiling stellarium, which are:
- CMAKE , that will create the project. It's not really a compiler, it only tells QTCreator how stellarium's code source is organized so QT compilers can do their job. Notice that in the official wiki, it is said that you can't compile directly on a win7 64b plateform directly, and that you must use a virtual xp computer. This information seems to be out-dated, as I was able to compile on my 3 Windows 7 64b computers. Just install Cmake in the default directory, and choose to add Cmake to your path.
Then, you'll need the 3 following softs, which are dependances for Stellarium (if you miss-installed them, you'll get an error at the CMAKE step). Those softs are :
- GETTEXT, for translating purpose,
- ICONV for character encoding conversion purpose,
- ZLIB, for compression purpose.
You should install the three last softwares on the same folder where the mingw compiler is. For me, it's "C:\QtSDK\mingw". Then, you must tell your computer where are all those compilers by adding to the PATH environment variable the path to needed binaries and include files (of course this will depends on the version of Qt you get):
C:\QtSDK\mingw\bin; C:\QtSDK\mingw\include; C:\QtSDK\mingw\lib; C:\QtSDK\Desktop\Qt\4.8.1\; C:\QtSDK\Desktop\Qt\4.8.1\mingw\bin; C:\QtSDK\Desktop\Qt\4.8.1\mingw\include; C:\QtSDK\Desktop\Qt\4.8.1\mingw\lib;
Setting up a Stellarium project in QTCreator
Ok then, launch QTCreator. open CMakeList.txt at the project's root (File/Open File or Project...). As it turns, QTCreator recognize this file "to be the descriptor file of the whole Stellarium project.
You can select a build location, to keep your source code clean. You'll also be asked to select a project compiler : Select the default one (MinGW Generator (Mingw as a GCC for Windows targets). Launch the project creation ("Run CMake"). If there are errors here, make sure you didn't forgot any step described above. Verify the different paths (bin folders must contain exe and dll files, include header files, and lib .lib, or .a files. Some error can appear, but if nothing turns red, its OK.
You now have to say QTCreator that your runtime environment is the project's root. To do this, go under the Projects tab (on the left side of the Window), and got to the runtime parameters tab. As a folder repertory, put the folder where you unzipped the Stellarium sources.
After this, you should be able to build the project (Build/Build project "Stellarium") You'll see in the "Compile Output" the process details. There are lot of warnings you shouldn't be afraid of. You can launch your project (Build/Run). Now is the time when you are very happy to see your own Stellarium compilation running !
About debugging : The most annoying thing about this is that I wasn't able to find a way to use the debugger with Stellarium. Anyways, there are plenty of tools in Stellarium that allow you to write messages or TextBoxes to debug in an "old school" way. If you know a way to use a debugger, I'm really interested ...
Distribute your work
So, you made a very nice static plugin and want to distribute it to your friends or even the rest of the world ? Nothing easier. First you must have launched QTCreator as an administrator. Then, under the Projects tab, in the Compilation parameters, add an argument to the existing compilation step (mingw32-make.exe) , "-install". This will install your freshly compiled Stellarium under the program files folder. Next thing to do is to download inno setup, in order to package the whole thing. So open Inno Setup, and Open a New Script File. Use the stellarium.iss script (you can find it at the root folder of the sources). This is an auto generated file (at the CMake step), but in my case, this file has a little problem. Two lines are corrupted and need to be changed manually (don't worry, it's not really hard as it's just a problem with two files paths. You'll have at the end a very nice installer file easy to share.