AAOGlimpse
Other Links

AAOGlimpse Source code and Building


Overview


AAOGlimpse can be built for OS X, for Linux, or for Windows, all from the same set of source files.

The source for AAOGlimpse consists of a set of C++ and C files, together with AAOGlimpse.pro, which is a file used by Qt to control the way the project is built. The majority of the code in AAOGlimpse is completely system-independent. System dependencies are restricted to a small subset of files that use conditional compilation (#ifdef..#else..#endif blocks) to handle differences between the various operating systems. The AAOGlimpse.pro file has sections (called 'scopes' in Qt-speak) which are system-dependent.

Building AAOGlimpse consists of the following steps:

  1. Making sure the system has both Qt and OpenGL installed, together with a suitable C++ compiler.
  2. Making sure the system has the external libraries needed by AAOGlimpse. The cfitsio library, the wcslib library, and the libjpeg library are needed on all systems. AAOGlimpse can make use of the text facilities built in to Qt to draw strings in the OpenGL window, but if the FTGL library is available, it can make slightly more elaborate use of its facilities. So FTGL is optional, and a single line in the .pro file controls whether or not it is used. Being in C/C++, AAOGlimpse also needs the C/C++ run-time libraries - this is normally only an issue on Windows; most OS X and Linux systems will have these.
  3. Copying the AAOGlimpse files to a suitable working directory, and modifying the relevant section of the .pro file so it specifies the correct directories for the external libraries and their include files.
  4. Running the Qt 'qmake' program to create the AAOGlimpse project, and then building it, and running the resulting AAOGlimpse program to check that it works properly.
  5. If the program is to be copied to another computer running the same operating system it may need to be packaged with various run-time files - usually any shareable libraries. If FTGL is being used, these may need to include some font files as well.

All of these steps are reasonably straightforward, but all differ from system to system. There are separate sections in what follows for the three supported systems, OS X, Linux and Windows.

Building on OS X

1) Installing Qt, OpenGL, and C++ on OS X

OS X systems should all have OpenGL already installed.
The standard OS X C++ development system is XCode. I recommend installing this. It is a free installation on most OS X systems, and nowadays has to be downloaded from the Apple App Store, which makes it a straightforward installation. Qt works very nicely with XCode.
You need the full Qt SDK, downloaded from http://qt.nokia.com/downloads. You can download either an online or offline installer for OS X. On the same page, there are also links that let you download the Qt libraries for OS X. These will be needed by all machines on which AAOGlimpse is to run (although you can distribute these with the executable yourself). I'm not sure if you need to download these on the development system as well as the Qt SDK, but I did.

(I should note that I did the original AAOGlimpse development with Qt 4.8, and had no problems at all. However, a change to XCode introduced with version 4.6 has made Qt 4.8 incompatible with it and later XCode versions - as far as I know this is still the case -  so I recently moved to Qt 5, and found that this seems to have some teething problems that are slowly being sorted out. Qt 5.0 had problems with widgets losing focus that made it unusable for AAOGlimpse XCode. While most of this was fixed in Qt 5.1 there is still a problem with the XCode projects generated by qmake - I find that I can work around this by changing the compiler from 'Apple LLVM 4.2' to 'LLVM gcc 4.2' in the project build settings, but this spoils the rather nice continual checking of the code validity by the compiler. I believe this will be fixed in the next minor Qt 5.1 release, at which point things should be back to normal.)

2) Installing cfitsio, wcslib, libjpeg (and optionally, FTGL) on OS X

Cfitsio is Bill Pence's FITS file access library. Many systems used for astronomy will have it already installed. It's a standard, almost essential, piece of software. It can be downloaded from http://heasarc.gsfc.nasa.gov/fitsio/. For OS X, I downloaded the UNIX .tar file.

Wcslib is Mark Calabretta's World Coordinate library. It may also be already available on any system used for astronomy. If not, it can be downloaded from http://www.atnf.csiro.au/people/mcalabre/WCS/ as a .tar file.

Libjpeg is a library that provides access to JPEG files. It can be downloaded from http://www.ijg.org/ as a UNIX .tar file.

All three of these can be built by extracting the files from the .tar files, and then using the standard sequence of running "./configure" and then "make" from the command line. This will build the required .a library files in each case. Probably the best thing is then to install them, but in fact I simply set up the relevant INCLUDEPATH and LIBS lines in the AAOGLimpse.pro file to point to the directories in which I built the libraries.

If you want to use FTGL, which is a library that draws both 2D and 3D text strings in OpenGL windows, you can get it from http://sourceforge.net/projects/ftgl/develop. Again, it is a standard UNIX tar file, and can be built with "./configure" and "make", and I put the relevant LIBS and INCLUDEPATH lines in AAOGlimpse.pro. If you want to avoid using FTGL (and, frankly, all you miss is the sweep of the AAOGlimpse text banner around the screen on startup - after 10 seconds) all you have to do is remove the DEFINE line that sets GLIMPSE_TEXT_USE_FTGL from AAOGlimpse.pro. If you use FTGL, you also need the X11 include files and the freetype library that comes with X11. The lines in AAOGlimpse .pro that specify the X11 and freetype files should not need to be changed.

One thing I needed to do was rename the libftgl.dylib file to libftgl.dylib.hidden. Otherwise, it seems to be quite hard to prevent Xcode linking against it instead of the .a file, even when explicitly pointed at the .a file. (It always seems to prefer dynamic to static libraries, but this complicates running the program, particularly on other machines.)

3) Copy the AAOGlimpse files and modify the .pro file on OS X

The AAOGlimpse source files for version 1.5 can be downloaded from here. You need to modify some of the lines in the OS X specific section - the ones following the "macx {" line, as follows:

After all that, it gets easy.

4) Run 'qmake' and build the resulting project on OS X.

In a terminal window, cd to the directory with the AAOGlimpse.pro file, and type 'qmake'.
This produces a file called AAOGlimpse.xcodeproj.
Type 'open AAOGlimpse.xcodeproj'
XCode will open, all set up to build AAOGlimpse.
Select 'build' from the 'product' menu (or press command-b).
In principle, it should build cleanly. If not, it's most likely to be a problem with the INCLUDEPATH and LIBS lines in the .pro file. If so, fix them and repeat this step.
If it builds OK, select 'run' from the 'product' menu (or press command-r) and the program should run.

If not, there may be some error messages in the program output section of the XCode GUI. Failing to find a shareable library is one possibility. The command 'otool -L' can be run on the executable to list the shareable libraries and to see if they can be found. (The tricky bit is finding where Xcode has put the executable; click on 'Preferences' in the 'Xcode' menu and look at 'derived data'. Below the entry box, in small font, is the location, together with a tiny right arrow. Click on the arrow and the location is opened in the finder. Drag the executable to a terminal window to copy its full path into the command line. The .app file is actually a folder. The actual executable is AAOGLimpse.exe/Contents/MacOS/AAOGlimpse)

5) Running on another OS X computer

Built as described, the only shareable libraries needed by AAOGLimpse should be the Qt libraries. Qt provides a macdeployqt command which copies all the necessary shareable libraries into the executable. See the end of the previous section to see how to locate the .app file, and run 'macdeployqt AAOGlimpse.app'.

There's a lot of extra detail in http://qt-project.org/doc/qt-4.8/deployment-mac.html.

I have had problems where the font files used by FTGL are not in available on other OS X systems. At present, the code expects to find /Library/Fonts/Arial Bold.ttf and /Library/Fonts/Times New Roman.ttf. As of version 1.5, AAOGlimpse will fall back on the standard built-in Qt fonts if these are not found, so the program will continue to run. The only obvious difference will be that the sweeping 'AAO Glimpse' text seen with the startup display will not be seen.

Building on LINUX

1) Installing Qt, OpenGL, and C++ on Linux.

Linux systems will normally have the gcc compiler and linker and all the standard libraries installed.
You need OpenGL and the full Qt SDK. Most installations will provide these as standard packages that can be installed using the standard package installer.

2) Installing cfitsio, wcslib, libjpeg (and optionally, FTGL) on Linux.

Cfitsio is Bill Pence's FITS file access library. Many systems used for astronomy will have it already installed. It's a standard, almost essential, piece of software. It can be downloaded from http://heasarc.gsfc.nasa.gov/fitsio/. I downloaded the UNIX .tar file.

Wcslib is Mark Calabretta's World Coordinate library. It may also be already available on any system used for astronomy. If not, it can be downloaded from http://www.atnf.csiro.au/people/mcalabre/WCS/ as a .tar file.

Libjpeg is a library that provides access to JPEG files. It can be downloaded from http://www.ijg.org/ as a UNIX .tar file.

All three of these can be built by extracting the files from the .tar files, and then using the standard sequence of running "./configure" and then "make" from the command line. This will build the required .a library files in each case. Probably the best thing is then to install them, but in fact I simply set up the relevant INCLUDEPATH and LIBS lines in the AAOGLimpse.pro file to point to the directories in which I built the libraries.

If you want to use FTGL, which is a library that draws both 2D and 3D text strings in OpenGL windows, you can get it from http://sourceforge.net/projects/ftgl/develop. Again, it is a standard UNIX tar file, and can be built with "./configure" and "make", and I put the relevant LIBS and INCLUDEPATH lines in AAOGlimpse.pro. If you want to avoid using FTGL (and, frankly, all you miss is the sweep of the AAOGlimpse text banner around the screen on startup - after 10 seconds) all you have to do is remove the DEFINE line that sets GLIMPSE_TEXT_USE_FTGL from AAOGlimpse.pro. If you use FTGL, you also need the X11 include files and the freetype library that comes with X11. The lines in AAOGlimpse .pro that specify the X11 and freetype files should not need to be changed.

3) Copy the AAOGlimpse files and modify the .pro file on Linux.

The AAOGlimpse source files for version 1.5 can be downloaded from here. You need to modify some of the lines in the UNIX specific section - the ones following the "unix {" line.
If you aren't using FTGL, delete the DEFINES line that specifies GLIMPSE_TEXT_USE_FTGL. If you do that, you can also delete the INCLUDEPATH lines for ftgl, X11, and freetype2, and the LIBS lines for ftgl and freetype.
You need to make sure the INCLUDEPATH and LIBS lines point to the directories in which you can find the header and library files for the libraries you are using: cfitsio, wcslib, libjpeg and (optionally) ftgl.

After all that, it gets easy.

4) Run 'qmake' and build the resulting project on Linux.

In a terminal window, cd to the directory with the AAOGlimpse.pro file, and type 'qmake'.
This produces a Makefile.
Type 'make'.
And that should build AAOGlimpse.
./AAOGlimpse will run the program.

If the program builds but doesn't run, the problem may be a shareable library that can't be found. Try 'ldd AAOGlimpse' to see a list of all the shareable libraries used and their locations.

5) Running on another Linux computer

Built as described, the only shareable libraries needed by AAOGLimpse should be the Qt libraries, so in principle the AAGlimpse executable should run on any sufficiently similar Linux system (sorry if that's a bit vague - I've not yet had enough experience with trying AAOGlimpse on different Linux systems) that has the Qt shareable libraries. If you have problems, the first thing to try is 'ldd AAOGlimpse', as described in section 4).

Building on Windows


These notes are somewhat scrappier than the descriptions above for OS X and Linux. I'm not a regular Windows user, and I had to scramble about a bit to get AAOGLimpse built on Windows. I tried to keep notes of what I did, but in some places these proved to be a bit short on detail. I ended up with all the libraries I needed, and one day I will rebuild the whole thing from scratch on a Windows machine and keep proper notes. However, deep down, this is just a pretty normal Qt project with a .pro file already set up for Windows that uses three relatively straightforward libraries (well, two straightforward ones and Wcslib). Anyone used to building with Qt on Windows will find this much easier than I did.

1) Installing Qt, OpenGL, and C++ on Windows

Most of the building can be done directly from QtCreator, once downloaded, but it needs a C++ compiler. Microsoft has a confusing array of ways of buying its Visual C++ compiler and Visual Studio IDE, but the only free options are to download the Windows SDK or Visual Studio C++ 2010 Express. I used Visual Studio C++ 2010 Express, which gives you the Visual Studio IDE, but limits you to 32-bit compilations. The Windows SDK includes a 64 bit compiler, and I assume this can be used, but I've not experimented with it yet. When you install Qt, it configures itself for the compilers it finds. If you have no compilers on the system, it will set itself up to use the MinGW system - this is closer to a standard UNIX setup than is VC++, but the AAOGlimpse code has been set up to use VC++ rather than MinGW, on the assumption that this is what most builds will be using.

So download VC++ first. You then need the full Qt SDK, downloaded from http://qt.nokia.com/downloads. You can download either an online or offline installer for Windows.

The Windows setup for OpenGL is a little odd. Windows includes a very limited and outdated implementation, which can be extended through the drivers for specific cards. Most systems will in practice have very capable OpenGL support, but it will often need a file 'glext.h' which can be downloaded from http://www.opengl.org/registry/.

2) Installing cfitsio, wcslib, libjpeg (and optionally, FTGL) on Windows.

Cfitsio is Bill Pence's FITS file access library. Many systems used for astronomy will have it already installed. It's a standard, almost essential, piece of software. It can be downloaded from http://heasarc.gsfc.nasa.gov/fitsio/. This has good support for Windows, and you can download a proper Windows 7 installation that includes the necessary header file and a .dll library.

Wcslib is Mark Calabretta's World Coordinate library. It may also be already available on any system used for astronomy. If not, it can be downloaded from http://www.atnf.csiro.au/people/mcalabre/WCS/ as a .tar file. Wcslib is mainly a UNIX library, but I have managed to build a subset of it (all that AAOGlimpse needs) to run under Windows. The description of this is a bit to long to fit in here, so I've put it, together with a link to the modified code, here.

Libjpeg is a library that provides access to JPEG files. It can be downloaded from http://www.ijg.org/. There are specific instructions there for building with VC++ 2010. (These need 'nmake' and I found I had to download the Windows 7 SDK to get that, and I then had some messing about to get it into my INCLUDE path - I said I wasn't entirely au fait with Windows. Having done that, following the instructions builds a jpeg.sin, and clicking on that starts up Visual C++ with a 'jpeg' project that builds the library in a Release directory.)

On OS X and Linux, I also use FTGL, which is a library that draws both 2D and 3D text strings in OpenGL windows. You can get it from http://sourceforge.net/projects/ftgl/develop. However, I have not managed to get it to build properly under Windows - it is very much a UNIX library. Accordingly, I have removed the DEFINE line that sets GLIMPSE_TEXT_USE_FTGL from the Windows section of AAOGlimpse.pro. If anyone gets FTGL to work on Windows, the change to AAOGlimpse.pro to build AAOGlimpse with FTGL should be quite obvious (certainly, to anyone who can get FTGL to build properly!). As a result, AAOGlimpse on Windows uses the built-in Qt font handling, and hardly anyone notices the difference.

3) Copy the AAOGlimpse files and modify the .pro file on Windows

The AAOGlimpse source files for version 1.5 can be downloaded from here. You need to modify some of the lines in the Windows specific section - the ones following the "win32 {" line.
You need to make sure the INCLUDEPATH and LIBS lines point to the directories in which you can find the header and library files for the libraries you are using: cfitsio, wcslib, libjpeg and (optionally) ftgl.

After all that, it gets easy.

4) Run 'qmake' and build the resulting project on Windows.
Having copied over all the AAOGlimpse source files, just open up QtCreator, show it the various files and it creates a project that will then build and run.
5) Running on another Windows computer

If you want this version of AAOGlimpse to run on another Windows machine, you need to make sure it will have all the shareable libraries it needs on that machine. Windows looks for such libraries first in the folder from which it runs the executable program, so all you have to do is copy all the required libraries into the same folder as the executable, and then zip up the result and copy it to the other machine. The problem is gathering together all the required files.

I found I needed the following: QtCore4.dll, QtNetwork4.dll, cfitsio.dll, msvcr100.dll, QtGui4.dll, QtOpenGL4.dll and msvcp100.dll.

(I found I needed to get the 32-bit versions of most of these from C:\Windows\SysWOW64. I thought this was unintuitive, and made the following notes:

Which I think explains what goes on. I found DependencyWalker http://www.dependencywalker.com a huge help in sorting this out, and it's a very useful diagnostic tool if you have problems with Windows and shareable libraries.)

Understanding the source code


Unfortunately, that's a very big topic and not one I'm ready to address here. Some of the code is quite well commented, some isn't yet but will be eventually.

A few details about the interface between the system-dependent and system-independent layers of the program can be found in this page on interfaces.

Copyright issues


Traditionally, all AAO code has been released under words to the effect of "Copyright AAO, commercial use requires permission", and I have to release AAOGLimpse with the same wording. Just what this means in practice has really never been tested, and I'm releasing the source in the hope that others will find it useful and may improve on it. But be aware that, technically, it isn't actually open source. If this is an issue for anyone, contact me - ks at aao.gov.au.