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_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.
Where allowed options are:
>python Makespec.py [OPTIONS] script...
[For building with optimization on (like
- produce a single file deployment.
- produce a single directory deployment (default).
- include TCL/TK in the deployment.
- do not include encodings. The default (on Python versions with unicode support) is now to include all encodings.
- use debug versions of the executables.
- Windows: use the Windows subsystem executable (runw.exe or runw_d.exe).
- 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.
Python -O), see below.]
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
buildproject subdirectory will be created in the specfile's directory. This is where the persistence files (and anonymous targets) go, so that
Build can act like a makefile. Any named targets will appear in the specfile's directory.
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
will generate a new script
>python MakeCOMServer.py [OPTION] script...
drivescript.py and a spec file for the script.
These options are allowed:
- Use the verbose version of the executable.
- Register the COM server(s) with the quiet flag off.
- do not include encodings (this is passed through to Makespec).
- --out dir
- Generate the driver script and spec file in dir.
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,
MakeCOMServer also assumes that your top level code (registration etc.) is "normal". If it's not, you will have to edit the generated script.
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 ...
Py_OptimizeFlag will be set if you use a
('O','','OPTION') in one of the
TOCs building the
exe = EXE(pyz,
a.scripts + [('O','','OPTION')],
See Spec Files for details.