starpu-max/README

++=================++
|| I. Introduction ||
++=================++

+---------------------
| I.a. What is StarPU?

StarPU is a runtime system that offers support for heterogeneous multicore
machines. While many efforts are devoted to design efficient computation kernels
for those architectures (e.g. to implement BLAS kernels on GPUs or on Cell's
SPUs), StarPU not only takes care of offloading such kernels (and implementing
data coherency across the machine), but it also makes sure the kernels are
executed as efficiently as possible.

+------------------------
| I.b. What StarPU is not

StarPU is not a new language, and it does not extends existing languages either.
StarPU does not help to write computation kernels.

+---------------------------------
| I.c. (How) Could StarPU help me?

While StarPU will not make it easier to write computation kernels, it does
simplify their actual offloading as StarPU handle most low level aspects
transparently.

Obviously, it is crucial to have efficient kernels, but it must be noted that
the way those kernels are mapped and scheduled onto the computational resources
also affect the overall performance to a great extent.

StarPU is especially helpful when considering multiple heterogeneous processing
resources: statically mapping and synchronizing tasks in such a heterogeneous
environment is already very difficult, making it in a portable way is virtually
impossible. On the other hand, the scheduling capabilities of StarPU makes it
possible to easily exploit all processors at the same time while taking
advantage of their specificities in a portable fashion.

++==================++
|| II. Requirements ||
++==================++

 * make
 * gcc (version >= 4.1)
 * if CUDA support is enabled
   * CUDA (version >= 2.2)
   * CUBLAS (version >= 2.2)
 * if OpenCL support is enabled
   * AMD SDK >= 2.3 if AMD driver is used
   * CUDA >= 3.2 if NVIDIA driver is used
 * extra requirements for the svn version (we usually use the Debian testing
   versions)
   * autoconf (version >= 2.60)
   * automake
   * makeinfo

 * Remark: It is strongly recommanded that you also install the hwloc library
   before installing StarPU. This permits StarPU to actually map the processing
   units according to the machine topology. For more details on hwloc, see
   http://www.open-mpi.org/projects/hwloc/ .

++=====================++
|| III. Getting StarPU ||
++=====================++

StarPU is available on https://gforge.inria.fr/projects/starpu/.

The project's SVN repository can be checked out through anonymous
access with the following command(s).

$ svn checkout svn://scm.gforge.inria.fr/svn/starpu/trunk
$ svn checkout --username anonsvn https://scm.gforge.inria.fr/svn/starpu/trunk

The password is 'anonsvn'

++=============================++
|| IV. Building and Installing ||
++=============================++

+---------------------------
| IV.a. For svn version only

  $ ./autogen.sh

+-----------------------
| IV.b. For all versions

  $ ./configure
  $ make
  $ make install

+---------------------
| IV.c. Windows build:

StarPU can be built using MinGW or Cygwin.  To avoid the cygwin dependency,
we provide MinGW-built binaries.  The build process produces libstarpu.dll,
libstarpu.def, and libstarpu.lib, which should be enough to use it from e.g.
Microsoft Visual Studio.

A few details need to be fixed when building StarPU on windows:

- To get a .def file built, make sure that MSVC's lib.exe tool is in PATH.

- Update the video drivers to the latest stable release available for your
  hardware. Older ATI drivers (< 2.3) contain bugs that cause OpenCL support in
  StarPU to hang or exhibit incorrect behaviour.

- c:\cuda\include\host_defines.h has a bogus CUDARTAPI definition which makes
  linking fail completely. Replace the first occurence of

    #define CUDARTAPI
    
  with
    
    #ifdef _WIN32
    #define CUDARTAPI __stdcall
    #else
    #define CUDARTAPI
    #endif

  While at it, you can also comment the __cdecl definition to avoid spurious
  warnings.

- If you have a non-english version of windows, use

    export LANG=C

  else libtool has troubles parsing the translated output of the toolchain.

- libtool is not able to find the libraries automatically, you need to make some
  copies:

    copy c:\cuda\lib\cuda.lib c:\cuda\lib\libcuda.lib
    copy c:\cuda\lib\cudart.lib c:\cuda\lib\libcudart.lib
    copy c:\cuda\lib\cublas.lib c:\cuda\lib\libcublas.lib
    copy c:\cuda\lib\cufft.lib c:\cuda\lib\libcufft.lib
    copy c:\cuda\lib\OpenCL.lib c:\cuda\lib\libOpenCL.lib

++===========++
|| V. Trying ||
++===========++

Some examples ready to run are installed into $prefix/lib/starpu/{examples,mpi}

++=============++
|| VI. Upgrade ||
++=============++

To upgrade your source code from older version (there were quite a few
renamings), use the tools/rename.sh script

++==============++
|| VII. Contact ||
++==============++

For any questions regarding StarPU, please contact the starpu-devel
mailing-list at starpu-devel@lists.gforge.inria.fr .