Read Me

Welcome
=======

Welcome to the Algorithm Development Kit, the associated code repository to
the "Algorithms in a Nutshell" book published by O'Reilly Media, Inc.

  http://oreilly.com/catalog/9780596516246

This repository is freely available for you to use (as per the "Using Code
Examples" from the preface of the book. We quote:

  This book is here to help you get your job done. In general, you may
  use the code in this book in your programs and documentation. You do
  not need  to contact us  for permission unless you're  reproducing a
  significant portion of the code. For example, writing a program that
  uses  several  chunks  of  code  from this  book  does  not  require
  permission.  Selling  or  distributing  a CD-ROM  of  examples  from
  O'Reilly  books does  require  permission. Answering  a question  by
  citing  this  book  and   quoting  example  code  does  not  require
  permission. Incorporating a significant  amount of example code from
  this book into your product's documentation does require permission.

  We  appreciate,  but do  not  require,  attribution. An  attribution
  usually  includes  the  title,  author,  publisher,  and  ISBN.  For
  example:  "Algorithms in  a Nutshell"  by George  T.  Heineman, Gary
  Pollice, and  Stanley Selkow.  Copyright 2009 George  Heineman, Gary
  Pollice, and Stanley Selkow, 978-0-596-51624-6

  If you feel your use of  code examples falls outside fair use or the
  permission   given    here,   feel    free   to   contact    us   at
  permissions@oreilly.com

Within this repository you will find the following directories:

  README.txt         This file
  Code               Implementation of algorithms using C/C++
  PerformanceTests   Tests to stress-test JavaCode
  Tests              JUnit tests cases for JavaCode
  dist               compiled JAR files for JavaCode
  Examples           Examples showing JavaCode in action
  Figures            Shows how to generate nearly all Book Figures
  JavaCode           Implementation of algorithms using Java
  no_ant.sh          Shell script to compile JavaCode and package dist
  no_ant.bat         Windows batch file to launch no_ant_build (RUN THIS)
  no_ant_build.bat   Windows batch file that packages dist 
  build.xml          Ant buildfile to compile, test, and package JavaCode
  VERSION.txt        Version information about this Development Kit
  Makefile           Makefile to compile C/C++ code using gcc/g++
  codeIndex.txt      Code index for Java/C/C++ code references in book

The repository is provided for you as a ZIP file which you must unzip (and
likely have already done so, since you are reading this README file). Your
next goal is to compile all of the source code. This is described next.

Primary Task
============

1. Make sure JAVA_HOME is set to your JDK installation. For example the
   following shows how to set JAVA_HOME using C-Shell:

     setenv JAVA_HOME /usr/local/jdk1.6.0_07

   Note that the code repository will not compile using JDK 1.5 because
   some code relies on the java.util.Arrays.copyOf() method which was
   introduced with the JDK 1.6; we also use "@Override" annotation tags for
   classes that implement an interface. Compiling the repository requires a
   JDK-1.6 compatible javac compiler. Download the latest JDK from
   [http://java.sun.com/javase]

   Make sure that $JAVA_HOME/bin is in your PATH so the proper java and
   javac executables can be located.

2. Make sure ant is in your PATH. This installation was tested with:

      Apache Ant version 1.7.1 compiled on June 27 2008

   Download the latest version from:

      http://ant.apache.org/
 
   If you don't have 'ant' available, you may be able to use the
   "no_ant.sh" script to compile all Java classes. Read that file for
   instructions on its use. If you are on a Microsoft XP Windows machine,
   you can launch the "no_ant.bat" batch file and it will provide
   instructions on how to build the code (provided you have an available
   JDK of version 1.6 or higher).

3. Make sure that JUnit is available.

   The ant build script assumes there is a directory ../junit4.0 which
   contains the JUnit installation as found from [http://www.junit.org].
   We have tested the installation with both JUnit 4.0 and a more recent
   release, JUnit 4.10.  In all cases, the directory "junit4.0" is
   required (you can install the latest version of JUnit and simply
   create a symbolic link to that directory with the name "junit4.0").

   If your JUnit installation is in a different location, simply modify the
   line defining

      <property name="junit.home"   value="${basedir}/../junit4.0"/>

   If you are using ant version 1.6.5 (and possibly others) you will have
   to also ensure that the junit-4.0.jar JAR file is already in your
   CLASSPATH before launching ant. To do this using Bash, you would type
   something like:

      export CLASSPATH=.:/path/to/junit/junit-4.0.jar

   Apparently, ant 1.7 does not have this second CLASSPATH requirement.

4. cd into 'Tasks' and type 'ant' to build special ant task

   go back to main directory (cd ..) and continue. At this point you 
   may have to ensure that the ant libraries ${ant.home}/lib/ant.jar
   are in your CLASSPATH.

5. Type 'ant' to compile all Java code (in JavaCode directory).

   This will compile all sources and execute the JUnit test cases

5. Type 'make' to compile all C/C++ code (in Code directory)

   You will need both a 'gcc' C compiler and a 'g++' C++ compiler. Tested
   on 'g++' version 3.4.6 and 'gcc' version. Also tested on versions 4.2.1
   of both.

Review Figures and Examples
===========================

You can reproduce all of the computer-generated figures in the book using
code provided with this deployment.  Within the Figures/ directory, type
"make" to generate all of the computed tables and figures. Please be aware
that this process may take several days to compute (especially for Chapter
5). Should you wish to regenerate the figures for a specific chapter only,
change directory to Figures/scripts/chapterN and then 

  type 'make data' to generate all tables and data
  type 'make figure' to create Postscript files for computed figures

Please review the information found in

  * Figures/src/algs/chapterN/README.txt        for N=2..10
  * Figures/src/algs/appendixA/README.txt       benchmark code contained here

To run any of the Java examples, type:

  java -cp dist/ADK-1.0-ExamplesAndFigures.jar [ExampleMain]

For example, to regenerate the information found in chapter 3, table 1, type:

  java -cp dist/ADK-1.0-ExamplesAndFigures.jar   algs.chapter3.table1.Main

And to show a code example, type:

  java -cp dist/ADK-1.0-ExamplesAndFigures.jar algs.example.chapter5.ModuloSurprise

Some figures and examples require resources that are stored on the
disk. These examples must be run within the appropriate Examples/bin or
Figures/bin directory. For example, to regenerate the data from sidebar 2
in chapter 2, type:

  cd Figures
  java -cp ../dist/ADK-1.0-ExamplesAndFigures.jar algs.chapter2.sidebar2.Main

We also provide a number of example programs showing the algorithms in
practice. For examples, review the information found in

  * Examples/src/algs/example/README.txt

Optional Tasks
==============

1. Type 'ant junitBlogs' to execute the JUnit test cases covering 
   the blog code.

2. Type 'ant junitreport' to produce a full Report on the JUnit
   progress. Find the compiled JUnit report in:

       ./Tests/bin/report/ 

   This option is likely only available for ant 1.7 (and higher).

3. To generate javadoc, execute 'ant javadoc'

4. To generate doxygen documentation, type 'make doxygen' in the Code
   directory.

Final Words
===========

Once the book is published, the authors will publish a "Monthly Column"
Blog to further expand on the algorithms described in the book. The Blog
will be linked from the book's web page:

  http://oreilly.com/catalog/9780596516246

We intend to release updated versions of the repository based upon any
identified problems. You likely are already aware of the SVN repository
from which you downloaded this release:

  http://examples.oreilly.com/svn/examples/9780596516246/

Each numbered-release will be available in this directory for free
download. A README.txt file will describe the status of each release and
there will be CHANGELOG file describing the defects fixed or added
enhancements. 

Should you find an issue in either the code or the book, please let us know
using the book's web site:

  http://oreilly.com/catalog/9780596516246/errata/

You can post Errata and see the list of errors/corrections that were found
after the book was printed.  Should you wish to also post a review of the
book (and this code) visit the book's webpage:

  http://oreilly.com/catalog/9780596516246