Pam (Python to AMulet interface) provides an interactive, interpreted 
interface to the Amulet graphical interface development environment via
the Python language. Using Pam, one can rapidly prototype applications 
by creating graphical objects and callback procedures in Python, and then 
using Amulet as a backend for displaying the graphical objects and calling 
the Python callback procedures. For simplicity, Python only supports a 
subset of Amulet, although we believe that it is the subset used the great 
majority of the time. 

PLATFORMS ON WHICH PAM RUNS

Pam has been successfully installed under SunOs 4.1.4 and Solaris 5.5.1
using g++ version 2.7.2.1, Python 1.4, and Amulet 3.0 beta. Since Python
and Amulet both run under other versions of Unix, and on the Windows and 
Macintosh operating systems, it is possible that Pam will run in these
other environments as well. Feel free to try to make Pam run in these
environments and if you succeed, please email the installation instructions
to Brad Vander Zanden (bvz@cs.utk.edu).

DOCUMENTATION

There are three documents describing Pam: tutorial.html, ref.html, and
faq.html. These files can be found in the doc directory.
tutorial.html provides a good interactive introduction to Pam. ref.html
provides a complete reference manual for Pam. faq.html provides answers
to some frequently asked Pam questions.

LICENSE

Pam 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. A copy of the license can be
found in the file called COPYING. If you cannot locate this file, write
the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA
for a copy of the license.

INSTALLING PAM

You will notice that the tar directory has three subdirectories named
doc, pam, and amulet. doc contains the documentation files. pam contains
.py files that implement pam. amulet contains the c++ extension files
needed to interface pam with amulet. The installation instructions are
different for Solaris and SunOs so find the appropriate installation
instructions for your platform below and follow them.

INSTALLATION INSTRUCTIONS FOR SOLARIS

Solaris supports dynamic libraries and that is the most space efficient
way to compile Pam for a Solaris machine. The following procedure should
successfully install Pam:

1. Type:
    
    cd amulet
    cp Makefile.Solaris Makefile
    
    Make sure that the AMULET_DIR, AMULET_VARS_FILE, and PYTHON environment 
	variables are set to the appropriate top-level amulet directory,
	amulet Makefile, and top-level python directories respectively.

    NOTE: You cannot use ~ in the paths when using python. It doesn't 
	understand them.  For example, you must write out /azure/homes/bvz/
	instead of ~bvz/.

2. Build amuletmodule with the command

	make

3. Install the pam*.py and amuletmodule.o files in a place where
     Python can find them. To do this, create a pam directory in the
     directory where you would like to store pam:

	cd chosen-directory
	mkdir pam
	cd pam

    a. Copy the pam/pam*.py files from the tar directory into this new 
	directory.
 
    b. Copy the amuletmodule.so file that you created in step 2 into this
	new directory.

    c. If the PYTHONPATH environment variable is undefined, type:

	setenv PYTHONPATH 'DIRNAME/pam'

	where DIRNAME is the location of the pam directory. For example:

	setenv PYTHONPATH '/azure/homes/bvz/pam'

	If you already define the PYTHONPATH environment variable, add
	DIRNAME/pam to the list of paths, where DIRNAME is the location of
	the pam directory.

	NOTE: You cannot use ~ in the paths when using python. It doesn't 
	    understand them.  For example, you must write out /azure/homes/bvz/
	    instead of ~bvz/.

You should now be able to run Python and import pam.

INSTALLATION INSTRUCTIONS FOR SUNOS

Using dynamic libraries for Pam in the Sun's BSD environment does not
seem to work so it is necessary to compile Pam into Python. The following
procedure does the trick. 

1. Create a Makefile that will build amuletmodule.o. First cd to the amulet
	directory:

	cd amulet

    The Makefile can now be created in one of two ways:

    a. Type:

	mv Setup.SunOs Setup.in
	make -f Makefile.pre.in boot

	This command is Python's standard way of making a module. 

    b. Copy Makefile.SunOs to Makefile. Make sure that the AMULET_DIR
	and PYTHON_DIST_PATH environment variables are set to the appropriate
	top-level amulet and python directories. Note that while Amulet
	users customarily set the AMULET_DIR environment variable, Python
	users do not normally set the PYTHON_DIST_PATH environment variable.
	Consequently, you will probably need to explicitly set this
	environment variable to your system's Python distribution files.
	For example, on my system I type:

	setenv PYTHON_DIST_PATH /sunshine/homes/bvz/Python-1.4

2. Build amuletmodule.o with the command

	make amuletmodule.o
    
3. Copy amuletmodule.o to PYTHON_DIST_PATH/Modules, where 
     PYTHON_DIST_PATH is the path to your system's Python distribution files.

4. Copy Setup.local to PYTHON_DIST_PATH/Modules, or, if Setup.local
	already exists in the Modules directory, copy the lines in
	Setup.local to the Setup.local in the Modules directory.

5. cd to PYTHON_DIST_PATH. 

6. Run the ./configure command using whatever flags you normally pass
	to ./configure. In addition to these flags, add the --with-libs
	flag and add libraries for X11 and amulet. For example, my
	./configure command looks as follows:

    ./configure --prefix=/sunshine/homes/bvz/Python-1.4 \
        --with-libs='-L/usr/local/X11R6.1/lib -lX11 -L/usr/local/lib/amulet/lib -lamulet'
 
    The ./configure command will *not* make all your compiled python code
	obsolete. It will simply update the appropriate Makefiles so that
	Python gets linked with the correct X11 and amulet libraries.

    The loader does care about the ordering of the -l flags. If you
	encounter link errors during the install, try reordering the 
	--with-libs string so that -L/usr/local/lib/amulet/lib -lamulet
	precedes -L/usr/local/X11R6.1/lib -lX11.
 
7. cd to PYTHON_DIST_PATH/Modules.  We'll do most of the rest
     of the work here.

8. Issue the command 

	touch amuletmodule.c

     This creates an empty file called amuletmodule.c.

9. Wait a few moments and then issue

	touch amuletmodule.o

     This gives the amuletmodule.o file that you just copied into
     this directory a timestamp that's later than its supposed
     source, amuletmodule.c. Python's make file will be content not to 
     try and compile amuletmodule.c, and both amuletmodule.c and
     amuletmodule.o will be present so the Makefile will work
     correctly.


10. Edit the Setup file in this directory in the following fashion:

     a. Add the line:
	
	amulet amuletmodule.c

        to the end of the Setup file. This line causes Python to include 
	amuletmodule.o in the python binary.

     b. Add the line

	PAMPATH=:$(DESTLIB)/pam

        to the Setup file *before* the assignment to COREPYTHONPATH

     c. Modify the COREPYTHONPATH assignment to be

        COREPYTHONPATH=$(DESTPATH)$(SITEPATH)$(TESTPATH)$(MACHDEPPATH)
            $(STDWINPATH)$(TKPATH)$(PAMPATH)

        Put this all on one line without any line breaks.   The main
        thing here is have $(PAMPATH) appended to the end of whatever
        COREPYTHONPATH was originally. The effect of this assignment
	is to allow Python to find the .py Pam modules that you will
	copy to the directory pointed to by $(DESTLIB)/pam.

11. cd to PYTHON_DIST_PATH. Type

	make 

     Once make has finished, you may wish to strip the Python executable:

	strip python

     On my system, python drops from about 10 Mbytes to just over
     2.5 Mbytes!  Since everything is statically linked and Amulet
     is so big, it's a step worth considering.  

12. The last step is to install the pam*.py files in a place where
     Python can find them. There are two ways to do this:

    a. Find the standard Python import library location and make a directory
         in this location called pam. Copy all the pam/pam*.py files from the 
	 tar directory into this new directory.

       Usually the import library location is in 
	PYTHON_DIST_PATH/lib/python1.4. If this directory does not exist, 
	you can find the import library location in one of two ways:

	i. enter the Python interpreter and type

		import sys
		sys.path

	    The first pathname you see after the empty string ('') is
		the import library location. For example, on my system 
		when I type sys.path I get:

                ['', '/usr/local/lib/python1.4', 
		 '/usr/local/lib/python1.4/test', 
		 '/usr/local/lib/python1.4/sunos5', 
	         '/mdx/usr/local/lib/python1.4/sharedmodules', 
		 '/usr/local/lib/python1.4/tkinter']

		The first pathname after the empty string is
		/usr/local/lib/python1.4, which is the location of the
                import library on my system.

	ii. find the value of the environment variable DESTLIB in the 
		Makefile in PYTHON_DIST_PATH/Modules.

    b. Create a pam directory in an arbitrary location and copy all the
	pam/pam*.py files from the tar directory into this new directory.
 	If the PYTHONPATH environment variable is undefined, type:

	setenv PYTHONPATH 'DIRNAME/pam'

	where DIRNAME is the location of the pam directory. For example:

	setenv PYTHONPATH '/azure/homes/bvz/pam'

	If you already define the PYTHONPATH environment variable, add
	DIRNAME/pam to the list of paths, where DIRNAME is the location of
	the pam directory.

	NOTE: You cannot use ~ in the paths when using python. It doesn't 
	    understand them.  For example, you must write out /azure/homes/bvz/
	    instead of ~bvz/.

You should now be able to run Python and import pam.
