Developer notes

Building the docs

The documentation is a combined for the ParticleDetection and the RodTracker packages. Please make sure that ParticleDetection is installed. It is not necessary to install the DETECTRON extra. Please make sure that the RodTracker with the dependencies of the DOCS, BUILD, or DEV extra are installed.

  1. Clean the build directory:

    YOUR/REPO/PATH/docs$ make clean

  2. (Re-)Build the documentation:

    YOUR/REPO/PATH/docs$ make html

Refer to the Sphinx documentation for further options.

Warning

On Windows make sure that no other process, e.g. Dropbox, attempts to access files necessary for the build during this. Otherwise an OSError: [WinError 110] might occur and break the process.

On Linux/macOS this problem does not seem to occur.

Note

On macOS: Make sure that XCode is installed.

RodTracker

The different tasks described below require additional libraries compared to the default installation. Please make sure that you install the correct extras before attempting the tasks below (see Installation options).

PyQt UI files

Please make sure that the dependencies from the DEV extra are installed. The main GUI-layout is modeled in mainwindow_layout.ui and can be changed using QtDesigner. Generate the Python file after changing the UI-File using:

pyuic5 -o path/to/mainwindow_layout.py path/to/mainwindow_layout.ui

Do not change the Python file containing the GUI-Layout manually as all changes will be lost when generating it automatically again.

Debugging Threads

When debugging the RodTracker it is sometimes useful to be able to put breakpoints in functions run in threads other than the main-thread. In Visual Studio Code this does not work out of the box. There it is necessary to use the following piece of code:

import debugpy
...
def function_supposed_to_be_debugged():
   debugpy.debug_this_thread()
   ...

debugpy.debug_this_thread()must be added inside the function(s) running outside the main-thread that shall be debugged.

See the Visual Studio Code docs here for more information.

Running tests

Please make sure that the dependencies from TEST or DEV extra are installed. Run the tests with pytest from within the RodTracker directory:

YOUR/REPO/PATH/RodTracker$ pytest

Note

Some tests require a display (see pytest-qt)! Make sure the machine either has a screen connected or use pytest-xvfb.

Bundling the app

Please make sure that the dependencies of the BUILD, or DEV extra are installed. On Linux there are additional requirements to be able to run the bundling script. Refer to the PyInstaller documentation for that.

There is a script to generate an executable for Windows, Linux, or macOS. Prior to bundling it will also (re-)build the documentation because this is supposed to be contained in the bundled app.

On Windows:

YOUR/REPO/PATH/RodTracker/build-files> build_app.bat

On Linux & macOS:

YOUR/REPO/PATH/RodTracker/build-files$ build_app.sh

The build script will generate a .\RodTracker\build and a .\RodTracker\dist folder. The generated executables are located in the .\RodTracker\dist directory under either a windows or a unix subfolder.

Everything is bundled into one folder named RodTracker which can be copied or moved as a whole. Run the executable inside this folder to start the program. On macOS the generated folder is additionally converted into a RodTracker.app bundle that should be used to execute the RodTracker.

  • (Windows) dist\windows\RodTracker\RodTrackerApp.exe

  • (Linux) dist/unix/RodTracker/RodTracker

  • (macOS) dist/unix/RodTracker.app

Warning

On Windows make sure that no other process, e.g. Dropbox, attempts to access files necessary for the build during this step. Otherwise an OSError: [WinError 110] might occur and break the process.

On Linux/macOS this problem does not seem to occur.

Creating Installers

After it can be useful to create installers for easy distribution to the end user. The following scripts require the RodTracker to already be bundled as per the previous section.

On Windows:

An installer is created using Inno Setup. Use Inno Setup to compile the .\RodTracker\build-files\build_installer.iss script. This will create the installer file .\RodTracker\dist\windows\RodTracker-Setup.exe that can then be distributed.

On Linux:

dpkg-deb is used to create a *.deb package.

YOUR/REPO/PATH/RodTracker/build-files$ build_deb.sh

On macOS:

create-dmg is used to create a *.dmg installer.

  1. Install create-dmg:

    brew install create-dmg

  2. Create the installer:

    YOUR/REPO/PATH/RodTracker/build-files$ build_dmg.sh

ParticleDetection

Running tests

Please make sure that the dependencies from TEST extra are installed. Run the tests with pytest from within the ParticleDetection directory:

YOUR/REPO/PATH/ParticleDetection$ pytest