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/