This file contains the installation instructions for the
resource-characterization tool.

The high-level design of the system is as follows: an administrator
must first adjust a file of parameters that the system uses.  Then,
all of the characterization passes are executed and a (dynamic, if
possible on that system) linkable library is built -- the only output
from this process is the location of the library and its .h file (so
the administrator can move these to whereever the rest of the code
needs them to be).


The first step, then, is to update the configuration.txt file in the
same directory as this README file.  This file contains a set of
(string, value) pairs to describe the C compiler and its options.
These options cannot be discovered by the autotools, so they require
an administrator to set them up.  The default values in this file are
for most versions of gcc numbered 4.x.  The flags and expected values are
explained at the end of this README.

The second step is to cd into the Benchmark_Skeleton directory and run
"configure".

The final step is running the RUN_ME script in the Benchmark_Skeleton
directory.  This script adds the correct directories to the path and
then calls make, which recursively calls all of the characterization
passes.  When they finish, the library is built, and the RUN_ME script
returns the location of the code.

For a human-readable list of the chacracteristics found, run the
generate_human_readable_report.bash script from the same directory as
the RUN_ME script.



The library returned by this system is described in the README.txt
file in the RCDB subdirectory in the src directory, but we explain
them briefly here:

RC_Init sets up the database data structure, so it must be called
before either of the other two calls.

RC_Query looks up strings that describe the various resource
characteristics discovered.  These strings are described in the 

RC_Final is the cleanup routine; it frees the database data structure.



The configuration.txt file is a simple text file of (name, value)
pairs.  The resource-characterization passes were designed to be
remotely compiled, so most pairs have a TARGET entry and a HOST entry.
The HOST entries correspond to the compiler values associated with the
system on which the characterization passes are being built.  The
TARGET entries correspond to the compiler values associated with the
environment in whcih the passes will actually be run.  When the code
is not going to be remotely compiled, the HOST and TARGET values will
mirror each other.

The names and meanings are as follows:

CC_HOST, CC_TARGET -- these are the names of the C compilers on the
host and target.

COPT_HOST, COPT_TARGET -- these are the values of the default
optimization flags.  On gcc, for example, the value is -O (which
actually corresponds to -O2).  This value is used by passes that need
optimization, but do not require specific levels of optimization or
specific optimizations (such as loop unrolling, for example).  The gcc
default is -O.

C99_STD_FLAG_HOST, C99_STD_FLAG_TARGET -- some of the passes require
features from the C99 standard, and these are the flags that tell the
compiler to accept code according to that standard.  The gcc default
is -std=c99.

MATH_LIBRARY_LINKER_FLAG_HOST, MATH_LIBRARY_LINKER_FLAG_TARGET -- some
compilers require inclusion of the math library on the command line.
This flag corresponds to the option those compilers demand.  The gcc
default is -lm.

ASSEMBLER_OUTPUT_FLAG_HOST -- this flag is not (currently) used.

ASSEMBLER_OUTPUT_FLAG_TARGET -- To find the number of registers on the
machine, we compile a piece of code and examine the assembly code
(instead of running an executable, as most of the other passes do).
This is the flag that forces the compiler to output assembly code
rather than object code.  The gcc default is -S.

EXECUTABLE_OUTPUT_FLAG_HOST, EXECUTABLE_OUTPUT_FLAG_TARGET -- these
flags allow the user to specify a particular output-file name.  The
gcc default is -o.

LINK_PATH_FLAG_HOST, LINK_PATH_FLAG_TARGET -- this flag is the flag
passed to the linker to specify link libraries.  The gcc default is
-L.

INCLUDE_PATH_FLAG_HOST, INCLUDE_PATH_FLAG_TARGET -- these flags are used
to specify extra paths for the compiler to find include files.  The
gcc default is -I.

MACRO_DEF_FLAG_HOST, MACRO_DEF_FLAG_TARGET -- these flags are used to
pass macro values into the compiler.  The gcc default is -D.

PTHREAD_LIBRARY_LINKER_FLAG_HOST, PTHREAD_LIBRARY_LINKER_FLAG_TARGET --
these flags specify to the link to include the pthreads library.  The
gcc default is -lpthread.


ASSEMBLY_CODE_COMMENT_START_HOST, ASSEMBLY_CODE_COMMENT_START_TARGET, 
ASSEMBLY_CODE_COMMENT_END_HOST, ASSEMBLY_CODE_COMMENT_END_TARGET --
as said above, we find the number of registers on a system by
examining the compiler's assembly-code output.  This simple method is
complicated by many compilers, which add comments into their assembly,
which is a feature that can't always be turned off with a flag.  The
general solution is to identify the assembly comments and ignore them,
and these flags identify the starting and ending comment characters.
In C, for example, the starting comment string is "/*", and the
comment continues until the ending comment string, "*/", is
encountered.  In contrast, C++ comments start with the string "//" and
are terminated by the end of line character.  If the comment is
terminated by the end of the line, the "ASSEMBLY_CODE_COMMENT_END_*"
variables should be followed by a space in configuration.txt.  The gcc
default is ";;", and comments are terminated by the end of the line.


COUTPUT_FLAG_HOST, COUTPUT_FLAG_TARGET -- for historic reasons, these
flags mimic the values of "EXECUTABLE_OUTPUT_FLAG_*"; these flags
tell the compiler to output to a file with a specific name.  The gcc
default is -o.

ASSEMBLY_FILE_EXTENSION_HOST, ASSEMBLY_FILE_EXTENSION_TARGET -- these
flags specify the extension on the file output by the compiler when we
compile to assembly code rather than object code.  The gcc default is s.

CCOMPILE_ONLY_FLAG_HOST, CCOMPILE_ONLY_FLAG_TARGET -- these flags
tell the compiler to compile the input to an object file rather than
an executable.  The gcc default is -c.

HWLOC_PATH_HOST, HWLOC_PATH_TARGET -- these flags specify the path to
the Portable Hardware Locality (hwloc) library.  If these do not exist
on the system, these values should be followed by a space.

COPT_TARGET, COPT1_TARGET, COPT2_TARGET, COPT3_TARGET -- these flags
give the passes control over the level of optimization, with the
assumption that the higher the number, the greater effort the compiler
makes to optimize.  The gcc default values are, respectively, -O, -O1,
-O2, and -O3.


VECTORIZATION_FLAG_TARGET -- on systems that support vectorization,
this flag tells the compiler to try to vectorize the code.  The gcc
default is -ftree-vectorize.

VECTOR_UNIT_INSTRUCTION_FLAG_TARGET -- this flag tells the compiler to
give access to vectorizing intrinsics.  The gcc default is -msse2.

NO_UNROLL_TARGET -- this flag is not currently used and should be left
blank.

LIBTOOL -- Apple has their own version of libtool, so this should be
set to "glibtool" for MAC OS X.



"This software was produced with support from the Defense Advanced
Research Projects Agency (DARPA) through AFRL Contract FA8650-09-C-1915. 
Nothing in this work should be construed as reflecting the official policy or
position of the Defense Department, the United States government, or
Rice University.

THIS SOFTWARE HAS BEEN APPROVED FOR PUBLIC RELEASE,
UNLIMITED DISTRIBUTION."
