#+title: mcl-applications

* Introduction

This repository contains several applications that drive kernels generated by
[[https://github.com/JungleComputing/mcl][Many-Core Levels]] (MCL) for OpenCL and CUDA.  For a particular application,
there is a CUDA version and an OpenCL version.  Both these versions run a CPU
kernel and then the MCL kernel comparing the output.

* Directory structure

The repository contains a library directory ~lib~ with three libraries for I/O,
timing, and conveniently calling OpenCL applications.  Besides this, the
repository contains application directories, for example ~vectoradd~.  Each
application directory has three subdirectories:
- ~generic~
- ~cuda~
- ~opencl~
The ~generic~ directory contains C++ files that are used to drive both the
OpenCL and CUDA kernels.  The files in this directory are symlinked into ~cuda~
and ~opencl~.  The ~cuda~ and ~opencl~ directory contain a Makefile and the
output from MCL should be symlinked into this directory.  For example, for
vector addition, the MCL compiler creates a ~vectoradd~ directory that should
be symlinked or copied into this directory.  The Makefile will compile the
program.

To be able to compile the OpenCL and CUDA programs, it is first necessary to
compile the libraries in ~lib~.  For each library, go to the ~src~ directory
and run ~make~.

* Prerequisites

This application has the following prerequisites:

- A CUDA device, see the specifics below
- A CUDA installation with ~nvcc~
- make (tested with GNU make)

* Obtaining the code

We first clone and enter this repository:
#+begin_src sh
git clone https://github.com/JungleComputing/mcl-applications.git
cd mcl-applications
#+end_src

We then fetch the submodules:

#+begin_src sh
git submodule init
git submodule update
#+end_src

* Building code

Each applications has its own ~Makefile~ for both CUDA and OpenCL.  First it is
necessary to compile the shared libraries:

#+begin_src sh
cd lib/lib-io-data/src
make
cd -

cd lib/lib-opencl-wrapper/src
make
cd -

cd lib/lib-timer/src
make
cd -
#+end_src

Then it is necessary to symlink or copy the output from the MCL compiler.  For
example, for vector addition, we assume that the MCL compiler generated output
for OpenCL in ~$(MCL_OUTPUT_DIR)~.

#+begin_src lisp
cd vectoradd/opencl
ln -s $(MCL_OUTPUT_DIR)/vectoradd
#+end_src

We can then run ~make~

* Running the code

For example, for vector addition, to run an application, move to directory
~vectoradd/cuda~ or ~vectoradd/opencl~ and run:

#+begin_src sh
./vecadd
#+end_src