Mapscript Tcl Interface

WHAT
It's a Tcl interface for Mapserver.  You can write Tcl scripts to generate
maps, read/write shapefiles, etc.

VERSION
Mapscript 1.1 is built for Mapserver 3.5 +

INSTALL
A simple 'configure' script and Makefile is included.  The configure is hand
built, rather than being derived from GNU autoconf.  Normally you can just 
type:
	configure
	make
	make install

    to build and install the interface.  Three configure options are supported:

	configure --with-tcl=[dir]  --with-swig=[dir]  --with-linker-cc

	--with-tcl=[dir]    specify the directory where you installed Tcl,
			    the default is /usr/local.  'configure' looks for
			    $dir/lib/tclConfig.sh for Tcl configure info.

	--with-swig=[dir]   specify the directory where you installed Swig,
			    the default is /usr/local.  'configure' looks for
			    $dir/include/swig.h and $dir/lib/libswig.a.

	--with-linker-cc    use the compiler command as the front-end for
			    linking, if not already so.  See 'COMPILE PROBLEMS'
			    below.

	** Mapserver source code is presumed to be two directory levels above
	this directory, and uses various .h files from Mapscript, along	
	with ../mapscript.i.

	** Mapscript/Tcl normally builds as a Tcl stubbed dynamic library.
	The makefile includes a target 'nostublib' if you want to build
	with a Tcl version dependent library (not recommended).

	** Tested with Tcl/Tk version 8.3.2, and Swig version 1.1-883


REQUIREMENTS
You must have Tcl (tcl.sourceforge.net) installed and optionally, Swig 
installed also (www.swig.org).  

The current mapscript.i Swig interface definition file is designed for
Swig 1.1 versions.  Newer versions of Swig may require mapscript.i changes.
You should have Tcl 8.3 or greater installed, as the Makefile normally builds
with the Tcl dynamic stubs library.  Tcl 8.3.2 (or current release) is 
recommended.  Additionally, you may want the Img Tcl extension to
support upcoming Mapserver images (PNG, JPG, etc.)  See the NOTES section
below for more information.


COMPILE PROBLEMS
Some users have reported link or runtime errors, most notably when 
mapscript_wrap.c is compiled with gcc, but using ld to link the shared
library.  If you experience this problem, try re-running the configure script,
adding the '--with-linker-cc' option to the configure command line.

For users without Swig installed, a pre-built mapscript_wrap.c is available.
'make useprebuilt' will unpack the pre-built mapscript_wrap.c.

If you get runtime errors reporting missing symbols, check the Mapscript/Tcl
shared library for shared libraries it may be dependent upon.  In Linux, 
Solaris (and possibly other unix systems) try this:
	
	ldd libMapscript*.*

Note which libraries are unresolved.  Find the directories which contain the
libraries that are unresolved, and add those directories to your 
LD_LIBRARY_PATH environment variable, or whichever environment variable is
appropriate for your system:

	$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/other/required/dirs

Add this to your .profile or .cshrc so you won't have to set this each
time you login.  On some systems (Linux, et.al), a /etc/ld.so.conf file
and 'ldconfig' program will set system-wide default library directory paths.


WINDOWS
See the ./win directory.   You should first install Tcl 8.3.2.  Then,
run the 'setup.tcl' file to install Mapscript/Tcl.  You can double-click
on the 'setup.tcl' file from Windows explorer, or 'start setup.tcl'
from a DOS box.
  
To rebuild the DLL, see the file 'README.ms-mingw' and 'ms-mingw.tar.gz'.  
The DLL provided was built with the Mingw compiler, as a cross compiler 
hosted on Linux.  You should be able to rebuild the DLL on any Unix box, or 
with a little work, using Mingw or Cygwin compiler & tools on Windows.  

No Microsoft or Borland makefiles are provided.  Feel free to donate one(s). 

You can use the popular 'WinZip' program to unpack tar.gz files on Windows
(http://www.winzip.com), or use gunzip and tar from the Cygwin tools
(http://sources.redhat.com/cygwin/).



DOCS
Swig generated documentation, plus and additional doc page for Tcl coded 
helper functions are available as HTML.


EXAMPLES
See the ./examples directory.  

	shpinfo.tcl    - print rudimentary info about a shape file.


MAPSERVER WORKBENCH 
MapServer Workbench is a set of tools written in Tcl/Tk with the Mapscript/Tcl
extension, and is available separately.  The Workbench currently consists of:

	msappwiz.tcl    -wizard to create mapserver application mapfiles
	msedit.tcl	-tree-structured mapfile editor
	msexplorer.tcl	-view, zoom, and query mapfiles 
	msshapex.tcl	-view shapefile information and .dbf attributes

MapServer Workbench tools run under Unix or Windows.

For more information and to download MapServer Workbench:
	http://msworkbench.sourceforge.net
	http://sourceforge.net/projects/msworkbench/
	http://www.nyx.net/~tpoindex/gis


NOTES
e.g., the "SWIG_STUB_HACK"
Building Tcl extensions that are not dependent on a particular version of
Tcl is the preferred method.  Prior to Tcl 8.1, an extension had to be
linked against a version dependent Tcl libarary.  Extensions had to be
recompiled and relinked when newer versions of Tcl were installed.

Beginning with Tcl 8.1, the 'stub' library was introduced to facilitate 
version independent extensions.  The stub library is a table of pointers
to Tcl functions, that are initialized at run time, so extensions compiled
for one version of Tcl don't have to be recompiled.  A call to Tcl_InitStubs()
is required before using any Tcl function in an extension, and we link to
libtclstub8.3.a, instead of the entire Tcl library. 

Swig 1.1-883 doesn't initialize the stub table by calling Tcl_InitStubs(), so
we must do it ourselves.  Normally, we use the Swig directive '%init' to
include the call to Tcl_InitStubs.  However, we also prefer that the new
Mapscript commands reside in their own namespace, by using the Swig option
'-namespace'.  Unfortunately, Swig generates a call to Tcl_Eval() before
the %init code is included in the wrapped .c file.

We work around this problem for Mapscript by some crusty use of the
C preprocessor.  Just before the Tcl_Eval call in the wrapped .c file, Swig
also includes an bit of code that allows use the [incr Tcl] object system.  
The makefile passes command line C preprocessor defines to
subvert this bit of code for our use.  Thus, we are able to call the 
Tcl_InitStub function before Tcl_Eval is called.  See the Makefile 
macro "SWIG_STUB_HACK".


WHO
Tom Poindexter
tpoindex@nyx.net
http://www.nyx.net/~tpoindex/


