Windows Debugging Tips and Tricks

Background: Playing well with windows

Mailpile aims to provide a reliable and integrated experience on Windows. It tries to integrate into the Windows UI and provide expected indications and UI features. It also bundles it's own dependencies locally at known versions to ensure everything works as expected. Achieving these two goals makes debugging mailpile on windows slightly more challenging than other environments.

Mailpile environment script

All mailpile entry points use a helper script to allow mailpile to use it's own local dependencies. The helper script is at "path\to\mailpile\install\bin\with-mailpile-env.py". Chances are mailpile will only work when launched with help of that script unless you have manually configured your machine for mailpile development. Even if you have, it's useful to be able to test and reproduce bugs in the bundled environment. To use the script, you'll have to select an appropriate version of python.

Python's two windows flavors

Mailpile on Windows attempts to unobtrusively integrate with the window manager. Unlike Linux/Mac/POSIX, Windows desktop apps do not have standard IO streams by default, and use a different initialization/main pattern. In light of that, python provides two interpreters for windows: python.exe and pythonw.exe. Python.exe acts very similarly to how you'd expect python to work on a Unix platform(it's not the same, the OS APIs have incompatibilities). However, python.exe is built as a windows console app to do that, and is tide to a console window in the window manager. For those that do not want a console window, pythonw.exe is built as a desktop app. As such, it has several deviations from how python behaves on Unix. Here is a link to some stack overflow information for the curious.

Debugging on Windows

To debug mailpile on windows, you'll likely want to redirect stdout and stderr to somewhere. with-mailpile-env.py is usually used to route these to os.devnull so that they exist and pythonw.exe doesn't immediately throw an exception when they are referenced. However, that doesn't do anything useful for capturing output for debugging. Instead, with-python-env.py can be invoked in such a way to redirect them to files. The files will not be accessible/up-to-date while the interpreter is running, but afterwards they'll hopefully have helpful output. with-mailpile-env.py treats all options up to the first argument that doesn't start with a - as it's own, and the remainder as a command to execute. Here's an example of starting mailpile:

cd C:\path\to\mailpile\install
.\python27\pythonw.exe .\bin\with-mailpile-env.py --stdout=c:\path\to\stdout.log --stderr=c:\path\to\stderr.log -q .\mailpile\scripts\mailpile # Append additional mailpile args as desired

Here's an example of starting mailpile-gui:

cd C:\path\to\mailpile\install
.\python27\pythonw.exe .\bin\with-mailpile-env.py --stdout=c:\path\to\stdout.log --stderr=c:\path\to\stderr.log -q .\Mailpile\shared-data\mailpile-gui\mailpile-gui.py # Append additional mailpile args as desired

Note that as a regular user you may not have permission to write or modify files in the installation by default.

Decision point: python or pythonw

The above examples use pythonw.exe to give as close an experience as possible to a regular shortcut launch by a desktop user. Sometimes that makes debugging extremely problematic. As a gentler start, it is possible to use regular python.exe or use python.exe to bootstrap pythonw.exe. Here is an example of starting mailpile with python.exe:

cd C:\path\to\mailpile\install
.\python27\python.exe .\bin\with-mailpile-env.py --stdout=c:\path\to\stdout.log --stderr=c:\path\to\stderr.log -q .\mailpile\scripts\mailpile # Append additional mailpile args as desired

To bootstrap a different flavor of python, we simply explicitly specify the next interpreter:

cd C:\path\to\mailpile\install
.\python27\python.exe .\bin\with-mailpile-env.py --stdout=c:\path\to\stdout.log --stderr=c:\path\to\stderr.log -q pythonw.exe .\mailpile\scripts\mailpile # Append additional mailpile args as desired

One caveat of bootstrapping/multiprocessing: stdout/stderr may not propagate as would be expected on a Unix platform.