Freq source code
/===================\
|Scalograms are cool|
\===================/

The intention of this document is to explain how to fetch the source code with all the dependencies, how to setup a functional development environment, how to build the source code, how to run Freq and eventually how to distribute an installer.

Setting up the development environment requires quite a few steps. Please read through this document in its entirety.

Make sure you have a public release of Freq up an running on your computer before you start, to make sure your computer can actually run the program.


CUDA
----
If you don't intend to build releases with CUDA support you can skip this section.

Install the CUDA Toolkit from Nvidia. You might also want to install the SDK to experiment with CUDA development. Skip the "Drivers" on OS X 10.8!
http://developer.nvidia.com/cuda/cuda-downloads

The Drivers from the cuda-downloads page breaks Cuda in Mac!


CUDA in Ubuntu
--------------
(advanced: the devdrivers are needed for building because they include 'libcuda.so'. If you don't need to run the program but want to compile it you can extract libcuda.so from the devdriver installation package with the flag -x).

Create link to nvidia cuda compiler (nvcc) in path, and set library path for Cuda:

sudo su
ln -s /usr/local/cuda/bin/nvcc /usr/local/bin/nvcc
echo /usr/local/cuda/lib > /etc/ld.so.conf.d/cuda.conf
echo /usr/local/cuda/lib64 >> /etc/ld.so.conf.d/cuda.conf
ldconfig
exit


CUDA in Mac
-----------
To run the binary you need to make sure your LD_LIBRARY_PATH includes the path to the CUDA libraries. Add this line to ~/.bash_profile

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/cuda/lib/

OS X 10.8 Mountain Lion requires Cuda 5.0. This is not yet supported.


CUDA in Windows
---------------
Install the toolkit for 32-bit development, we don't have any 64-bit builds for Windows. If you want to try out the 64-bit toolkit you will need to change to value of the environment variable CUDA_LIB_PATH (created by the CUDA Toolkit installation program) to point 32-bit library files (also included in the 64-bit toolkit). Like so: %CUDA_PATH%lib\win32


Build environment for Ubuntu
----------------------------
The build environment will be initialized during 'Build and run'.

If you know want a more recent version of Qt Creator than the one in the Ubuntu repositories you can install it from here (later versions of Qt Creator usually work with prior versions of Qt libraries as well). If you choose this path you might want to uninstall the package 'qtcreator' after finishing 'Build and run'.
http://qt.nokia.com/downloads/downloads#qt-creator


Build environment for OS X
--------------------------
Make sure "Command line tools for Xcode" are installed.

Install Nokia open source QT Libraries 5.1 and QT Creator
http://qt.nokia.com/downloads/downloads#qt-lib
http://qt.nokia.com/downloads/downloads#qt-creator

Edit, build and debug using Qt Creator. Refer to 'Developing Freq' below for details.

Required libraries will be initialized during 'Build and run'.


Build environment for Windows
-----------------------------
Install Visual C++ 2008 Express:
http://www.microsoft.com/visualstudio/en-us/products/2008-editions/express

Install Nokia open source Qt Libraries and Qt Creator for VS 2008:
http://qt.nokia.com/downloads/downloads#qt-lib
http://qt.nokia.com/downloads/downloads#qt-creator

Install NSIS:
http://nsis.sourceforge.net/Download

Add the Qt bin folder to your path, for instance by adding this line to ~/.bashrc
PATH=$PATH:/c/Qt/4.8.2/bin

You might find it handy to also add an alias in ~/.bashrc for your favourite editor, like so:
alias edit='"C:\Program Files (x86)\Notepad++\notepad++.exe"'

Edit using qt creator. Build using Visual C++ 2008 Express for Win32. Other versions of Visual C++ than 2008 requires you to get the equivalent versions of the libraries in freq-winlib and might not support OpenMP.

Refer to 'Developing Freq' and 'Developing Freq in Windows' below for details on how to work with Qt Libraries, Qt Creator, and Visual C++.

Optional: There is a Qt integration for Visual Studio but it doesn't work with the Express version;
http://qt.nokia.com/downloads/visual-studio-add-in
http://qt-project.org/faq/answer/what_is_the_qt_visual_studio_add-in


Build and run
-------------
The default branch after a 'git clone' is 'master', this branch should contain the last stable release of Freq. All development is however based on a branch named 'develop'. See 'a-successful-git-branching-model'.

This command will fetch the required libraries for your system and then build and run Freq (this command performs initial setup. To build during everyday development it's recommended to follow "Developing Freq" further down instead):
./buildandrun.sh

Press enter to accept the default answer to the 4 initial questions about verifying repositories, making a clean build and uploading a compiled package.

In Linux you will be asked for your password when 'buildandrun.sh' tries to perform a 'sudo apt-get install' for required libraries the first time you run it.

When 'buildandrun.sh' has finished compiling it will start Freq. A complete rebuild may take between 1 and 15 minutes depending on the performance of your computer.

The intention of this document is that if you get an error while running this (i.e if 'buildandrun.sh' doesn't start Freq), the instructions above are missing something. Please document a fix if you find one, or document under what circumstances this guide doesn't work.


Developing Freq
--------------------
We use Qt Creator to edit the source code, the Qt framework for cross-platform GUI and cross-platform project configurations.

Strongly recommended reading (it's short): http://classes.soe.ucsc.edu/cmps160/Fall10/resources/qtexcerpt.pdf

Projects based on the Qt framework are defined by .pro-files. These are then compiled by 'qmake' into other platform-specific projects before they are sent to the compiler; i.e into Makefiles for the GNU Toolchain and into .vcproj or .vcxproj projects for Visual C++.

When you first open the project in Qt Creator it will create some user specific build preferences. In Windows it doesn't matter what you choose as you don't build within Qt Creator. Under OS X and Ubuntu it does however matter. Different preferences may work, but the most convenient setup for Freq development is probably to select options like this (note that different versions of Qt Creator look different):
- Select a toolchain that is known to work with Freq on your platform. (i.e most toolchains under Ubuntu but only 'GCC (x86 32bit)' under OS X).
- Select "Desktop" to do setup a desktop build.
- If it asks for you to import a build don't.
- Create build configurations: select "For Each Qt Version One Debug and And One Release".
- De-select "Shadow build".
- De-select "Embedded linux".

Note that builds created through the deploy scripts (in the 'dist' folder) have explicit settings and build configurations for pretty much everything to ensure that two releases from the same code base behave the same. This is not the case for your user settings in Qt Creator or builds from within Visual C++. Another difference is that the deploy scripts are adding some extra predefined C/C++ DEFINES in addition to your local 'default' build.


Developing Freq in OS X
----------------------------
We're using the GNU Toolchain on Mac, we're not using Xcode. qmake is however capable of generating .xcodeproj files for Xcode and defaults to that on Mac. So if you see such files it's an indication that something is wrong with your .pro files. You may of course feel free to experiment with the Xcode environment if you prefer that. We're using the GNU Toolchain simply because it is less work to maintain due to all the similarities to the equivalent toolchain under Linux (Ubuntu).

To build using the GNU Toolchain, add QMAKESPEC to your ~/.bash_profile like this:
export QMAKESPEC='macx-g++'

Build and debug using Qt Creator.
It's suggested to use Qt Creator to edit as well.


Developing Freq in Windows
-------------------------------
You need to manually run qmake whenever you've changed the Qt .pro project files to generate new project files for Visual C++ (this can be done from within Qt Creator as well as running 'qmake' in a 'git bash' window). These files are linked to by the Visual C++ solution at '/path/to/freq/quick/freq.sln'. Open the solution to build the project in Visual C++. Visual C++ project files should be regared as temporary files.

Run qmake using Qt Creator whenever the project has changed. This needs to be done for each subproject (gpumisc.pro and src.pro). The project is also changed when it's build configuration changes (i.e switching between building for CUDA to OpenCL to CPU or switching target from default to reader to hast). See more below regarding build configurations.

Build and debug using Visual C++.
It's suggested to use Qt Creator to edit.


Developing Freq in Ubuntu
------------------------------
Build and debug using Qt Creator.
It's suggested to use Qt Creator to edit as well.


Tests
-----
To run the test suite. Execute this in the folder 'tests':
./update-integration-tests.sh
./runtests.sh

For more info on running tests, see the runtests help:
./runtests.sh --help

For instance, to only run tests with 'mytest' in their name you can run:
./runtests.sh mytest

The argument to runtests.sh is parsed as regexp against the test name as it is written in the result list by runtests.sh.


Packaging/deployment
--------------------
To make a full release, merge into the master branch and run ./deploy-all-targets.sh from the folder 'dist'.


Packaging on Windows
--------------------
Install Wizou's XML plugin. To install the plugin, unzip the nsisXML.dll file from the bin directory into the corresponding directory of your NSIS installation.
http://wiz0u.free.fr/prog/nsisXML/


Build configurations
--------------------
Freq is build with several different build targets during a full deployment. For instance Freq is built as 'reader' and the full default version among others (see 'dist/deploy-all-targets.sh').

You can select a target other than the default target by adding to qmake (for the 'reader' target): CONFIG+=TARGET_reader

Freq is also built with CUDA support, OpenCL support and CPU fallback independently. This will likely change in the future. For instance, to build with cuda support add this to qmake: CONFIG+=usecuda

The the arguments to qmake change you need to do the same change to gpumisc (and to test projects or other projects based on those assumptions that you're working with). Remember in Windows that you need to run qmake for each project separately to create new Visual C++ project files.


Further questions
-----------------
Maintainer: johan@freq.consulting