5.3 Creating Windows Installers

Executable installers are the natural format for binary distributions on Windows. They display a nice graphical user interface, display some information about the module distribution to be installed taken from the metadata in the setup script, let the user select a few options, and start or cancel the installation.

Since the metadata is taken from the setup script, creating Windows installers is usually as easy as running:

python setup.py bdist_wininst

or the bdist command with the --formats option:

python setup.py bdist --formats=wininst

If you have a pure module distribution (only containing pure Python modules and packages), the resulting installer will be version independent and have a name like foo-1.0.win32.exe. These installers can even be created on Unix or Mac OS platforms.

If you have a non-pure distribution, the extensions can only be created on a Windows platform, and will be Python version dependent. The installer filename will reflect this and now has the form foo-1.0.win32-py2.0.exe. You have to create a separate installer for every Python version you want to support.

The installer will try to compile pure modules into bytecode after installation on the target system in normal and optimizing mode. If you don't want this to happen for some reason, you can run the bdist_wininst command with the --no-target-compile and/or the --no-target-optimize option.

By default the installer will display the cool ``Python Powered'' logo when it is run, but you can also supply your own bitmap which must be a Windows .bmp file with the --bitmap option.

The installer will also display a large title on the desktop background window when it is run, which is constructed from the name of your distribution and the version number. This can be changed to another text by using the --title option.

The installer file will be written to the ``distribution directory'' -- normally dist/, but customizable with the --dist-dir option.

5.3.1 The Postinstallation script

Starting with Python 2.3, a postinstallation script can be specified which the --install-script option. The basename of the script must be specified, and the script filename must also be listed in the scripts argument to the setup function.

This script will be run at installation time on the target system after all the files have been copied, with argv[1] set to -install, and again at uninstallation time before the files are removed with argv[1] set to -remove.

The installation script runs embedded in the windows installer, every output (sys.stdout, sys.stderr) is redirected into a buffer and will be displayed in the GUI after the script has finished.

Some functions especially useful in this context are available as additional built-in functions in the installation script.

directory_created( path)
file_created( path): These functions should be called when a directory or file is created by the postinstall script at installation time. It will register path with the uninstaller, so that it will be removed when the distribution is uninstalled. To be safe, directories are only removed if they are empty.

get_special_folder_path( csidl_string)

This function can be used to retrieve special folder locations on Windows like the Start Menu or the Desktop. It returns the full path to the folder. csidl_string must be one of the following strings:

"CSIDL_APPDATA"

"CSIDL_COMMON_STARTMENU"
"CSIDL_STARTMENU"

"CSIDL_COMMON_DESKTOPDIRECTORY"
"CSIDL_DESKTOPDIRECTORY"

"CSIDL_COMMON_STARTUP"
"CSIDL_STARTUP"

"CSIDL_COMMON_PROGRAMS"
"CSIDL_PROGRAMS"

"CSIDL_FONTS"

If the folder cannot be retrieved, OSError is raised.

Which folders are available depends on the exact Windows version, and probably also the configuration. For details refer to Microsoft's documentation of the SHGetSpecialFolderPath() function.

create_shortcut( target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]): This function creates a shortcut. target is the path to the program to be started by the shortcut. description is the description of the shortcut. filename is the title of the shortcut that the user will see. arguments specifies the command line arguments, if any. workdir is the working directory for the program. iconpath is the file containing the icon for the shortcut, and iconindex is the index of the icon in the file iconpath. Again, for details consult the Microsoft documentation for the IShellLink interface.

See About this document... for information on suggesting changes.