Abstract
This chapter describes how to use pgtcl with
your Tcl application. Before using pgtcl commands,
you must load the libpgtcl
library into your Tcl
application. There are three approaches to doing this, but care must be
taken because of the dependency on the PostgreSQL
client library libpq
.
This chapter also describes pgtclsh and pgwish, which are Tcl and Tcl/Tk shells built with pgtcl.
This chapter only applies to the pgtcl-ng implementation of pgtcl. For other implementations, check the included documentation.
You can use the Tcl package
command to load
the pgtcl library.
This is the recommended approach, especially if you have multiple
applications using pgtcl on your system.
For this to work, you need the libpgtcl
library
and the pkgIndex.tcl
package index file installed.
If these files are installed properly, your application can use:
package require Pgtcl
to load the pgtcl library. Or, if your application requires a specific version:
package require Pgtcl 1.6
This is the preferred method for loading a package into a Tcl application,
however it does require some installation setup. Specifically, the library
and package index file must be installed into a subdirectory of the Tcl
$auto_path
or $tcl_pkgPath
directories.
A typical location for installation of this package might be:
/usr/lib/tcl8.4/pgtcl1.6/
.
(Note the subdirectory name (here pgtcl1.6
), does
not need to match the library name, and by convention includes only
the two parts of the version. Tcl looks in all subdirectories
of its package library directory to find packages.)
Refer to the Tcl documentation on
pkgMkIndex for more details.
In addition to installing the libpgtcl
library,
you must install the libpq
library in a location
where it will be found by the system shared library loader. Just
installing libpq
in the package directory along
with libpgtcl
will not work.
On Unix-like systems, either install the libpq
library
into a well-known system directory such as
/usr/local/lib
, or install it somewhere else. If you
install it somewhere else, either modify the system loader configuration
(typically using a command like ldconfig), or use the
environment variable LD_LIBRARY_PATH
to tell the system
loader where to find it.
On some systems Unix-like systems, such as Linux, the path where
libpq
was found when building
libpgtcl
is stored in the
libpgtcl
library (as rpath
).
This lets the system find the library even if it isn't in a well-known
system directory or pointed to by LD_LIBRARY_PATH
.
The other methods of finding the library still apply, if it is not
in the stored location.
On Windows systems, install the libpq
library
into a directory named in the PATH
environment variable.
It will also work if the libpq
library is installed in
the same directory as the Tcl script interpreter tclsh.exe
or wish.exe
.
Another option for installing the libpq
library is
to place it in the pgtcl package directory,
and use a modified package index file to load it.
Here is a pkgIndex.tcl
package index file for
Windows systems which enables loading both libraries from the
package directory. (This file is included in the Windows binary
distribution, and in the source distribution as
pkgIndex.tcl.win32
.)
# Tcl package index file, version 1.1 # This is a modified package index file for Pgtcl on Windows. libpgtcl needs # libpq, but libpq has to be found on PATH. So this modifies PATH before # loading libpgtcl, then restores PATH after. This allows you to store # both libpgtcl.dll and [b]libpq.dll in the package directory. proc Pgtcl__load_with_path {dir} { global env set save_path $env(PATH) append env(PATH) ";$dir" load [file join $dir libpgtcl.dll] set env(PATH) $save_path } package ifneeded Pgtcl 1.6.0 [list Pgtcl__load_with_path $dir]