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.