Sitemap

Getting Started

First, unpack the archive wherever you want to. Installer is not a Python package, so it doesn't need to go in site-packages, or have a .pth file. You will be using a couple of scripts in the root directory, and these will find everything they need from their own location.

You will need a separate copy for each Python version you wish to work with (or you'll need to rerun Configure.py every time you switch).

I - Building the runtime executables

On non-Windows platforms, the first thing to do is build the runtime executables. Windows users can skip this step, because all of Python is contained in pythonXX.dll, and Installer will use your pythonXX.dll.

Before building, you need to decide what strategy you want the runtime executables to use. On ELF platforms, you can concatenate arbitrary data onto an executable and still have an executable. This is the strategy Installer will use on Linux and cygwin systems (since most of them are Intel-like hardware). Where this trick doesn't work, Installer has an alternate stategy: the runtime executable looks at its name, and then looks for a file in its directory called exename.pkg. This strategy is used on non-Linux platforms, and can be enabled by using the -n option to Make.py. So if your system is Linux on a non-ELF platform, you'll need to use the -n option. Conversely, if your system is ELF, but not Linux (eg, Solaris), you can use the -e option to set the ELF strategy. The non-ELF strategy works fine on ELF platforms, too, so the choice is yours.

Change to the source/linux subdirectory. Run Make.py [-n|-e] and then make. This will produce support/run and support/run_d. If you have multiple versions of Python, the Python you use to run Make.py is the one whose configuration is used.

Windows distributions come with four executables in the support dir: run.exe, run_d.exe, runw.exe and runw_d.exe. There are also two dlls, inprocsrvr.dll and inprocsrvr_d.dll for doing in-process COM servers. All of these can be rebuilt from the MSVC workspace in source/windows. (I'm fairly sure these could be built using MinGW, too, but I haven't yet tried it).

Note that the _d suffix does not mean the same as it does with extension modules - you don't need a debug build of Python to use them.

II - Configuring your Installer setup

In the root directory, run Configure.py. This saves some information into config.dat that would otherwise be recomputed every time. It can be rerun at any time if your configuration changes. It must be run before trying to build anything.

III - Create a spec file for your project

[For Windows COM server support, see below.]

The root directory has a script Makespec.py for this purpose.

       >python Makespec.py [OPTIONS] script...
      

--onefile

produce a single file deployment.

--onedir

produce a single directory deployment (default).

--tk

include TCL/TK in the deployment.

--ascii

do not include encodings. The default (on Python versions with unicode support) is now to include all encodings.

--debug

use debug versions of the executables.

--noconsole

Windows: use the Windows subsystem executable (runw.exe or runw_d.exe).

--strip

the executable and all shared libraries will be run through strip. Note that cygwin's strip tends to render normal Win32 dlls unusable.

--out directory

create the spec file in directory. If not specified, and the current directory is Installer's root directory, an output subdirectory will be created. Otherwise the current directory is used.

--icon file.ico

add file.ico to the executable's resources (Windows only).

--icon file.exe,n

add the nth incon in file.exe to the executable's resources (Windows only).

--version verfile

add verfile as a version resource to the executable (Windows only).

--name name

optional name to assign to the project (from which the spec file name is generated). If omitted, the basename of the (first) script is used.

For simple projects, the generated spec file will probably be sufficient. For more complex projects, it should be regarded as a template. The spec file is actually Python code, and modifying it should be much easier than working with the config files used in earlier Installer releases. See Spec Files for details.

IV - Build your project

      >python Build.py specfile
      

In most cases, this will be all you have to do. If not, see When things go wrong and be sure to read the introduction to Spec Files.

Windows COM Server support

       >python MakeCOMServer.py [OPTION] script...
      

These options are allowed:

--debug

Use the verbose version of the executable.

--verbose

Register the COM server(s) with the quiet flag off.

--ascii

do not include encodings (this is passed through to Makespec).

--out dir

Generate the driver script and spec file in dir.

Now run Build.py on the generated spec file.

If you have the win32dbg package installed, you can use it with the generated COM server. In the driver script, edit the registration line(s) as follows:

          register.UseCommandLine(class, debug=1, quiet=0)
      

Warnings: the inprocess COM server support will not work when the client process already has Python loaded. It would be rather tricky to non-obtrusively hook into an already running Python, but the show-stopper is that the Python/C API won't let me find out which interpreter instance I should hook into. To use a "frozen" COM server from a Python process, you'll have to load it as an exe:

      o = win32com.client.Dispatch(progid,
                       clsctx=pythoncom.CLSCTX_LOCAL_SERVER)
      

MakeCOMServer also assumes that your top level code (registration etc.) is "normal". If it's not, you will have to edit the generated script.

Building Optimized

There are two facets to running optimized: gathering .pyo's, and setting the Py_OptimizeFlag. Installer will gather .pyo's if it is run optimized:

       >python -O Build.py ...
      

The Py_OptimizeFlag will be set if you use a ('O','','OPTION') in one of the TOCs building the EXE.

      exe = EXE(pyz,
                a.scripts + [('O','','OPTION')],
                ...
      

See Spec Files for details.