**************************
OSKI Developer Notes
Last update: June 30, 2005
**************************

These notes are for use by OSKI developers or people interested
in extending/modifying the OSKI source.

Contents:

(1)  Checking out the developer version from CVS
(2)  Generating Doxygen documentation
(3)  Creating a new matrix type
(4)  Creating a new heuristic
(5)  Debugging techniques

----------------------------------------------
1. Checking out the developer version from CVS
----------------------------------------------

Read these instructions on how to check out the developer's version
from the OSKI on SourceForge CVS repository:

   http://sourceforge.net/cvs/?group_id=140679

Once you have a copy, you need to bootstrap the distribution by
running the "./bootstrap.bash" bash-shell script at the top of the
source tree. OSKI uses the GNU AutoTools, and has been specifically
tested with these versions:

  m4-1.4.2
  autoconf-2.59
  automake-1.9.5
  libtool-1.5.10

The only sensitive dependence is on libtool-1.5.10, although
libtool-1.5.22 appears to work on many platforms as well.

-----------------------------------
2. Generating Doxygen documentation
-----------------------------------

After configuring a build tree, you can build the Doxygen
documentation from the source by executing

  $  make docs

from the top of the build-tree. You will need Doxygen 1.3.9.1 or
later.

-----------------------------
3. Creating a new matrix type
-----------------------------

(To be completed)

When adding a new matrix type to be integrated into the core OSKI
source distribution, you may need to modify these files:

    configure.ac
    Makefile.am
    ac_macros/oski_enable_${MATTYPE}.m4
    ac_macros/oski_enable_bench.m4
    src/Makefile.mattypes
    src/gen_extlibs_stub.sh --> src/Make.extlibs
    bench/gen_allfmtker.bash, bench/gen_fmtker_stub.sh
    tests/format_battery.sh, tests/format_battery_simple.sh
    doc/libdep.dot

where "${MATTYPE}" is your matrix type (e.g., CSR, CSC, MBCSR, ...)
and the arrow relation "a --> b" indicates script "a" should be
modified and then used to re-generate file "b".

---------------------------
4. Creating a new heuristic
---------------------------

(To be completed)

------------------------
5.  Debugging techniques
------------------------

The OSKI library responds to a variety of run-time environment
variables which aid debugging:

*  OSKI_DEBUG_LEVEL=<integer>

Controls debugging message verbosity. A value <= 0 means output no
debugging messages.

Debugging messages are output in the library by calls to
oski_PrintDebugMessage() and its variants (see src/corelib/debug.c).

*  OSKI_LD_LIBRARY_PATH=<paths-separated-by-colons>

Sets the shared library search path. This variable is equivalent to
setting LD_LIBRARY_PATH, but overrides LD_LIBRARY_PATH.

*  OSKI_LUA_PATH=<paths-separated-by-semicolons>

Changes the OSKI-Lua search path. The format uses a '?' to mark the
substituion of a Lua module. For example, suppose

  OSKI_LUA_PATH=/home/bob/?;/home/dat-phan/?.lua

If the OSKI-Lua interpreter encounters an unknown constructor symbol
'SYMBOL' at run-time, then it will see if '/home/bob/SYMBOL' or
'/home/dat-phan/SYMBOL.lua' exist.

*  OSKI_BENCH_DIR=<path>

Tells the tuning module to look for benchmark data in the specified
directory. Note: this is not a search path, though it should be.

*  DISABLE_BENCH={yes|no}    (Default: no)

If set to 'yes', then when 'make benchmarks' is run, the benchmark
program does not run. Instead, the time stamps for all benchmark data
files will be updated (using 'touch') or, if non-existent, initialized
to empty files.

*  OSKI_TICKS_PER_SEC=<value>

This environment variable sets the ticks-per-second calibration factor
for the timer. The timer is based on FFTW's hardware cycle counter
module ('cycle.h' distributed with FFTW 3), which reports times in
arbitrary units of 'ticks'. OSKI will, at run-time, determine the
ticks-per-second conversion factor, which could take around 1 second
at run-time. To avoid this cost, set this environment variable to the
right factor. For example,

  OSKI_TICKS_PER_SEC=2e9

tells OSKI to assume 2 billion ticks per second.

'Ticks' are usually cycles, so this factor is equivalent to the
machine's clock rate. (Exception: the cycle counter on a MIPS-14000
processor may be 2x the clock rate.)

# eof
