Contents:
---------

1. Copyright and contact information
2. Introduction
3. Installation on Linux x86
4. Installation on other UNIX architectures
5. Installation on Windows


1. Copyright and contact information
-------------------------------------

Postgres Forms (pfm) is a client application for PostgreSQL.

Copyright © 2004-2013 Willem Herremans

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

A copy of the  GNU General Public License is included in the 'help'
subdirectory of this software package.

The home page of Postgres Forms (pfm) can be found at:

http://pgfoundry.org/projects/pfm/

There you can report bugs, request new features and get support.


2. Introduction
----------------

Postgres Forms (pfm) has been designed and tested on Linux. It may
work on other UNIXes as well. It has also been tested on Windows XP.

To get Postgres Forms (pfm) running you need to have access to at
least one database on a PostgreSQL database server, which may be
running either on your machine, or on another machine that you can
access via TCP/IP. You also need the PostgreSQL client application
'psql' on your machine. See PostgreSQL documentation for details.

Postgres Forms has been designed and tested with PostgreSQL version
7.4.2, but it probably works with some older and newer versions as
well. It has also been tested with PostgreSQL 8.x and 9.0. You can
obtain PostgreSQL from http://www.postgresql.org.

pfm is available in 2 variants:

  1. pfm-2.0.8-linux-x86.tar.gz for the Linux x86 architecture (32 bit);

  2. pfm-2.0.8-windows-32.exe for Windows 32 bit architecture;

Since version 2.0.5, I don't include binaries for the 64-bit
architectures anymore. The reason is that the 64-bit binaries of the
Tclkit for linux are not published by the Equi4 anymore. Also, I
don't have a 64-bit computer to test the 64-bit binaries. I am
reasonably confident that the 32-bit binaries work without problem
on a 64 bit machine. If you insist on running a 64-bit version, you
can easily replace 32-bit binaries of tclkit with their 64-bit
variants, AFTER installation. To do so:

   - Download the 64 bit binary from

        http://www.equi4.com/

     or  http://code.google.com/p/tclkit/

   - On Linux replace the installed 32 bit binary tclkit in the pfm
     installation directory with its 64 bit variant. Make sure
     that it is still called tclkit and that it is executable.

   - On Windows replace the installed 32 bit binaries tclkit.exe and
     tclkitsh.exe in the pfm installation directory with their 64 bit
     variants. Make sure that they are still called tclkit.exe
     and tcklkitsh.exe.

All variants are basically the same and contain the complete Tcl
sources. Each variant contains a binary Tclkit corresponding to its
architecture. The Linux variant contains an installer script written
in Tcl. The Windows variant is distributed as an executable NSIS
installer program.

PostgreSQL is the only package that you need to install separately
from pfm. All the other packages required by pfm are included in this
distribution. The easiest way to install pfm and the packages it
requires is to run the installer (see sections 3, 4 and 5). The rest
of this section is only included for completeness. Don't let it scare
you off.

pfm needs one of the packages: Pgtcl or pgintcl to communicate
with the PostgreSQL database server.

pgintcl 3.4.0 is included in the pfm distribution.

Pgtcl can be obtained from:

http://pgfoundry.org/projects/pgtcl/

or, the new generation Pgtcl, from:

http://sourceforge.net/projects/pgtclng/

pgintcl (included in pfm distribution) can be obtained from:

http://sourceforge.net/projects/pgintcl/

Notes:

    - The Pgtcl package offers better performance, but needs to be
      built, whereas the pgintcl package is just a Tcl script that can
      be called by pfm. Pgtcl is included in most Linux distributions,
      often with the package name "libpgtcl". In the case of pfm, the
      difference in performance between Pgtcl and pgintcl is hardly
      noticeable.

    - Pgtcl cannot be used in combination with the Tclkit run-time
      environment. You need a properly installed Tcl/Tk to use Pgtcl.

    - If the pgin.tcl file is present in the installation directory,
      pfm sources it and does not attempt to load the Pgtcl package.

    - Postgres Forms has been designed and tested with versions 1.5.1
      of package Pgtcl and with version 3.0.1 of pgintcl.

    - pgintcl 3.4.0 works with PostgreSQL version 7.4. or higher.

    - A copy of pgintcl 3.4.0 is included in the pfm distribution.

From version 2.0.0. on Postgres Forms requires version 8.5 of Tcl/Tk.
It also needs the packages Itcl 3.4 and msgcat 1.4.2. All these
packages are in the 'tclkit' which is included in the pfm distribution.


3. Installation on linux-x86
----------------------------

You can either install pfm at system level, such that it is available
for all users, or at individual user level. The installation procedure
is the same, unless specified otherwise.

  1. Put the pfm-2.0.8-linux-x86.tar.gz file that you have downloaded
     in a temporary location and open a terminal window.

  2. Unpack that file using

     tar --extract --gunzip --file=pfm-2.0.8-linux-x86.tar.gz

  3. cd to the directory pfm-2.0.8-linux-x86 that was created as a
     result from the extract operation.

  4. If you want to install pfm at system level, login as root by typing

     su

     Note: On some Linux systems (such as Ubuntu), you cannot login as
           root using 'su'. On these systems, immediately start the
           installation script by typing

           sudo ./install.tcl

           Then continue at point 6.

  5. Start the install.tcl script by typing

     ./install.tcl

  6. Just answer a few questions and that's it!

     This is what the installer does.

        - Copy all the necessary files and the source files of pfm
          to the installation directory of your choice.

        - Install tclkit and pgintcl unless you choose to use other
          equivalent packages already installed on your computer.

        - Install a launch shell script called 'pfm' in a directory
          of your choice. If that directory is in your PATH, you can
          start pfm from the command line by typing 'pfm'.

        - Install an entry in the applications menu. You will
          probably find it in the 'Office' submenu. This only works
          if you have the 'xdg-utils' on your computer.

        - Install a desktop icon on your desktop. This only works for
          an installation at individual user level and if you have the
          xdg-utils on your computer.

        - Install a deskop file called 'pfm-postgresforms.desktop' in
          the installation directory which acts as a program launcher
          and which you can copy to the desktop or to any other
          location of your choice.

        - Install a script called 'uninstall.tcl' in the installation
          directory and which you can execute to uninstall pfm.


4. Installation on other UNIX architectures
-------------------------------------------

Note: Please note that pfm has not been tested on any UNIX architecture
      other than linux-x86. It may or may not work on other architectures.

  1.  Download pfm-2.0.8-linux-x86.tar.gz.

  2.  Do steps 1 through 3 of the previous section.

  2.  Download a tclkit version 8.5 for your architecture from

      http://www.equi4.com/tclkit.html     or

      http://code.google.com/p/tclkit/

      Unpack it, install it in the current directory
      (pfm-2.0.8-linux-x86) and rename it to 'tclkit'.

      Don't forget to make it executable with 'chmod a+x tclkit'.

  3.  Continue at step 4 of the previous section.


5. Installation on Windows
--------------------------

From version 2.0.0 on, pfm comes as an executable which is an NSIS
installer program (see http://nsis.sourceforge.net for more information
on NSIS).

Just run the executable

pfm-2.0.8-windows-32.exe

that you have downloaded.

After installing you may need to change the psql option such that
pfm can find the psql.exe program of PostgreSQL.

The installer program does the following:

  1. It installs all the necessary files in a directory pfm-2.0.8 under
     "Program Files".

  2. It creates a subdirectory pfm-2.0.8 in the start menu under
     "programs".

  3. In that subdirectory pfm-2.0.8:

        - it installs a shortcut "pfm" to launch pfm;

        - it installs a shortcut "Website" which brings you to the
          home page of pfm;

        - it installs a shortcut "Uninstall" which uninstalls pfm;

        - it installs all the source files of the program.

  4. It installs a shortcut pfm-2.0.8 on the Desktop to launch pfm.

  5. It installs an uninstall entry in the windows register under
     HKEY_LOCAL_MACHINE:

     Software\Microsoft\Windows\CurrentVersion\Uninstall\pfm-2.0.8

    This makes pfm-2.0.8 to appear in the list of installed programs
    under "Software" in the "Control panel".
