Building PyGE Distributions --------------------------- PyGE software is released in two forms: source distributions for all platforms, and binary distributions for a few supported systems (primarily the ones I use). Building these distributions from source requires a little explanation. Fully automating the process is something on the list of future things to do, but does not have a very high priority right now. Source distributions -------------------- Pythons distutils module makes creating source distributions relatively easy. In general, the following command line is all that is needed: python setup.py sdist This command is run within the PyGE directory which contains the source files and the setup.py script. It creates a dist directory if one is not present, then generates source distribution archives within that directory. The one cross-platform issue that I have encountered is the need to make text source files compatible with the platform they will be used on. By compatible, I mean the form of line terminators used to mark the end of a line. On Unix and Linux systems, the line terminator is a single linefeed character (hex value 0A). On MS Windows systems, the line terminator is a two-character pair of carriage return and a linefeed (hex values 0D, 0A). On Apple Macintosh systems, the line terminator is a single carriage return character (hex value 0D). To address this issue, PyGE source distributions are produced in two flavors: one for Unix/Linux and one for Windows (not having an Apple system, I am unable to properly test this variant). The Unix/Linux version is packaged as a tarred and gzipped archive (PyGE-x.x.x.tar.gz), while the Windows version is packaged as a zipped archive (PyGE-x.x.x.zip). My development work is done primarily on Linux, so I make all source changes on files with Unix line terminators. When it's time to create a new set of distribution files, I use the script make_win_version.py found in the Utility directory to create a Windows compatible set of files. The command to make this conversion is: make_win_version.py PyGE The command is run at the directory level containing the directory where source files are located (in this case named PyGE). It creates a new directory called PyGE_WIN and populates it with converted source files. One further step must be taken in any converted directory before building a new source distribution: the program help files must be rebuilt. Help files from Linux/Unix systems do not appear to work properly when used on Windows systems. Rebuilding is a simple process. Each help file is a zipped file containing the contents of one of three directories: docs/PyGEMZ, docs/PyGETS, and docs/PyGERS. As an example, on my Linux system I can change to the docs/PyGEMZ directory in the source distribution, perform a "zip pygemz *" command, and rename the resulting zip file to pygemz.htb. The new help files are then moved to the top level of the source distribution files. The command script "make_helpfiles.cmd" located in the top level of the source distribution directory may be used as a shortcut for these commands on a Unix or Linux system. The normal distutils command for producing a source distribution is then run in the PyGE_WIN directory to produce the Windows-compatible distribution file. python setup.py sdist Going the opposite direction and working with Windows text source files, then converting to Unix/Linux compatible format is also possible. The Utility directory also contains a make_nix_version.py script supporting this approach. Binary distributions -------------------- Windows ------- Binary executables for MS Windows are created with the help of two third-party tools: py2exe and Inno Setup. Py2exe creates executable files from Python programs that can be installed and run on any Windows systems without the need to first install Python or third-party extensions. The result of running py2exe is an .exe file for each application script, a collection of required library files (.dll, .pyd), and developer-specified data files. Further information on py2exe can be found at: http://starship.python.net/crew/theller/py2exe/ Inno Setup is a Windows program for creating program installers. It takes the files produced by py2exe, and following a configuration script, creates an installation program that will install PyGE software in a user-specified location, set up Start Program shortcuts for PyGE programs, and allow for regular Windows uninstallation of PyGE software from the Control Panel. Further information on Inno Setup can be found at: http://www.jrsoftware.org/isinfo.php The process for creating the installation executable requires a few manual steps, but is relatively straightforward. After first installing py2exe, Inno Setup, and a source distribution for PyGE on a Windows machine, the following steps need to be performed: 1. Change to the location of the source distribution files, i.e. D:\PyGE-0.x.x. 2. Open an MSDOS window and change the current directory to the location of the source distribution files. 3. Edit the setup.cfg file to remove the semi-colon comment marker from the configuration line containing the string "PyGEMZ", and place a semi-colon in front of the other two lines containing the words "version-filedescription". 4. Type in a command with the following form: D:\Python22\python.exe buildmz.py py2exe where the first part of the command is the location of the installed Python interpreter, and the second part is the script for building an executable for the PyGEMZ program. The result should be a long stream of messages as py2exe does its work. If the process completes successfully, there should be a subdirectory called dist\pygemz in which a file named pygemz.exe has been created. 5. Now edit the setup.cfg file to remove the semi-colon comment marker from the configuration line containing the string "PyGETS", and place a semi-colon in front of the other two lines containing the words "version-filedescription". 6. Type in a command with the following form: D:\Python22\python.exe buildts.py py2exe where for this case the second part is the script for building an executable for the PyGETS program. The result should again be a long stream of messages as py2exe does its work. If the process completes successfully, there should be a subdirectory called dist\pygets in which a file named pygets.exe has been created. 7. Finally edit the setup.cfg file to remove the semi-colon comment marker from the configuration line containing the string "PyGERS", and place a semi-colon in front of the other two lines containing the words "version-filedescription". 8. Type in a command with the following form: D:\Python22\python.exe buildrs.py py2exe where for this case the second part is the script for building an executable for the PyGERS program. The result should again be a long stream of messages as py2exe does its work. If the process completes successfully, there should be a subdirectory called dist\pygers in which a file named pygers.exe has been created. 9. Create a directory dist\pyge in the source distribution directory if one is not already present. Copy into dist\pyge all the files created by py2exe in dist\pygemz, dist\pygets, and dist\pygers. There will be a number of duplicate files, but one copy of each unique file is all that is needed. 10. Edit the configuration file for Inno Setup named pyge.iss to change all directory references containing D:\Tmp\PyGE-0.x.x\ to instead point to the actual location of the source distribution files. 11. Start Inno Setup and load the pyge.iss file you just edited with a File->Open menu command. Begin compiling with a File->Compile menu command. If Inno Setup successfully finishes, there should be a file named Output\setup.exe. This file is the generated installation program for PyGE. You can rename this file to something more appropriate, such as pyge-060-win.exe. Linux (User-mode Installations) ------------------------------- Binary executables for Linux are created with the help of two third-party tools: Installer from McMillan Enterprises and Linstall Wizard from New Republic Software. Installer is a set of Python scripts that perform a function on Linux that is similar to what py2exe does on Windows. It analyzes a Python script to determine what other modules and extensions are used, and collects all the script-related components that are required to run the script into a single directory. It then creates an executable file that can be run on Linux systems with minimum installation or dependency requirements. Further information on McMillan Enterprise's Installer can be found at: http://www.mcmillan-inc.com/install1.html Linstall Wizard is a program that allows Linux program files to be packaged into a single self-installing executable which presents a simple graphical interface to users when run. A free version is available for distributing non-commercial programs. Further information about Linstall Wizard can be found at: http://www.newrepublicsoftware.com/ After installing the Installer and Linstall Wizard tools (installation with just user privelages in a home directory works fine), creation of a binary distribution requires performing the following steps: 1. Change to the Installer directory in the top level of the source distribution. Edit the lines indicated in the three files pygemz/pygemz.spec, pygets/pygets.spec, and pygers/pygers.spec to match the locations of relevant files on your system. 2. Change to the directory containing the Installer package files. There should be a script named Build.py present. Execute the following three commands, substituting the actual locations of the three spec files you modified in step 1 above. python Build.py /home/bob/PyGE/Installer/pygemz/pygemz.spec python Build.py /home/bob/PyGE/Installer/pygets/pygets.spec python Build.py /home/bob/PyGE/Installer/pygers/pygers.spec If successful, each command should produce a directory where the spec file resides that begins with "dist", such as distpygemz in the /home/bob/PyGE/Installer/pygemz directory for the example cited above. This new directory should contain an executable file with the name of the PyGE application (pygemz, pygets, pygers) along with library files needed to run the program. 3. All of the files produced by step 2 above should be copied to another temporary directory, such as /home/bob/PyGE/Tmp to continue following our example. This temporary directory should then contain the executable files pygemz, pygets, pygers, and a group of library files with .so extensions. Any X libraries with names of the form libX*.so.6 that are present in the temporary directory should be deleted. 4. Into this temporary directory copy the LICENSE file, the entire SampleData directory, and the three files with .htb extensions from the source distribution directory. Also copy the README file and the shell script files pygemz/pygemz.sh, pygets/pygets.sh and pygers/pygers.sh from the Installer directory of the source distribution. Finally, copy the wxGTK library file (with a name like libwx_gtkd-2.4.so) into the temporary directory. The temporary directory now contains the files of the desired binary distribution. 5. Linstall Wizard is used to package the binary distribution files into a single self-installing executable file. Change to the directory where Linstall Wizard has been installed (if it was installed with user privelages) and enter the command "./Linwiz". A window will appear, presenting a series of questions for the user to answer concerning how to configure the desired installation program. Most questions require only a simple response, and are relatively intuitive. Refer to the Linstall Wizard documentation for details. After the Wizard successfully finishes, it should inform you where it has placed the newly generated executable installer for your program. Locate this file and rename it to something more appropriate, such as PyGE_060_linux_debian_gcc295.install. Linux (System Installations) ---------------------------- Binary distribution packages can also be created that require root privelages to install files as globally accessible system files. Support files have been created to allow building distribution packages with the ESP Package Manager (EPM) program from Easy Software Products. EPM allows creating distributions in many package formats using a single common list file to specify distribution contents. Supported formats are a highly portable format developed by ESP, the Redhat package management (rpm) and Debian dpkg (deb) formats for Linux, and numerous Unix vendor-specific distribution formats. Further information about EPM can be found at: http://www.easysw.com/epm/ The process of building a distribution package with EPM follows the first four steps described above for generating distribution files with Installer. The remaining steps are as follows: 5. Copy the PyGETS, PyGEMZ, and PyGERS shell script files from the Installer/epm directory of the source distribution into the temporary directory of step 4. Also copy the README.portable, README.debian, and README.redhat text files from the Installer/epm directory into the temporary directory. 6. Change to the directory containing the temporary directory of step 4, and copy the pyge.list and logo.xpm files from the Installer/epm directory there. Edit the line in pyge.list which begins with $srcdir to assign the name of the directory where distribution files are to be found. 7. Distribution packages are created with the epm command. The following commands can be used to create three different package formats for Linux systems. The portable format includes both command-line and graphical installer programs in the package. epm --setup-image logo.xpm pyge pyge.list (portable format) epm -f rpm pyge pyge.list (RPM format) epm -f deb pyge pyge.list (Debian format) The output package files will be generated in a directory with a name following the form os-major.minor-arch, such as linux-2.4-intel. Portable package files will have an extension of .tar.gz, RPM package files will have an extension of .rpm, and Debian package files an extension of .deb.