Welcome to the IWLS 2008 Synthesis Challenge.

In the root directory of the unpacked tarball you'll find a script
named "bootstrap" which will bootstrap the infrastructure for the
synthesis challenge.


Bootstrapping the installation
==============================
Before you invoke 'bootstrap' make sure you have the following tools on 
your PATH:

- a working C++ compiler
- the 'tar' command
- the 'awk' command
- the 'gunzip' command
- the 'bunzip2' command
 
The bootstrap will proceed in three steps.

Step #1 will install a few programming tools that you will need to 
        program in the OA/OAGear environment. 
Step #2 will install OA.
Step #3 will build and install OAGear, as well as run some bring-up tests. 

Fear not, the bootstrap script does not mess around. Everything that is 
being installed is located within this directory. 
Depending on hardware, the bootstrap step may take between 30 - 60 minutes.

During the bootstrap you may encounter compiler warnings. Ignore them.
If anything goes seriously wrong the bootstrap script will abort.
If all goes well you should see the message "...bootstrap finished".


Trouble shooting
================
Make sure you have a working compiler. Write, compile, and execute a 
simple 'hello world' program in C and C++ (using cout << ). 
If that does not work you have fundamental problems with your system 
which are beyond what we can address here.

Assuming you have a working compiler...

Build failures during step #1
-----------------------------
There is a subdirectory named 'build'. Go there and then cd to the
source directory for the programming tool that was attempted to be 
installed. Locate one or more of the files CONFIG.log, MAKE.log, and
INSTALL.log. The files are created by the build in this order. So, for
instance, if there is a MAKE.log, but no INSTALL.log then compiling
the source failed. If there is a CONFIG.LOG but no MAKE.log, then
configuration failed. Typically one or more prerequisites are not
in place. The log files should make it simple to determine the cause
of the problem.
If configuration failed, take a look at the 'bootstrap' script to see
how configuration was attempted. You need to redo it the same way,
such that the tool gets installed in the directory where it is later
expected to be found. Do not omit the --prefix option.
If configuration was successful but compilation failed, fix the
problem and iterate using the 'make' command until compilation
succeeds. Then issue 'make install'.
If you're done go back to the root directory of the installation
(that is the directory containing the 'bootstrap' script) and
rm -rf ./build.
Then issue the 'bootstrap' command again.


Build failures during step #2
-----------------------------
This step only unpacks the OA tarballs. We don't expect any problems.


Build failures during step #3
-----------------------------
Go to the OAGear-0.98 subdirectory.
There you should find one or more of these files:
- SETUP.log   - result of generating the configure script
- CONFIG.log  - result of configuring OAGear
- MAKE.log    - result of building OAGear
- INSTALL.log - result of installing OAGear (also runs testcases)

Take a look at the files in the order given above. It should be easy
to determine what went wrong by investigating the first error message.

If configuration failed, you need to redo it. As the command that is
used to configure OAGear is fairly complex, the easiest way to redo
this step is to simply remove the OAGear subtree in the root directory
of the installation (that is the directory containing the 'bootstrap'
script). Then issue the 'bootstrap' command again.

If compilation failed, your compiler might need upgrading. See the OA 
documentation for recommended compiler levels.
After you have upgraded your compiler you need to do three things

1) Edit the iwls-setup script and *add* to LD_LIBRARY_PATH the directory
   where the standard C++ library is located. If GCC is your compiler
   you can find that directory by issuing the command
      gcc --print-search-dirs 
   Then look at the line beginning with "install:". The directory there
   is the one you want. Make sure that the "gcc" you invoked is the one
   you just installed!

2) Clean out OAGear from previous failed compile attempt. Like so:

   cd OAGear-0.98
   make distclean
   cd ../..

3) Invoke the bootstrap script again.



The iwls-setup script
=====================
After the bootstrap step has succeeded you should find a file named
'iwls-setup.sh/csh' in the root directory of the installation. You need to source
that file before you attempt to do anything (compiling, running, etc) with 
OA/OAGear. If you forget to do it there will be compile errors about
missing header files or complaints from the linker/loader because it cannot 
find some shared objects.


Getting started
===============
OA documentation can be accessed starting here:

   ./OA-2.2p052/doc/oa/html/index.html

For OAGear you want to read README-developer carefully. It not only
explains coding conventions; it also discusses how to add another package
to the OAGear build system. 


Good luck

     The IWLS team
