wiki:GettingStarted
Last modified 9 months ago Last modified on 07/09/13 16:36:52

New Developers

Welcome, new developer! This page will help you get started using this site to help us develop Strata.

Getting the Code

First step is to download the Strata development code. To do this, you'll need Subversion, an open source version control system. You can download Subversion for all major platforms, including Linux, Windows, and MacOSX. If you're working on Windows, the Tortoise SVN package is particularly slick. It lets you control SVN functions via right-click menus as you navigate the file system. Subversion is similar to CVS, so if you've used that before, you'll feel right at home.

If you're just getting started with Subversion, check out this tutorial on nanoHUB.

Once Subversion is installed, you can download Strata as follows:

% svn checkout https://nees.org/tools/strata/svn/trunk strata

The checkout command makes a local copy of the entire Strata source tree into your current working directory as a subdirectory called strata. By requesting .../strata/svn/trunk, you get the main development trunk, which should have the latest stable code.

Dependencies

Strata depends on the following open source libraries:

Qt
cross-platform graphical user interface
Qwt
technical widgets for Qt
GSL
GNU Scientific Library used for random number generation
FFTW
Fastest Fourier Transform in the West
In addition to providing a graphical user interface, Qt provides an integrated development environment (IDE) that can be used to edit and compile Strata. Prior to building Strata, these libraries must be installed.

Linux Instructions

Installation of the required libraries is dependent on the linux distribution. For Debian based distributions (including Ubuntu), the following command will install all of the necessary files:

% sudo apt-get install libqt4-dev libqwt-dev libgsl0-dev libfftw3-dev 

Optionally, the Qt IDE can be installed with:

% sudo apt-get install qtcreator

After the dependencies have been installed, Strata can be built and run using the following commands:

% qmake
% make
% ./release/strata

The project file (strata.pro) includes support for the NEEShub systems, which might not work for all linux systems. The include path may have to be changed from:

INCLUDEPATH += . \
        "/usr/include/qwt" \
        \${GSL_INCLUDE}

to

INCLUDEPATH += . \
        "/usr/include/qwt"

Windows Instructions

Unfortunately, Windows does not have package management system so each of the components much be install individually. I install all of the required libraries under C:\devel\. For example, version 3.3 of the FFTW library would be stored in C:\devel\fftw-3.3. Using this convention, or another of your choosing, download and install windows binaries for each of the libraries.

Qt
http://qt.nokia.com/downloads
FFTW
http://www.fftw.org/install/windows.html
GSL
http://gnuwin32.sourceforge.net/packages/gsl.htm

There are no precompile binaries for Qwt. So we need to check out Qwt from the svn repository and compile it ourselves.

% svn checkout https://qwt.svn.sourceforge.net/svnroot/qwt/branches/qwt-5.2/ qwt-5.2

This should be done in C:\devel for your sanity. Next, we compile the library by executing the following commands from the terminal:

% C:
% cd C:\devel\qwt-5.2
% qmake
% mingw32-make all

If you get errors about qmake or mingw32-make not working use the Qt Command Prompt to ensure the path includes the required files.

We can then open the project with Qt Creator by opening the strata.pro file. The location of the library files listed in strata.pro may have to be modified to reflect path to the library files. For example, the following is the relevant section for libraries install to 'C:\devel\`.

LIBS += -lm \
    -lfftw3-3 \
    -L"C:/devel/fftw-3.2.2" \
    -lgsl \
    -lgslcblas \
    -L"C:/devel/GnuWin32/bin"
INCLUDEPATH += . \
    "C:/devel/fftw-3.2.2" \
    "C:/devel/qwt-5.2/src" \
    "C:/devel/GnuWin32/include"
RC_FILE = strata.rc
CONFIG(debug, debug|release ) {
    LIBS += -lqwtd5 \
	-L"C:/devel/qwt-5.2/lib"
} else {
    LIBS += -lqwt5 \
	-L"C:/devel/qwt-5.2/lib"
}

If FFTW version 3.3 was installed, the lines contain C:/devel/fftw-3.2.2 would need to be changed to C:/devel/fftw-3.3. Additionally, the PATH system variable has to be modified so that these libraries can be located. This modification is done by selecting Projects -> Build Settings -> Build Environment -> Details, and then editing PATH to include the paths to Qwt, FFTW, and GSL. This is an example of my PATH variable:

C:\devel\Qt\qtcreator-2.2.0\mingw\bin;C:\devel\Qt\4.7.3\bin;C:\Windows\system32;C:\Windows;C:\devel\qwt-5.2\lib;C:\devel\fftw-3.2.2;C:\devel\GnuWin32\bin

The project file makes use of python and svn to determine the svn revision number. If you are not interesting in including this information into the compiled program, it can be disable by modifying line 17 from:

DEFINES += REVISION=$$system(python getSvnVersion.py)

to:

DEFINES += REVISION=0

Mac OS X Instructions

On OS X, the required dependencies can be installed using a number of different methods. For simplicity, I recommend using MacPorts, which can be installed by following the directions here. Note, that MacPorts requires that XCode >4.1 be installed on the system. After MacPorts? is installed, open a Terminal by navigating to /Applications/Utilities? and double-clicking on Terminal. If you had a Terminal open prior to the MacPorts install you will need to open a new Terminal as the path information needs to be updated. Next install the required libraries

% sudo port install fftw-3 gsl-devel

We also need to install the Qt libraries, which can be done using MacPorts (sudo port install qt4-mac) or using the Qt online installer.

After the dependencies have been installed, Strata can't be built and run using the following commands:

% qmake
% make
% ./release/strata

The paths listed in strata.pro may need to be adjusted.

Making Changes

Once you've downloaded the code, you can make whatever changes you like. For example, you might edit a file to fix a bug or add some code. To make your changes permanent, you must commit them to the repository as follows:

% cd strata
% svn commit --message "fixed my first bug!"

You don't have to include the optional --message argument. If you just say svn commit, Subversion will prompt you for comments in your favorite editor, and you can type much more.

It's best to commit at the top of the source tree--that's why we said "cd strata" in the example above. When you commit at the top of the tree, Subversion will search everything below, find all files that have changed, and commit them all at once. Committing a change makes it permanent. Once committed, other developers will see the change. If for some reason, you want to throw away your changes and start fresh, you can simply remove your source tree and check it out all over again. Or, you may want to remove just a few files that you've modified, and then update (as we'll see below) to replace the missing files with their previous version.

If you want to add a new file or directory to your distribution, you can use the add command:

% svn add README.txt
% svn commit

Like any other change, the file is not really added until the next commit operation.

Similarly, if you want to remove a file or directory from your distribution, you can use the delete command:

% svn delete README.txt
% svn commit

Once the change is committed, the file will disappear. The file is still kept in the history, so it is not completely gone. But deleting the file will take it out of your way at least for this and future versions.

From time to time, you and another developer will modify the same file at the same time. Suppose the other developer checks in his changes first. When you try to commit, you'll get an error saying that your file is out-of-date. In that case, you need to update before committing. You can do that as follows:

% cd strata
% svn update

It's best to update at the top of the source tree--just like commit. That's why we said "cd strata" in the example above. When you update at the top of the tree, Subversion will search everything below, adding any new files, replacing any missing files, and integrating changes made by other developers. Once all files are properly updated, you can commit your changes again, and this time, it will work.