Building and Installing pgtcl

   This file describes how to build and install pgtcl, making it
   available for use in your applications. This INSTALL file was
   extracted from the full pgtcl documentation (version 2004-11-08),
   which you should consult for more information about using pgtcl in
   your applications.
     _________________________________________________________________

Building and Installing on Unix-like Systems

   This section describes how to build and install pgtcl on Unix-like
   systems, including Linux.
     _________________________________________________________________

Prerequisites for Unix-like Systems

   To build pgtcl on Unix-like Systems, you need:

     * Tcl/Tk version 8.3.1 or higher, with 8.4.4 or higher strongly
       recommended.
     * PostgreSQL version 7.4 or higher, with 7.4.1 or higher
       recommended.
     * The usual building tools such as C compiler, make, and a shell.
     _________________________________________________________________

Building and Installing - Unix-like Systems

   Pgtcl is Tcl Extension Architecture (TEA) compliant, shipping with a
   standard "configure" script. You do not need to have a PostgreSQL
   source distribution available to build pgtcl, but you need a
   PostgreSQL installation with libraries and header files.

   After unpacking the pgtcl distribution, change directory into the top
   level of the distribution.

   To configure pgtcl, you must specify the path to the PostgreSQL
   include files and library files. If you have the pg_config program,
   supplied with PostgreSQL, on your PATH, you can use it to specify the
   directories as follows:

    $  ./configure --prefix=/usr/local \
     --libdir=/usr/lib/tcl8.4 \
     --with-postgres-include=$(pg_config --includedir) \
     --with-postgres-lib=$(pg_config --libdir)

   If you don't have pg_config available, you can specify the directories
   on the command line, for example:

    $  ./configure --prefix=/usr/local \
     --libdir=/usr/lib/tcl8.4 \
     --with-postgres-include=/opt/postgres/include \
     --with-postgres-lib=/opt/postgres/lib

   assuming you have installed PostgreSQL in the directory
   "/opt/postgres" .

   In the above configure commands, we have specified both --prefix and
   --libdir. If you are going to manually install the product (which is
   easy, since there is just one file produced), you can use anything you
   want or omit these. If you plan to use the install target in the
   Makefile, you need to point --libdir to a location where Tcl will look
   for package directories. On a typical system, this may be
   "/usr/lib/tcl8.4/" as shown above. The --prefix is only used for the
   header file installation (which is normally not needed anyway).

   To build pgtcl, just type:

    $  make

   If all goes well, you will end up with a sharable library file named
   something like "libpgtcl#.#.#.so".

   You can install pgtcl with:

    $  make install

   to install everything in the paths set during configure, as indicated
   above. If the paths are chosen right, the result will be enabled for
   package loading.

   You may choose instead to manually install pgtcl. If you will be
   loading "libpgtcl" directly in your application, you need only copy
   that file into a convenient location for loading. Note that "libpgtcl"
   will need to find the PostgreSQL "libpq" loadable library.

   If you want to be able to load pgtcl into applications using

    package require Pgtcl

   you need to install "libpgtcl" into a subdirectory of Tcl's
   tcl_pkgPath or auto_path, and include the file "pkgIndex.tcl" which
   tells Tcl how to load the package. For example:

    $ mkdir /usr/lib/tcl8.4/pgtcl1.5
    $ cp libpgtcl1.5.2.so pkgIndex.tcl /usr/lib/tcl8.4/pgtcl1.5

   This is what the make install target does. Note: The name of the
   directory under the Tcl library directory is not important, as the
   extension will be found regardless of the directory name. You may
   choose to use the three-part version number in the name, or just the
   major and minor version numbers.
     _________________________________________________________________

Building and Installing on Windows Systems (Borland Compiler)

   This section describes how to build and install pgtcl on Windows
   systems. Building on Windows systems is less automated than on
   Unix-like systems, and you are advised to fetch a binary release
   instead of building it yourself. If you get a binary release, follow
   the instructions in the release to install it. Installation generally
   just involves copying two DLL files. If you want to compile your own
   pgtcl, read the following sections.
     _________________________________________________________________

Prerequisites for Windows Systems

   Here are the prerequisites for building pgtcl on Windows. Note that
   specific versions of each product are mentioned. Newer versions will
   probably work, and older versions are less likely to work. The
   versions listed here have been tested.

   To build pgtcl on Windows, you need:

     * ActiveState ActiveTcl Tcl/Tk version 8.4.5, installed with
       libraries and header files;
     * Borland C++ Builder Command Line Tools (BCC32 5.5.1), installed
       and configured;
     * PostgreSQL 7.4.1 source release, unpacked. You cannot use any
       release before 7.4.1. Note that you really only need the
       directories "src/interfaces/libpq", "src/interfaces/backend",
       "src/include", and "src/port" .

     Note: You can probably build this with Microsoft's C compiler, but
     we don't have one and don't know how to do it.
     _________________________________________________________________

Building and Installing - Windows Systems

   Following the instructions below, you will first build the the
   PostgreSQL "libpq" loadable library. Then you will build the pgtcl
   loadable library "libpgtcl", and link it with ActiveState Tcl
   libraries. (Even though ActiveState libraries are built with Microsoft
   C, they can be linked with Borland C programs, with one extra step.
   However, you cannot use the Tcl stubs interface.)

   Here are the steps to build pgtcl on Windows. You will be working
   mostly in a Command Prompt window. (The prompt is shown below as C:\>
   but your prompt will vary.)

   The steps below assume your Borland compiler is installed at
   "c:\apps\bcc", ActiveState Tcl is installed at "c:\apps\tcl", your
   PostgreSQL source is unpacked at "c:\src\pgsql", and pgtcl is unpacked
   at "c:\src\pgtcl". Adjust the pathnames shown below to match your
   actual installation.

    1. Create a Borland import library from the ActiveState Tcl link
       library.
    C:> cd c:\apps\tcl\lib
    C:> coff2omf tcl84.lib tcl84omf.lib
    2. Build the libpq loadable library, "blibpq.dll".
         a. In "c:\src\pgsql\src\include", copy the file
            "pg_config.h.win32" to "pg_config.h", overwriting the
            existing file. (This would be done for us if we used the
            top-level src/bcc32.mak Makefile, but that makes psql also
            and we don't want that.)
         b. If you are running PostgreSQL 7.4.1, there is one source
            patch you need to apply. (This patch is already present in
            7.4.2.) In the source directory "c:\src\pgsql\src\port" edit
            the file "thread.c" and change the line:
    #if defined(WIN32) && defined(_MSC_VER)
            to:
    #if defined(WIN32) && (defined(_MSC_VER) || defined(__BORLANDC__))
         c. In the directory "c:\src\pgsql\src\interfaces\libpq", edit
            the file "bcc32.mak" as follows:
              i. Uncomment the line and define BCB to point to your
                 Borland installation directory. (Although this isn't
                 needed to compile programs with a proper PATH, it is
                 needed for the resource compiler BRC32.)
             ii. Change LINK32_FLAGS to add the option "-c" to the end.
                 This is needed to make the linker case-sensitive,
                 because libpq has external symbols which differ only in
                 case.
             iii. Change the link command run-time library from
                 "cw32mti.lib" to the static version "cw32mt.lib". This
                 is necessary or applications using fprintf will crash.
         d. Build the libpq library:
    C:\>  cd c:\src\pgsql\src\interfaces\libpq
    C:\>  make -f bcc32.mak
            This will create the loadable library file "blibpq.dll", and
            an import library "blibpqdll.lib", in the
            "src\interfaces\libpq\Release" directory. You need these for
            the next step.
    3. Build the pgtcl loadable library, "libpgtcl.dll". Change directory
       to the unpacked pgtcl source distribution. For example:
    C:\>  cd c:\src\pgtcl
       Edit the file "bcc32.mak" as follows:

    a. Define BORLAND to point to the top of your Borland installation
       directory.
    b. Define TCL to point to the top of your Tcl installation directory.
    c. Define POSTGRESQL to point to the top-level source directory "src"
       inside your unpacked PostgreSQL distribution, where you have
       already built libpq. For example: POSTGRESQL=C:\src\pgsql\src .

   Now build libpgtcl:

    C:\>  make -f bcc32.mak

   This will create the file "libpgtcl.dll".

   To use pgtcl on Windows, you will need the two files you built:
   "c:\src\pgsql\src\interfaces\libpq\release\blibpq.dll", and
   "c:\src\pgtcl\libpgtcl.dll" . The Makefile contains an installation
   target you may choose to use:

    C:\>  make -f bcc32.mak install

   This will install the two library files and a specially modified
   package loading script into a new package directory in your Tcl
   library directory.
     _________________________________________________________________

Building and Installing on MacOS 10

   This section describes how to build and install pgtcl on MacOS X 10
   systems. This information was provided by a user and has not been
   verified by the developers or authors. It is provided in the hope that
   it will be useful to others.
     _________________________________________________________________

Prerequisites for MacOS Systems

   Our successful report building pgtcl on MacOS used:

     * MacOS X 10.3.3
     * PostgreSQL 7.4.x
     * Aqua Tcl/Tk 8.4.5
     _________________________________________________________________

Building on MacOS

   The user-submitted configure command for MacOS X follows. It specifies
   additional link libraries using the EXTRA_LIBS environment variable.
   This is used to link in the ssl libraries needed by libpq.

    EXTRA_LIBS='-lssl -lcrypto' \
    ./configure --prefix=/usr/local \
      --libdir=/Library/Tcl \
      --with-postgres-include=/usr/local/pgsql/include \
      --with-postgres-lib=/usr/local/pgsql/lib \
      --with-tcl=/Library/Frameworks/Tcl.framework \
      --with-tclinclude=/Library/Frameworks/Tcl.framework/Headers
