How to build the self contained Holdit! application

Hold It! can be used as a command-line application or a full self-contained application. For the latter, we use PyInstaller to create the application on Windows and macOS.

Building on a Mac

The Hold It! source code directory contains a simple Makefile to run the process. To create the application, after making sure that the necessary dependencies are available on your system (including PyInstaller version 3.4 or later, as well as inliner and pandoc), simply run make at the top level of the repository:

make

During the run of PyInstaller, you may get an error involving Jinja2 that looks like this:

Syntax error in  /Users/mhucka/system/lib/python3.5/site-packages/jinja2/asyncsupport.py
("'yield' inside async function", ('/Users/mhucka/system/lib/python3.5/site-packages/jinja2/asyncsupport.py', 35, 12, '            yield event\n'))

This appears to be due to some version incompatibility; I don't know which Python and Jinja versions it involves, but it can be ignored. As far as I can tell, the resulting application runs fine without any errors due to this.

The result of the make run will be a Mac application bundle (HoldIt.app) left in the dist subdirectory. This can be executed normally (e.g., by double-clicking it in the Finder, or by doing open dist/Holdit.app in a command line terminal).

Building on Windows

Before building the application on Windows, a build must be run on a Mac or Linux machine because only the Mac/Linux build process is set up to generate the files ABOUT.html and holdit/data/help.html. (This is not due to inherent limitations of Windows; I simply didn't spend the time figuring out how to get the necessary tools running on Windows in order to make the generation of those files something that the Windows make.bat could do.)

Next, to build the application on Windows, you can use the simple script called make.bat and located at the level of the Hold It! source directory. From a command shell, you can simply change directories to the Hold It! source directory and then run the script from the shell:

make

The result of the make run will be a Windows application (Hold It.exe) left in the dist subdirectory. This can be executed normally (e.g., by double-clicking it in the Windows file explorer).