/**
@file README.TXT

@mainpage dlr Utility Libraries

@section intro_sec Introduction

General support libraries for exception handling, unit testing,
numerics, optimization, etc.  The current version number is shown
in file VERSION.TXT, and recent changes can be seen in the file
RELEASE_NOTES.TXT.

@section contact_sec Contact

Bugfixes and patches welcome!  Please see the file LICENSE.TXT in
this directory for up-to-date contact information.

@section license_sec License

Please see the file LICENSE.TXT in this directory.

@section platform_sec Platform

These libraries are in regular use under Linux (32- & 64-bit), and
not-so-regular use under Windows (32-bit).  They should be portable
to any platform supporting ISO C++.

@section finding_sec Finding Your Way Around

Each of the libraries in this distribution has both its own namespace
and its own directory in the source tree.  If you're reading this as
part of the HTML documentation, then you can get a good overview of
what's available by clicking on the "namespaces" and "directories"
tabs at the top of the page.  The namespaces tab has brief
descriptions of each namespace/library, and the direcotories tab has
links which show you all of the files which comprise each library.  If
you're reading this as part of the PDF documentation, then you can get
a good overview of what's available by going to the "namespaces" and
"directories" chapters, which should contain clickable links similar
to those in the html documentation.

In any case, the following section presents an short introduction to
each library in the distribution.

@section libraries_sec Libraries

@subsection corelibs_subsec Core Libraries

The libraries listed in the section have been around for a while.
They are well tested, and their interfaces are stable.  Features get
added from time to time, but we're careful not to break existing user
code.

  - dlrCommon: This library is the foundation for all of the other
    libraries in the collection.  It provides classes for working
    with exceptions, reference counting, portable numeric types
    with known precision, byte order, and more.

  - dlrNumeric: This is the original and most complete library in the
    collection.  It has code for 1D, 2D, and 3D arrays, coordinate
    transformations, and much more.  This is a good library to use
    if you need to port Numeric/numpy code from Python to C++.

  - dlrLinearAlgebra: This library provides C++ wrappers around
    LAPACK linear algebra routines.  Currently it includes routines
    for matrix inverse, solution of linear equations, SVD,
    determinant, and eigenvectors/eigenvalues of symmetric real
    matrices.

  - dlrRandom: This library provides a C++ wrapper around the LAPACK
    pseudo-random number generator.  It is much less comprehensive
    than, for example, boost::random, but is very easy to use.

  - dlrOptimization: Quasi-Newton and Downhill Simplex nonlinear
    optimization classes. These classes follow the algorithms
    described in Numerical Recipes in C, but the code is nicer.

  - dlrTest: This is a unit testing library.  It's kind of like a
    simpler and less featureful version of CPPUNIT or boost::test.
    The unit tests for the rest of the collection are implemented
    using dlrTest.

@subsection incompletelibs_subsec Incomplete Libraries

These libraries are less mature and less stable than the core
libraries, but they still contain useful code.  Some effort will be
put into maintaining a consistent interface.

  - dlrUtilities: This library started out as a C++ replacement for
    the python modules string and path.  Development of the path
    component was moved to the dlrPortability library instead, and
    then stalled because boost::filesystem does a much better job.
    The string manipulation routines are reasonably mature and quite
    useful.  This library now includes a command line parser that grew
    out of my frustration with existing libraries for parsing program
    options.  There's a also class for handling lockfiles (currently
    Linux-only) and code for importing and exporting arrays in a
    format that's easy to read and write from Python.

  - dlrPortability: The point of this library is to encapsulate as
    much of the platform-specific code as possible, making the
    other libraries more readable.  Currently it contains the
    (stalled) path code which was originally part of dlrUtilities,
    a few time-related routines, and a reduced-functionality
    version of snprintf.

@subsection unstablelibs_subsec Unstable Libraries

Libraries in this section are still very young, and their
interfaces are still being explored.  Feel free to play around with
these libraries, but bear in mind that they may change out from
under you.  Of the libraries in this section, dlrThread is the
closest to being stable and usable.

  - dlrThread: This library is built on top of boost::thread.  The
    idea is to provide some high level abstractions such as shared
    FIFOs and monitor objects so that the user doesn't have to
    think at the level of locks and mutexes.  Currently it includes
    a FIFO object called a DataQueue which allows multiple threads
    to access data in sequence.

  - dlrComputerVision: This library is still in the early stages of
    development.  Feel free to play around with it, but please bear in
    mind that its interface is not stable.  It currently includes code
    for basic morphological operations, edge detection, simple
    deformable contours, and histogram equalization.

  - dlrStochastics: This library is still almost completely empty.
    It was created as a place to put code which deals with
    probability and statistics.  It's not clear when work on this
    library will resume.

  - dlrClassification: This was an abortive start at a machine
    learning library.  Since then I've audited a machine learning
    class, so I'll be completely replacing this code.

@section dependencies_sec Dependencies

You should be able to build all of the the libraries except for
dlrThread, dlrLinearAlgebra, and dlrRandom without installing any
additional dependencies.  To build dlrThread, you'll need to install
the boost::thread library.  To use the dlrLinearAlgebra library and
the dlrRandom library, or to run the tests for those and several other
libraries, libraries, you'll need to have LAPACK and BLAS installed.

The LAPACK and BLAS libraries generally come as part of major Linux
distributions, or else you can get them from
http://www.netlib.org/.  Optimized versions of LAPACK and BLAS are
also available from http://math-atlas.sourceforge.net/.

Boost::thread is also included with many major Linux distributions.
You can download it frow http://www.boost.org.

Note that to compile programs linked against LAPACK and BLAS using
g++, you may also need libg2c, which is part of the gnu compiler
collection, and should come bundled with g77, which in turn may
have been installed along with g++ & gcc.

@section installation_sec Installation

@subsection visual_studio Visual Studio

If you're building under Visual C++, load the solution file:

  ./visualc/dlrLibs/dlrLibs.sln

Building this file will put libraries in 

  ./visualc/dlrLibs/{Release,Debug}

NOTE: Microsoft's compiler considers much of the C++ Standard Library
to be deprecated.  Building this code under recent versions of VC++
generates lots of warnings telling you to use the use the confusingly
named "Safe Standard C++ Library," which isn't standard at all, and as
far as I know isn't portable to any other platforms.  It's possible to
disable these warnings.  I encourage you to do so by adding
"/D_CRT_SECURE_NO_DEPRECATE" and "/D_SCL_SECURE_NO_DEPRECATE" to the
compiler command line via the "properties" dialog for the .vcproj file
within Visual Studio.  I've done this for the .vcproj files included
with dlr_libs, but you may find these warnings popping up in your own
code when you include dlr_libs header files.  Don't be fooled.

Please be aware that I hardly ever use windows, so the .sln/.vcproj
files are usually a little out of date.  I occasionally check that
friends who use these libraries under windows are still happy, but I
don't get patches too often.  Let me know if you have any trouble, and
please feel free to email with updates.  Also note that the .vcproj
files are all configured to build multi-threaded code.  This may cause
some trouble if you're linking with projects that use single threaded
code.  See the code generation page of the project properties dialog
to change this.

@subsection autotools GNU Autotools

On every other platform, building and installing is done via GNU
Autotools.  If you're building from a tarball, the simplest
possible version looks like this:

@code
> tar -xvf dlr_libs-x.y.z.tar.gz
> cd dlr_libs-x.y.z
> ./configure
> make
> make install
@endcode

If you're using the source files from CVS, you need to add a step:

@code
> [get source from cvs]
> ./bootstrap
> ./configure
> make
> make install
@endcode

Of course, you may want to specify an installation directory:

@code
> [get source from cvs and run ./bootstrap, or unpack tarball]
> ./configure --prefix=/home/jfisher/software
> make
> make install
@endcode

Or some compiler options:

@code
> [get source from cvs and run ./bootstrap, or unpack tarball]
> env CXXFLAGS="-g -Wall" ./configure \
    --prefix=/home/jfisher/software
> make
> make install
@endcode

For more information on configure options:

@code
> ./configure --help
@endcode

Thanks,
David LaRose
**/
