==============================
Obtain the Project from GitHub                                          [TOC]
==============================

The project __ulmBLAS__ is hosted at __GitHub__.  We use different branches for
analyzing certain aspects of the matrix-matrix multiplication.

Obtain
======
#
#   Cleanup previous directory
#
    *--[SHELL(hide)]----------------------------------------------------*
    |                                                                   |
    | rm -rf ulmBLAS/                                                   |
    |                                                                   |
    *-------------------------------------------------------------------*

First clone the __ulmBLAS__ repository from __GitHub__:

    *--[SHELL]----------------------------------------------------------*
    |                                                                   |
    |  git clone https://github.com/michael-lehn/ulmBLAS.git            |
    |                                                                   |
    *-------------------------------------------------------------------*

You now have a new subdirectory `ulmBLAS`.


Select a Branch
===============
Now change into the directory `ulmBLAS`  and use `git branch -a` for displaying
all branches hosted on GitHub:

    *--[SHELL]----------------------------------------------------------*
    |                                                                   |
    |  cd ulmBLAS                                                       |
    |  git branch -a                                                    |
    |                                                                   |
    *-------------------------------------------------------------------*

With `git checkout -b LOCAL_BRANCH  REMOTE_BRANCH you can select a branch and
switch to it.  For example:

    *--[SHELL(path=ulmBLAS)]--------------------------------------------*
    |                                                                   |
    |  git checkout -B demo-pure-c remotes/origin/demo-pure-c           |
    |                                                                   |
    *-------------------------------------------------------------------*


Compile
=======
We have simple makefiles: `make` will compile and build everything

    *--[SHELL(path=ulmBLAS,height=15)]----------------------------------*
    |                                                                   |
    |  make                                                             |
    |                                                                   |
    *-------------------------------------------------------------------*


Structure of the Project
========================
The `ulmBLAS` project has basically four important components:

  - In `src/` the actually `ulmBLAS` library gets built.  Actually we build the
    library twice.  The resulting libraries are `libulmblas.a` and
    `libatlulmblas.a`.  The only difference between these two variants are the
    prefixes and suffixes of the symbol names.

    `libulmblas.a` exports symbol names like a regular Fortan 77 BLAS
    implementation, e.g. for `dgemm` we have

    *--[SHELL(path=ulmBLAS)]--------------------------------------------*
    |                                                                   |
    |  nm libulmblas.a | grep dgemm | grep T                            |
    |                                                                   |
    *-------------------------------------------------------------------*

    `libulmblas.a` exports symbol names like ATLAS.  So when we link against the
    ATLAS benchmark suite we can pretend to be the __ATLAS__ library.  For
    `dgemm` we have the following  symbols

    *--[SHELL(path=ulmBLAS)]--------------------------------------------*
    |                                                                   |
    |  nm libatlulmblas.a | grep dgemm | grep T                         |
    |                                                                   |
    *-------------------------------------------------------------------*

  - In `refblas/` the reference implementation (taken from __Netlib__) is
    located.  We use is for testing and as a reference for measuring speedups
    in the benchmarks.  The resulting library is `librefblas.a`.  Looking
    at the exported symbol for `dgemm` gives

    *--[SHELL(path=ulmBLAS)]--------------------------------------------*
    |                                                                   |
    |  nm librefblas.a | grep dgemm | grep T                            |
    |                                                                   |
    *-------------------------------------------------------------------*

  - In `test/` we have the BLAS test suite from __Netlib__.  With
    `make check_ulm` you can test `libulmblas.a`.
  - In `bench/` we have the benchmark suite from __ATLAS__.  Note that this is
    actually only the benchmark suite (about 40 files) ripped out from
    __ATLAS__.  We are not using the BLAS implementation of ATLAS itself.

    In `bench/Makefile` you can use the variables `ATLAS_LIB` and `REF_LIB`
    to compare the performance of two BLAS libraries.  E.g. here we compare
    `libatlulmblas.a` with `librefblas.a`:

    :import: ulmBLAS/bench/Makefile [linenumbers]

:links:  ulmBLAS -> https://github.com/michael-lehn/ulmBLAS
         GitHub  -> https://github.com
         Netlib  -> http://netlib.org
         ATLAS   -> http://math-atlas.sourceforge.net

:navigate: __up__    -> doc:index
           __next__  -> doc:page02/index