Sitemap

Getting Started

The first thing to do is pick a configuration. Installer can usually build any of the following configurations with one command:

Standalone.py

Produces a directory containing yoursrcipt.exe and all the dlls and pyds it requires. This is generally the easiest and certainly the simplest configuration to modify.

Simple.py

A single file that when executed, will unpack itself into a user chosen directory - like using Standalone and then packaging the directory in a self-extracting exe. But if you want a professional look, use Standalone and a real Installer / setup program.

Freeze.py

A single file executable. Actually, it unpacks itself at runtime, and cleans up when the run is done. Not very efficient, but definitely the easiest for the user to deal with.

To keep build stuff separate from development stuff, I usually create a new directory and copy the top level script into that directory. Then, for example:

       C:\Temp\buiddir>C:\Installer\Standalone.py myscript.py
      

(Windows) If your app uses Tkinter, use the -tk arg (you must have run SetupTK.py for this to work properly).

(Windows) If your app uses wxPython, or another GUI, use the -runw arg to get rid of the console window.

(Windows) If your app uses Mark Hammond's Win32 extensions, use the -win32 arg.

You'll see a slew of warning messages go by. But for most apps, that's all there is to it!.

When things go wrong...

...it's almost always the result of an import hack in the code you're freezing. An import hack is code that loads a module without using "import".

Tracking down the hack

Check out the extensions page and see if any of those situations pertain to you.

Examine the warning messages that came out when you built. (You may have to redirect the messages to a file: on Windows that means you can't use the short form of the command line - you must use python ... >msgs.txt.) Most of the messages will be OK, (e.g., on Windows, the mac, dos and os2 modules aren't there, and that's not a problem). If you see a "no module named..." message but you think it should be there, you may have to tweak your PYTHONPATH. If you see __import__, exec or eval in any module outside the standard library, you should check out what it's doing.

There are more debugging instructions here.

Fixing the problem

One way is to edit your code to do a normal "import" of the module before the hack ever runs. That way, the dependency will be tracked, the module included, and the hack will succeed at runtime.

The more general way is to edit myscript.cfg, which you'll find alongside myscript.py. You'll find the config file format documented here.

All Standalone, Simple and Freeze really do is fill in some blanks in some config file templates, write them out, and then execute Builder.py for you, (you'll see the command line at the top of the messages). Once you've tweaked the config file, you'll use:

       C:\Temp\buiddir>C:\Installer\Builder.py myscript.cfg
      

Most of the time, all you'll be doing is adding something to the packages or includes options of the section entitled [APPZLIB].

For more information...

Information about how the resulting executable works is here. How archives work is documented here.

Help with common extension modules and packages is here. There are also some utilities you might find useful.

Enjoy!