Read Me

This is a Tcl binding to famous levmar library implementing Levenberg-Marquardt 
optimization algorithm often used in data fitting. Please see following website
for additional information regarding levmar:

  http://www.ics.forth.gr/~lourakis/levmar/index.html

This library is a standard Tcl extension providing command interface to 
levmar functionality. Extension is implemented using Tcl Extension Architecture 
(TEA).  Please see the webpage

  http://www.tcl.tk/doc/tea/

Project home page at SourceForge:

  https://sourceforge.net/projects/levmartcl/

CONTENTS
========
The following is a short description of the files you will find in
the levmartcl distribution.

Makefile.in	Makefile template.  The configure script uses this file to
		produce the final Makefile.

README		This file

aclocal.m4	Generated file.  Do not edit.  Autoconf uses this as input
		when generating the final configure script.  See "tcl.m4"
		below.

configure	Generated file.  Do not edit.  This must be regenerated
		anytime configure.in or tclconfig/tcl.m4 changes.

configure.in	Configure script template.  Autoconf uses this file as input
		to produce the final configure script.

demos/  This directory contains demo scripts

doc/  This directory contains man pages

pkgIndex.tcl.in Package index template.  The configure script will use
		this file as input to create pkgIndex.tcl.

src/	This directory contains library source files

tclconfig/	This directory contains various template files that build
		the configure script.  They should not need modification.

	install-sh	Program used for copying binaries and script files
			to their install locations.

	tcl.m4		Collection of Tcl autoconf macros.  Included by
			aclocal.m4 to define SC_* macros.

PRE BUILD
==========

 Before you start building levmartcl, prease make sure that levmar library is 
built and installed in your system. Because levmartcl is a Tcl extnsion and 
linked dynamically, levmar must be built and accessible as shared (dynamic) 
library.

To download levmar library please visit its official site:

  http://www.ics.forth.gr/~lourakis/levmar/index.html

UNIX BUILD
==========

Building under most UNIX systems is easy, just run the configure script
and then run make. The following minimal example will install the extension in 
the /opt/tcl directory.

	$ cd levmartcl
	$ ./configure --prefix=/opt/tcl
	$ make
	$ make install

If "configure" script fails with "Can't find Tcl configuration definitions" 
error, please try to use command line option "--with-tcl=<dir>", where <dir> is 
a directory containing "tclConfig.sh" file with Tcl configuration.

To get list of all command line options, use "./configure --help" command.

If your target system has "checkinstall" utility, it is preferred yo use in 
place of "make install" command. Symply type "checkinstall" and follow program
instructions.

WINDOWS BUILD
=============

The recommended method to build extensions under windows is to use the Cygwin 
environment. This provides a Unix-style build while generating native Windows 
binaries. Using the Cygwin you can use the same configure script as per the Unix 
build to create a Makefile.

Native Windows builders, like Visual Studio C++, are not supported yet, but 
one can manually create a project, add sources and build the library binaries.

INSTALLATION
============

The installation of a levmartcl package is structure like so:

         $exec_prefix
          /       \
        lib       bin
         |         |
   PACKAGEx.y   (dependent .dll files on Windows)
         |
  pkgIndex.tcl (.so|.dll files)

The main .so|.dll library file gets installed in the versioned PACKAGE
directory, which is OK on all platforms because it will be directly
referenced with by 'load' in the pkgIndex.tcl file.  Dependent DLL files on
Windows must go in the bin directory (or other directory on the user's
PATH) in order for them to be found.

USAGE AS TCL EXTENSION
======================

If levmartcl is properly built and installed, one can use its functionality via
new Tcl commands which are added by this extension.

Prior to calling levmartcl commands, load this extension by issuing following 
command within tclsh:

package require levmartcl ?version?

where version - optional parameter specifying version of the extension you'd 
like to use.

If library is loaded successfully, command returns its version, say "1.0.0".

USAGE AS STATIC LIBRARY
=======================

Levmartcl may be also linked statically. Default installator (run by 
"make install" shell command) installs levmartcl.hpp file to system include
directory. This file may be used both in C and C++ projects. It declares two
global functions: createLevmarCommands and destroyLevmarCommands.

createLevmarCommands adds levmarlet commands to given Tcl interpreter.
destroyLevmarCommands removes levmarlet commands.

Also default installator places static version levmartcl to system library
directory. Please notice that library name contains version, i.e. 
"levmartcl1.0.0" rather that "levmartcl". One may create symbolic links with
unqualified name manually.