Installation instructions for GNUe-Forms
========================================

Quick Install
-------------
First, install the GNUe Common package.

Make sure that you have a valid /usr/local/gnue/etc/gnue.conf.
This is installed by gnue-common package as a sample.gnue.conf.
You will have to copy sample.gnue.conf to gnue.conf and edit
gnue.conf to suit your needs.  Then, run:

 $ python2 setup.py install  (depending on your OS, this could
                              also be python2.1 or python2.2)

If you are upgrading from a version of forms prior to 0.5.0
please reference the Upgrading Forms section below.


Requirements
------------
Forms needs the following in order to run:

   * GNUe Common 0.5.3+

   * A user-interface library:
      - wxPython (http://www.wxPython.org)
      - GTK 2
      - QT 3
      - NCurses

Also, Forms can make use of the following tools if they are
installed:

   * GNUe Reports

   * GNUe AppServer


General Information
-------------------

Later there will be available interoperability for a variety of
database systems via GNUe common.

Also there is only one functional user-interface available at the time
of writing via wxWidgets. We will concentrate on the GTK Version of
wxWidgets which is available for X-Windows.

The (wx-)GNUe-forms client which interpret the forms definition is
written in Python. It is being tested with python 1.5 and 2.0.1

The rest of the document describes the steps to install GNUe-forms on
a Debian 2.2, i386 platform.

Debian packages to be installed
-------------------------------
You should apt-get install the following packages:

  python2.1-dev
  python2.1-egenix-mxdatetime
  libwxgtk2.4-python
  python2.1-psycopg  (if needed -- for PostgreSQL support)
  python2.1-mysqldb  (if needed -- for MySQL support)

This will also install other packages, such as libgtk, libwxgtk,
postgresql-client, et al.


Other software to be installed:
------------------------------

Some of the following files have to be downloaded and installed. I will
give short installation instructions and a compact list of the needed
files and sites at the bottom for convenient reference for
download. Space requirements are 6856 KByte for the downloaded files
and 79680 KByte for the fully built directories, plus the space of the
installed binaries. If you follow the described sequence you can
delete each directory in turn after having installed the respective
software.


  * PyGreSQL.tgz (http://www.druid.net/pygresql)
        Only needed for acceess to postgresql databases.
        Untar in some place. Enter in the directory PyGreSQL-3.0,
        issue "./setup.py build".
        PyGreSQL needs to find the postgres header files in other
        place then debian installs them. One workaround is
        "ln -s /usr/include/postgresql /usr/include/pgsql".
        As root issue finally "./setup.py install".

     Note: if you are on the bleeding edge PyGreSQL
       is also included in postgreSQL cvs tree at
       pgsql/src/interfaces/python/.  If you build
       postgresql from cvs be sure to configure with
       '--with-python' and PyGreSQL should be built with
       postgresql. (currently this is not recommended as
       there may be problems with python 2.x in cvs)

  * MySQLdb-0.3.2 (http://dustman.net/andy/python/MySQLdb/)
        Only needed to access to mysql databases.
        Note: The debian package is current too old and does not work
        Untar in some place. Enter in the directory, issue
        "python setup.py build" and as root "python setup.py install".

  * mxDateTime-2.x (http://www.lemburg.com/file/python/mxDateTime.html)
        Needed by several of the database drivers (including the
        PostgreSQL drivers). Untar in some place, enter the directory,
        and issue "python setup.py build" and as root "python setup.py
        install"

  * wxGTK-2.4 (http://www.wxWidgets.org)
        Untar in some place. Enter in the directory wxGTK, issue
        "./configure", "make" - this will run looong time, and then
        "make install" as root.

  * wxPython-2.4 (http://www.wxpython.org/download.php)
        Untar in some place. Enter in the directory wxPython-2.2.2,
        edit setup.py and change the following variables to the
        indicated value (if not you get a compile time error):

        BUILD_GLCANVAS = 0

        issue "./setup.py build" - this will run long time, and as
        root "./setup.py install"


Download table
--------------

Distutils-1.0.1.tar.gz:          www.python.org
PyGreSQL.tgz:                  www.druid.net/pygresql
wxGTK-2.2.2.tar.gz:          www.freiburg.linux.de/~wxxt/download.htm
wxPython-2.2.2.tar.gz:          www.wxpython.org/download.php
mxDateTime                www.lemburg.com/files/python/mxDateTime.html
                        (this link is gone as of 12 Jan 2002)
                        (this may be included in python 2.x?)
[pyncurses-0.3.tar.gz:          pyncurses.sourceforge.net]


Upgrading Forms
---------------
The 0.5.0 release of gnue-forms uses a gfd format that is incompatible
with prior releases.  A utility named gfd04to05.py has been provided
in the forms/utils/ directory that will convert a pre 0.5.0 form to the
new format.

 Usage:
   $ gfd04to05.py oldFormName.gfd newFormName.gfd

If you omit the second name (newFormName.gfd) then gfd04to05.py
will create a backup of your form in oldFormName.gfd-PRE050 then
overwrite the existing form with the new format.

