Freezing the Python Apps

Overview

"Freezing" a python application refers to the process of starting from a python script (or set of scripts) and creating an executable program that can be run on another machine without requiring them to install dependencies, or even Python itself. Several software packages can do this, but they differ in scope and focus. For our current programs we use PyInstaller (DeepMedic, Theia) and Nuitka (Confetti). Generally PyInstaller is the preferred mechanism, but Nuitka is useful when Python 2.7 or older code needs to be supported.

Apps frozen in this way can be added to CaPTk as binaries.

PyInstaller

PyInstaller can be installed as a python module through pip (mind the capitalization of PyInstaller). You can then run it with: python -m PyInstaller myspecfile.spec where myspecfile.spec is the .spec file in the source directory of the python app, e.g. theia_source/Theia_Windows.spec The spec files should contain all the information needed for PyInstaller to successfully generate an executable. Do note that since PyInstaller copies parts of python from your machine, you must have installed all dependencies first. Basically, if the Python script runs correctly on your machine, then you can proceed to try and freeze it.

Nuitka

Nuitka can also be installed through pip. In fact, it is highly recommended that you ensure Nuitka is running from the same version of python that you are attempting to freeze code from. However, nuitka lacks the specification file concept. Instead you will need to pass command line arguments. Also, unlike PyInstaller Nuitka does not generate a single-file executable. Rather, it creates a "MyPythonApp.dist" folder containing all the shared objects as well as an executable. As long as the contents of this folder are kept intact, the executable will run alongside them. As with PyInstaller, nuitka will copy dependencies from your machine, so make sure you have all dependencies (and correct versions of them) required.

Building Theia with PyInstaller

Use PyInstaller the Theia_Windows.spec file in theia_source. Keep in mind that the versioning for VTK is very finicky -- if you are running python 3.6 or 3.7, then VTK 7.11.1 will NOT be available through pip. However, experimentation has revealed that VTK 8.1.2 is available on pip for these versions and does not break the PyInstaller functionality. Be warned that later versions of VTK include some functionality that breaks PyInstaller.

Building ConfettiGUI with Nuitka

Note that on Linux, ConfettiGUI is distributed as a .py script file with CaPTk. Creating the ConfettiGUI.exe executable only needs to be done for Windows. The below instructions work as of 7/22/2020, but as the dependencies are very old this may get more difficult as time goes on. Nevertheless, the below instructions should help make this as painless as possible.

Getting ConfettiGUI.exe built on Windows

Make sure for every step you are using Python 2.7, 64 bit -- this is a necessity.

You can help ensure this by using python2 -m before commands, ex:

python2 -m pip install nuitka

Whenever you see python2, you can replace it with the direct path to Python 2.7's python executable if necessary. Or, if Python 2.7 is the first/only python in the PATH, just call "python".

When it is time to run nuitka, you should do so through this command while inside the confetti_source/PyGUI directory:

python2 -m nuitka --standalone --file-reference-choice=runtime --follow-imports --plugin-enable=numpy --plugin-enable=qt-plugins ConfettiGUI.py (you can use the --output-dir= option to specify where the output should be created)

download SIP version 4.16 from https://sourceforge.net/projects/pyqt/files/sip/sip-4.16/

run the following in the extracted directory (make sure you're using the correct python): python2 configure.py

open an MSVC developer command prompt ( see https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=vs-2019 ) Make sure you've got the appropriate x64 vars, try using vcvarsall amd64.

make sure you are in the SIP directory

run nmake, then

run nmake install

numpy: python2 -m pip install numpy

vtk: Install using either pip or a downloaded wheel file. Either should work provided you have the wheel tool installed.

I got mine from: https://www.lfd.uci.edu/~gohlke/pythonlibs/#vtk (see the file VTK‑7.1.1‑cp27‑cp27m‑win_amd64.whl)

Use an installer for the following (the specific version is required): PyQt4 version 4.11 (based on Qt 4.8.x) installed from https://sourceforge.net/projects/pyqt/files/PyQt4/PyQt-4.11/

(Side note: if on linux, you must use your package manager to install PyQt4 -- it cannot be installed from pip and only specific versions work.)

Copy from CaPTk's binaries (if these are somehow unavailable, you'll need to build Confetti using CMake. Good luck.): We need the resulting shared object file (ConfettiCore.dll on windows) -- copy it.

Finally, run nuitka as described at the top of this document -- there will probably be some warnings about maybe needing additional options which can safely be ignored. A ConfettiGUI.dist directory will be produced. This contains a bunch of shared object files as well as the ConfettiGUI executable. Paste the previously copied files into this directory.