JCuda - Java bindings for NVIDIA CUDA

Copyright (c) 2008-2010 Marco Hutter - http://www.jcuda.org


This document and summarizes how to build the native JCuda libraries on 
different operating systems and gives an overview over the JCuda project 
structure.


=== Requirements =============================================================

The following software is required to compile the native JCuda libraries:

- The CUDA driver and toolkit from the NVIDIA website:
  http://www.nvidia.com/object/cuda_get.html

- For JCudpp: The CUDA SDK, or at least the CUDPP headers and libraries.

- The Java Development Kit (JDK) from Sun/Oracle:
  http://www.oracle.com/technetwork/java/javase/downloads/index.html
  
- A C/C++ compiler
  For Windows: Visual Studio 2005 or higher
  For Linux and MacOS : The GCC
  Alternatively: Any compiler that may be used as a generator for CMake
  (see the notes in the section "Compilation" below)
  
  


=== Project structure ========================================================

The libraries of JCuda are contained in different directories of the source 
code distribution. Each directory contains the project- and makefiles for 
the respective library, and a source code folder. These directories are
organized as follows:

- CommonJNI:
    A static library, used by all other libraries

- JCudaRuntimeJNI and JCudaDriverJNI:    
    The shared libraries for the CUDA runtime and driver API

- JCublasJNI, JCufftJNI, JCusparseJNI, JCurandJNI
    The shared libraries for the CUDA runtime libraries
    which are contained in the CUDA toolkit
    
- JCudppJNI
    The shared library for CUDPP, which is contained
    in the CUDA SDK



=== Compilation ==============================================================

There are several ways to build the native libraries for JCuda. The most
general and convenient solution is to use CMake from http://www.cmake.org/ . 
It is a cross-platform development tool which allows generating makefiles 
or project files for different compilers. 

The CMake makefiles are named 'CMakeLists.txt'. The main CMake makefile is 
contained in the root directory of the source code distribution, and refers 
to the CMake makefiles for the individual libraries contained in the 
respective subdirectories.

To create makefiles or project files from the CMake files for a specific 
compiler (for example, for GNU make or Visual Studio) the following command
has to be executed in the root directory of the source code distribution:

    cmake.exe -G <generator-name> CmakeLists.txt

where <generator-name> stands for one of the target compilers listed under
http://www.cmake.org/cmake/help/cmake-2-8-docs.html#section_Generators 

For example, the follwing command will create the project files for 
Visual Studio 2008 on 64bit Windows:
    
    cmake.exe -G "Visual Studio 9 2008 Win64" CmakeLists.txt

The resulting project- or makefiles may then be used to compile the 
JCuda libraries as a batch. Dependencies and most of the settings that
are specific for the target platform will be resolved automatically.



=== Compilation on Windows using Visual Studio ===============================

It is recommended to use CMake for creating the project files. However,
there are also general Visual Studio Project files (.VCPROJ) for each of
the libraries. These project files support the compilation of the Debug- 
and Release versions of the libraries for 32bit and 64bit Windows.

In order to compile these libraries, the environment variable named
JNI_INC_PATH
must point to the directories containing the header files from the Java JDK. 
For example, if the JDK is contained in "C:\jdk", the value of this 
environment variable must be
C:\jdk\include;C:\jdk\include\win32
(two paths, separated by a semicolon)

The CommonJNI library has to compiled first, since this will create a 
shared library ("CommonJNI32.lib" or "CommonJNI64.lib") which is 
required for all other libraries to be built.

Afterwards, the individual libraries may be compiled in an arbitrary order.




=== Compilation on Linux and MacOS ===========================================

It is recommended to use CMake for creating the makefiles. However, there
are also general makefiles for each of the libraries. These makefiles 
automatically detect the operating system and architecture and thus allow 
the compilation of the native 32bit and 64bit Linux or MacOS. 

It might be necessary to adjust the makefiles of the individual projects
to point to the right path for the Java JDK include files. 

Most of these makefiles are refering to a 'common.mk' makefile in the root 
directory of the source code distribution, which is a makefile from the 
NVIDIA code samples, adjusted for the compilation of the JCuda libraries.

To compile the JCuda native libraries using these makefiles, just execute

    make
    
in each of the project direcories, starting with the CommonJNI directory.

