This document describes how to build, install, configure and use the hiGPU
compiler. The release note of the compiler is in "docs/RELEASE_NOTES".


1. Prerequisites
----------------------------------------------------------------------------

The hiGPU compiler requires a Linux operating system, and has been tested on
the following variants:

- Ubuntu 7.10 (64-bit)
- Ubuntu 8.04 (64-bit)
- Ubuntu 9.10 (32-bit)
- Debian 5.0.3 (64-bit)
- Red Hat Enterprise Linux 5.5 (32-bit)

Before using the hiGPU compiler, please make sure that the following tools
are installed on the system:

- Awk and sed
- Bash and csh (or tcsh)

If you want to build the hiGPU compiler from the source tree, you need
additional tools:

- GCC 4.1
  - On a Debian-based OS, install the following packages:
    - gcc-4.1, g++-4.1
  - If the OS is 64-bit, install the following additional packages
    (for buidling 32-bit binaries):
    - ia32-libs, libc6-dev-i386, gcc-4.1-multilib, g++-4.1-multilib
  - NOTE: GCC 4.2 cannot be used to build the hiGPU compiler!
- GNU Make
- Flex and Bison


2. Building and installing the hiGPU compiler
----------------------------------------------------------------------------

If you downloaded the binary release of the hiGPU compiler, just execute the
following command to install it at <install root>:

$ ./install-bin <install root>

Note that if the install root requires root privilege, add "sudo" before the
install command.

If you downloaded the source release of the hiGPU compiler and want to build
and install it at <install root>, just execute the following two commands:

$ <source root>/utils/build
$ <source root>/utils/install <install root>


3. Configuring the environment for the hiGPU compiler
----------------------------------------------------------------------------

The scripts that set and clear up the environment for the hiGPU compiler are

        <install root>/bin/set-higpu.[sh|csh]
        <install root>/bin/unset-higpu.[sh|csh]

respectively. Note that both scripts must be invoked using "source".

For example, assuming that you installed the hiGPU compiler at /opt/higpu.
You must execute the following command in a bash shell before using the
compiler:

$ source /opt/higpu/bin/set-higpu.sh

Note that this command only needs to be invoked once when you start a new
shell. To avoid doing this manually, put the following lines in your login
script (e.g., .bashrc for bash shell):

# hiGPU environment
HIGPU_STARTUP=<install root>/bin/set-higpu
if [ -f "${HIGPU_STARTUP}" ]; then
    source ${HIGPU_STARTUP}
fi


4. Running regression tests
----------------------------------------------------------------------------

The regression test suite for the hiGPU compiler is located at:
- <install root>/regression if you downloaded the binary release
- <source root>/regression if you downloaded the source release

It is highly recommended to run the test suite to ensure that the compiler has
been installed correctly.

$ cd <install root>/regression
$ ./run-all.sh


5. Using the hiGPU compiler
----------------------------------------------------------------------------

The hiGPU compiler has the following command-line interface
(obtained by executing "higpu" at the command line):

higpu [-o <base name>] [-I<include path>]* [-m32|-m64] [-keep] [-v] [-opencl] \
    <input file(s)>

-o:     input program base name that is used to name the generated output
        files. The default value is "a.out".

-I:     add directory paths that contain the header files
        needed by the input program

-m32:   generate code to be compiled (by nvcc) to a 32-bit binary
        NOTE: must use -m32 in nvcc as well unless you are sure it does
        that by default.

-m64:   generate code to be compiled (by nvcc) to a 64-bit binary
        NOTE: must use -m64 in nvcc as well unless you are sure it does
        that by default.

-keep:  keep intermediate files generated by the compiler
        (for advanced users only)

-v:     dump more debugging info to trace files (of extension .t)
        There will be a trace file for each input file, and
        two global trace files: <base_name>.ipa.t and <base_name>.w2c.t.
        (for producing a bug report)

-opencl generate OpenCL files instead of CUDA files

The hiGPU compiler accepts one or more input files. If the base name is
"foo", it will create a new folder named "foo.cuda" (for CUDA backend) 
or "foo.opencl" (for OpenCL backend) in the current directory,
and generate the following files in these folders:

foo.cuda:
  foo.cu:       the CUDA program
  foo.cu.h:     the header file
  whirl2c.h:    internal header file included in foo.cu.h

foo.opencl:
  foo.c:        the openCL program
  foo.h:        the header file
  kernels.cl:   the openCL kernels
  kernels.cl.h: the openCL kernels header file
  whirl2c.h:    internal header file included in foo.cu.h

foo.cu can then be used in normal CUDA compilation:

$ nvcc foo.cu