****************************
** Open Community Runtime **
****************************


*************************
** Directory structure **
*************************

    - examples/
        helloworld and alike.
    - inc/
        user-level ocr api header files
    - src/
        ocr implementation source code
    - tests/
        Non-regression tests


*******************************
** Installation instructions **
*******************************
 
See the 'INSTALL' file


******************************
** Using OCR     		    **
******************************

This section's instructions requires you have set the 
OCR_INSTALL environment variable as described in the 
INSTALL file.


*** Compiling code

OCR is built as a library your program must link with.
The actual command line may differ on different OS and compilers.

The following command line can be used on a typical Linux X86 
distribution with gcc. It generates a binary named 'helloworld'
that links with the OCR library.

	$> gcc -L${OCR_INSTALL}/lib -I${OCR_INSTALL}/include -locr -o helloworld helloworld.c


*** Running code

OCR needs a runtime configuration file that describes how
the runtime must be layed out for the particular machine it
is executed on.

A default configuration file and some examples are provided 
under ${OCR_INSTALL}/config

The configuration file can be given to the runtime either
through the OCR_CONFIG environment variable or through the
command line parameter -ocr:cfg <filename>

Note: command line parameters always override values defined 
in environment variables.

Using environment variable options:

	$> OCR_CONFIG=<filename>; ./helloworld

Using command line options:

	$> ./helloworld -ocr:cfg <filename>

>To get a list of available OCR options:

	$> ./helloworld -ocr:help


******************************
** Testing the distribution **
******************************

*** Non-regression tests

The 'tests' folder contains a collection of non-regression tests.
After installing and setting OCR environment variables, one can
run non-regression tests running the 'ocrTests' script.

*** examples

After installing and setting OCR environment variables, examples 
located under the 'examples' folder can be tested for regressions 
using the 'ocrTestsExamples' script. 
 

***********************
** Known Limitations **
***********************

- The deque-based workpile does not resize automatically
    - the macro INC_DEQUE_CAPACITY defined in deque.h can be customized

*******************
** Documentation **
*******************

To generate documentation, type 'doxygen ocr.dox'. HTML documentation will be
generated in doc/html and LaTeX documentation in doc/latex. A PDF can be generated
from the LaTeX documentation by typing 'make' in that directory