README_windows_qsas.txt
Steve Schwartz
16 July 2013

1 Purpose
2 Requirements
3 MinGW, MSYS, Qt4
4 CDF
5 Install QSAS source
6 Building QSAS
7 Running QSAS

1 Purpose
=========
This Readme file provides instructions for building QSAS, and any user-written plugins, on a Windows platform. It is an update of notes written originally by Alban Rochel. Evolution of qsas, windows, and toolchains (gcc, qt) have necessitated this update. On the positive side, it should now be easier for a user to build qsas on a windows platform.

These notes are based on my experience (July 2013) building QSAS on a 64-bit Windows 7 platform.

2 Requirements
==============
QSAS is built under gcc, and makes use of external toolkits, notably the Qt4 widget environment and NASA's cdf libraries. These need to be compatible with one another, which in practise means they need to be built from the same gcc system. We use the MSYS (minimal system) build environment and mingw (minimalist gnu for windows) implementation of gcc.

WARNING: Do NOT use the automated msys and mingw installation tools you will find on the web. You need matched installations of mingw and Qt, which is easiest to achieve by following the instructions below and using the mingw-builds repository of pre-built binaries.

You will need 7-zip or a similar windows application in order to unpack the various components you will need.

3 MinGW, MSYS, Qt4
==================
mingw and matching msys and Qt installations can be found at the MinGW-builds repository on sourceforge. You need the posix/sjlj version of mingw. Look under:

http://sourceforge.net/projects/mingwbuilds/files/host-windows/releases

to find, for example, 

/4.7.2/64-bit/threads-posix/sjlj/x64-4.7.2-release-posix-sjlj-rev8.7z

and check against the Qt builds at:

http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/Qt-Builds/

for a version of Qt4 that was built against the same gcc, e.g., in this case

http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/Qt-Builds/Qt-4.8.4-x64.7z/

There isn't anything I can see to ensure this is built against EXACTLY the right revison of mingw 4.7.2, but the datestamps suggest it's close. You'll need 7-zip or some other application which can unpack 7z files. The workflow below installs various components in C:/<name> but you could install them anywhere. You may prefer, for example, to install msys first and then install Qt, cdf, etc. in your msys /home directory.

1) Download MinGW and unpack it to, e.g., c:/MinGW
2) Download the matching Qt4 (NOT Qt5) and unpack it to, e.g., c:/Qt
3) Finally, download the matching msys+friends, e.g.

http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/msys%2B7za%2Bwget%2Bsvn%2Bgit%2Bmercurial%2Bcvs-rev8.7z/download

(check the date-stamp and also revision number - I assume that rev8.7 here matches the rev8.7 in the mingw directory).

Unpack msys into, e.g., c:/msys

4) execute the batch script msys.bat which you'll find in something like c:/msys/msys/1.0/msys.bat. Apart from other things, this will create a /home/<user> folder. If one isn't already there, create a file called .profile there (e.g., with an editor like Notepad++) and add a line like:

export PATH=/c/MinGW/bin:/usr/bin:/c/Qt/4.8.4/bin:${PATH}

This sets up our configuration to find everything you'll need. Msys provides a unix-like work environment including command-line tools, a standard Unix directory tree structure, etc. 

4 CDF
=====
Fetch the distributino of cdf from 

http://cdaweb.gsfc.nasa.gov/pub/software/cdf/dist/cdf34_1/windows/src_distribution/

E.g., download cdf34_1-dist-cdf.tar.gz from that directory.

Note, you want to pick up the windows src_distribution, not the pre-built libraries and tools. Unpack to, e.g., c:/cdf. You can do this with 7-zip. Alternatively, put the .tar.gz file in, say, /c/cdf, open an msys console and perform:

$ cd /c/cdf
$ tar -xvzf cdf34_1-dist-cdf.tar.gz

to unpack it. This may install the source in a sub-directory of /c/cdf, so you'll need to modify the next steps to locate the correct directory from which you can build cdf. You'll recognise it as the one which has several README and Note's, a Makefile, and a srsc directory.

Open a msys console (by running msys.bat) and make cdf your current working directory, e.g.,
$ cd /c/cdf

Then build cdf:

$ make OS=mingw ENV=gnu CURSES=no all

This will build the cdf libraries (but not the cdf applications such as cdfedit since msys as built by mingw-builds doesn't come with curses support). Finally, install the cdf libraries:

$ make INSTALLDIR=install_dir install

This will put all the necessary components of cdf in c:/cdf/install_dir

5 Install QSAS source
=====================
You are now ready to fetch, build, and install QSAS. Download the QSAS source, unpack it and extract it to, e.g., your msys home directory, say /home/<yourusername>/MYQSAS. Launch an msys command-line console via msys.bat and change directory to the qsas bin directory. This is probably in /c/MSYS/msys/1.0/home/<yourusername>/MYQSAS/QSAS/bin, which you can get to via:

$ cd MYQSAS/QSAS/bin

as your msys console should start up in your home directory.

Open the file build_win in a text editor (e.g. notepad++). You will need to adapt several lines in this to your configuration:

QS_HOME should point to the main QSAS directory, ie the one in which bin lives.
TARGET_XXXX these should point to the place where you want the final results to be located. We'll put it alongside the source, so that the various TARGET_XXXX directories all live inside QS_HOME.

CDF_INC and CDF_LIB need to point to the installed locations of the cdf include and lib folders. If you've followed the above example these will be /c/cdf/install_dir/include and /c/cdf/install_dir/lib.

QT_INCLUDE_XXX point to the corresponding Qt directories. Note that these need to be formatted in Windows notation, e.g.

export QT_INCLUDE_CORE=\"C:\\Qt\\4.8.4\\include\\QtCore\"

You should only need to change the top-level elements here, and then only if your Qt isn't in /c/Qt/4.8.4 but, say, /c/QtSDK/x64-4.8.4 or somesuch.

MOC lives in the Qt/bin directory. It is an executable that creates supplementary source files for Qt applications. Note that the format for it is unix style.

LD should point to the mingw c++ compiler/loader, e.g. "/c/mingw/bin/g++ -g"
CPL should point to your c++ compiler, which is the came as LD
CC should point to you c compiler, e.g., "/c/mingw/bin/gcc -g"

6 Building QSAS
===============
In your msys concole with QSAS/bin as your working direcoty perform:

$ ./build_win empty

to clean out any binaries or libraries that may get shipped with the QSAS distribution. Then

$ ./build_win qsas

should build QSAS. It will take some time to build.

7 Running QSAS
==============

Edit the file QSAS_win located in QSAS/bin so that the environment variable QSAS_HOME points to the top-level QSAS directory, e.g., /home/<yourusername>/MYQSAS/QSAS.

From an MSYS console, 

$ cd ~/MYQSAS/QSAS/bin
$ ./QSAS_win

This should launch the QSAS main window (Working List). Under File->Restore Session, navigate to your QSAS_HOME/tmp directory and choose the Sample_Session.qss folder. This will get you started.

Alternatively, edit the QSAS.bat file also located in QSAS/bin so that again QSAS_HOME points to your top-level QSAS installation. You can run this .bat file from an ordinary Windows command console, or place a shortcut to it on your desktop and launch by double-clicking.

Please send comments on this README and on other QSAS-related matters to: csc-support-dl@imperial.ac.uk.

Steve Schwartz
17 July 2013