When the changes in your branch are stable, merge them back to development:

# Clone the development branch if not already done:(~)git clone git@github.com:dash-project/dash.git -b development ./dash-development
# In the development branch, apply the changes in your feature branch:(~)cd dash-development
(~/dash-development)git pull origin feat-turing-test
(~/dash-development)git push origin development

To keep your branch in sync with development simply do:

(~)cd dash-feat-turing-test
(~)git merge development

There are more elegant ways to merge branches, but this variant always works and we don’t care too much about a streamlined git history for now.

Also, we don’t really follow an industry-style development procedure. We don’t need to and we don’t want to, because procedure bureaucracy just distracts from actual work.

Note: Good software developers don’t need software operation procedures. Know that agile methods are favored in the industry because they get average results from bad (ergo: cheap) coders, but they cripple the workflow of good software engineers (like us). Yes, seriously.

But we have some minimalistic workflow guidelines to coordinate our work. These are explained in the DASH Readme.

Getting Familiar with the DASH Code Base

The DASH code base might seem overwhelming if you never worked on a library project, but DASH is actually a pretty small library.

DASH Examples

Forget about the DART implementation (dart-if, dart-impl) for now, you don’t need them yet.

It’s probably a good idea to start from the user’s perspective:

How is DASH used to implement HPC applications?

Start by browsing the DASH example applications in dash/examples.

The example applications illustrate common use cases of DASH but don’t show all the gritty detail. Once you got familiar with the DASH style in the examples a bit, you can dive deeper and study the DASH unit tests.

A unit test implementation is not exactly self-explanatory, but it shows the full usage and peculiarities of a specific DASH type. For example, dash/test/ArrayTest.cc illustrates all available allocation methods provided by dash::Array.

DASH Implementation

Most of DASH is implemented in headers. Once you are somewhat familiar with the examples and some unit tests and want to know how the containers and algorithms are actually implemented, browse the headers in dash/include/dash/.

To get familiar with the DASH library code, start with the basic stuff: a one-dimensional, static container, namely dash::Array, and the algorithms using it.

Ignore the implementation of dash::GlobIter, dash::GlobPtr etc. for now.
They are iterators / pointers that can point to elements in memory at remote machines. That’s all you need to know for now.

Study the implementation of dash::Array and dash::for_each a bit. You will be delighted how simple things actually are. Well, at least for the most primitive data structure and the most basic algorithm.

Log output of DASH is formatted to simplify processing with standard command line tools like awk, sed and grep. This shell function can be used to print log messages of up to 4 units in different colors:

Debugging

Bugs in the DASH code are extremely rare of course as we conduct a formal proof of every line of code before committing it. In the unlikely event of unexpected behaviour, we describe a practicable way to debug your code using gdb in the following (via this article, a digest of this tutorial).

or by setting the flag -DCMAKE_BUILD_TYPE=Debug for the cmake build manually.

Insert the following code to make it wait for gdb attachment during runtime:

int DebugWait = 1;
while (DebugWait);

Launch the parallel program using mpiexec, make sure you know those computers on which processes are running.

Login to a computer, use the following bash commands to get a process id, and start gdb to attach to this process:

ps aux |grep program_name
gdb program_name process_id

First, enter <CTRL-X 1> or <CTRL-X 2> for a nice text-based GUI. As an alternative to gdbtui, we highly recommend the GDB Dashboard

The debugger will be stuck in the infinite loop, as intended.

Use the following gdb commands to break the waiting and continue executing the process.

<gdb> set DebugWait = 0
<gdb> continue

You might want to set a break point first to prevent the program from running to completion.

<gdb> b 123 # sets breakpoint at line 123 in current file<gdb> n # short for 'next', steps through program by single operations<gdb> c # short for 'continue', continues regular program run, will halt at next break point<gdb> print foo # show current value of variable 'foo'