4. Building from source

This guide will describe how to build the app for distribution with PyInstaller and Inno Setup (if you’re building on Windows). We assume that you have successfully followed the steps to Setting up the development environment and Running the app from the source works already.

4.1. Additional build dependencies

The L’ART Research Client app is built with PyInstaller, and Inno Setup is used on Windows to package it up as an executable installer.

4.1.1. PyInstaller

PyInstaller will already have been installed when you have installed the development dependencies with pipenv install --dev while Setting up the development environment. If you get an error saying that PyInstaller could not be found, just run that command again.

4.1.2. Inno Setup

Inno Setup is only needed if you’re building on Windows — so if you’re on Linux or MacOS you can just ignore anything to do with Inno Setup.

On Windows, Inno Setup needs to be installed on your system or the build process will fail. Follow these simple steps to install it:

Download the latest version of Inno Setup from https://jrsoftware.org/isdl.php.
Run the Inno Setup installer on your system to install it.
Check whether the command iscc is on your system’s Path by opening a terminal window (Windows+R, type cmd, hit Enter) and then entering the command iscc followed by Enter.
If you see soem text starting with something like “Inno Setup 6 Command-Line Compiler” followed by instructions, you’re good to know and can skip to the next section. In the (very likely) event that you get an error instead, continue with the next step here.
Locate ISCC.exe and note the path to the directory where it is located. This is probably C:\Program Files\Inno Setup 6 or C:\Program Files (x86)\Inno Setup 6.
Either type “environment variables” in the Start search box and open the “Edit the system environment variables” shortcut that shows up, or go to Settings -> System -> Advanced system settings.
On the bottom of the dialog box, click on Environment Variables….
Highlight the variable called Path in the top half of the dialogue window, then click on Edit.
Click on New and add the path to the directory where Inno Setup (ISCC.exe from before) is installed, e.g. C:\Program Files (x86)\Inno Setup 6.
Click OK repeatedly until all the dialogue windows are closed.
Start a new terminal window (it will not work in any terminal windows that were opened before you edited the Path environment variable) and try running iscc again — it should work now, meaning you’re ready to build the app on Windows (if it still doesn’t work, you probably entered the wrong path two steps earlier).

4.2. Building the app and the installer

Building the app is super simple. Just go to the folder containing the manage.py file, make sure you’re running in the pipenv shell (if you’re not sure, just run pipenv shell again), and then run the command py ./manage.py build (on Windows) or python3.10 manage.py build (on Linux and MacOS).

The folder ./build will contain all the build artificats and direct outputs from PyInstaller.

The folder ./dist will contain the distributables for the app, in a subfolder named after the system on which they were built. For example on Linux, there will be a tarball (*.tar.gz) in ./dist/linux, while on Windows there will be both a ZIP archive and an executable (.exe) installer in ./dist/win64, which can be used to install the app.

4.3. Building the documentation

The documentation is built automatically on Read the Docs whenever a pull request, push or merge succeeds on the docs branch of the repository. Even so, if you’re updating the documentation (even in the inline documentation in the Python and JavaScript files) it might be desirable to build it locally to make sure any changes are reflected as they should be and nothing breaks.

4.3.1. Additional documentation dependencies

To build the documentation, you need to additionally install jsdoc, as shown as an optional step in Installing the pre-requirements.

jsdoc is used to extract documentation from within the JavaScript files that provide the app’s APIs in the frontend.

You can check whether jsdoc works by opening a terminal and typing jsdoc. If it is installed correctly and available on your Path, it should print something like “There are no input files to process.” — otherwise you will need to install it and make sure it is available on the Path before you can build the documentation.

4.3.2. Building the documentation

Building the documentation is just as simple as building the app. Like with building the app, make sure you’re in the directory containing the file manage.py and that you’re in the pipenv shell (any doubt, just run pipenv shell). Then just run the command py ./manage.py docs (on Windows) or python3.10 manage.py docs (on Linux and MacOS).

The folder ./dist/docs/html will contain the HTML version of the documentation (we do not currently build the latex/PDF version offline, as this has too many dependencies and quirks to work reliably from one person to the next).

4.4. Cleaning up after yourself

Just like with your bedroom, it’s important to keep your development environment tidy. So once you’ve completed your builds and inspected that everything is as it should be, you probably want to clean up all the artifacts, local documentation and distributables generated by the build process…

Just run py ./manage.py clean (on Windows) or python3.10 manage.py clean (on Linux or MacOS), and the manage.py utility will make everything nice and tidy again 🧹.

4.5. Known issues with building

Building fails with Python version 3.10.0 due a bug in Python that affects PyInstaller (issue). If your Python version is 3.10.0 then update to 3.10.1 or later (but not 3.11.x, for which nothing has been tested, …yet).