-
Notifications
You must be signed in to change notification settings - Fork 11
/
HACKING.txt
114 lines (81 loc) · 4.25 KB
/
HACKING.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
#############
## Setting up a development environment
#############
Athena requires a Python 3.7+ environment. Using virtualenv to manage
dependencies is highly recommended. After checking out the Athena
repository, run:
( On OSX )
> virtualenv env
> source env/activate
> pip install -r requirements.txt
( On Windows )
> virtualenv env
> env\Scripts\activate
> pip install -r requirements.txt
Athena can then be invoked by calling `python src/main.py` from the athena directory.
#############
## Preparing Athena releases
#############
Athena uses PyInstaller to prepare downloadable application bundles for Mac OS X
and Windows. Deployment convenience scripts are available for both platforms:
( On OSX )
> ./deploy_mac.sh
( On Windows )
> .\deploy_win.bat
The result of running these scripts is a file dist/athena_{platform}_{version}.zip,
which can be uploaded to Github or otherwise shared with collaborators. This zip
will include Athena's README and LICENSE files.
The deploy_mac.sh script calls sign_mac.sh with the name of a signing key ("LCBB" by default).
To create your own self-signed key for this purpose, follow the instructions at
https://github.com/pyinstaller/pyinstaller/wiki/Recipe-OSX-Code-Signing.
Without at least a self-signed binary, Athena.app has startup problems if it is
downloaded from the web, due to Apple's Gatekeeper features.
#############
## Platform Support
#############
As of this writing, the LCBB sequence tools are only available for Windows and Mac OSX.
There's no reason Athena wouldn't also run fine on Linux, but it wouldn't be
able to call sequence tools unless they were first compiled on that target.
On OSX, PyInstaller creates binaries that are forward compatible with new versions
of the OS, but not backward compatible. So it is necessary to build Athena on the
oldest version of OSX that we want to support for our users. Athena's development
through version 0.4.2 was done on OSX 10.12 Sierra.
#############
## Repository Layout
#############
The ui/ directory contains Qt ui files, which can be edited with Qt Creator or Qt Designer.
Chief among these is AthenaMainWindow.ui. Almost any GUI change will begin with editing
this file. I have adhered to a convention of not setting up signals and slots in the
ui file; all signal connections are set up manually in src/mainwindow.py
All other input code is under src/, as follows:
* src/athena -- Athena's GUI and graphics source code; see internal documentation within .py files
* src/earcut -- The earcut library, taken from https://github.com/joshuaskelly/earcut-python
(If this had been conventionally available via pip it would be a pip dependency)
* src/pdbgen -- The PDBGen library
* src/qml -- QML files for Athena's graphical QMaterial classes
* src/shaders -- GLSL shader code
(There's a lot of material here, because Athena draws spheres, cylinders,
and cones using ray-traced imposter shaders.)
#############
## Athena and Qt
#############
Athena uses PySide2 as an interface to the Qt5 API.
Within that API, it uses Qt3D for 3D graphics. Qt3D's documentation
is not great, so Athena has some idiosyncratic interactions with it:
* QMaterials are defined in QML, but all other Qt3D structures (including scene
graphs and frame graphs) are set up manually in Python code.
* Even those QMaterial subclassess require support from Python to define paths to their
shader files, since QML can't reference files outside of a qrc file.
* I wanted to avoid using Qt3DWindow and implement a customized 3D widget, especially
for the purposes of controlling the format of the OpenGL depth buffer (see Athena
issue #6). This was impossible due to https://bugreports.qt.io/browse/PYSIDE-753
but may become possible in the future if that bug is fixed or Athena migrates from
PySide2 to PyQt5.
#############
## A note about dependencies
#############
Any Python dependencies introduced to Athena must be installable with pip on both Windows
and Mac OS X without requiring any native library compilation. This avoids dll
hell on Windows, where we would have to ensure the compiled libraries are
compatible with the Qt libraries in the PySide2 wheels. It also ensures that
users can build Athena without needing to set up native compilers.