Development Basics
Submitting patches
The source code for SnapPy and its various parts are hosted on GitHub as Git repositories. To contribute a patch, create a free GitHub account, fork the appropriate repository, and then send us a pull request, as described in here.
macOS
Here is how to get a clean development setup under macOS.
Install the latest Python 3.13 from Python.org using the Mac Installer Disk Image. Set your path so that “python3” is:
/Library/Frameworks/Python.framework/Versions/3.13/bin/python3
Use pip to install the following packages:
python3 -m pip install --upgrade setuptools virtualenv wheel pip python3 -m pip install cython # Used for Python-C interfacing python3 -m pip install sphinx # For building the documentation python3 -m pip install ipython # Improved Python shell python3 -m pip install py2app # For making app bundles python3 -m pip install pyx FXrays low_index
Get the source code from the repository, using Git. For example you can install Git via its package installer. Now do:
git clone https://github.com/3-manifolds/plink.git git clone https://github.com/3-manifolds/spherogram.git git clone https://github.com/3-manifolds/snappy.git
Test the stand-alone link editor:
cd plink python3 setup.py pip_install python3 -m plink.app # Link editor appears!
This last command runs the script
plink/app.py
; the real code for the link editor is inplink/__init__.py
.Build and install Spherogram:
cd ../spherogram python3 setup.py pip_install python3 setup.py test
Now build SnapPy itself. One builds it twice to generate the documentation, much of which is extracted from the installed module:
cd ../snappy python3 setup.py pip_install python3 setup.py test # Run the tests; pretty picture should appear. python3 -m snappy.app #SnapPy starts!
To build the clickable app, just do the following:
cd mac_osx_app python3 release.py --manual
though for general development purposes
python3 -m snappy.app
is usually the way to go.
Some major parts of the SnapPy codebase are:
SnapPy.pyx
,SnapPycore.pxi
,SnapPy.pxi
: The Cython interface to the SnapPea kernelopengl/CyOpenGL*.pyx
: The Cython interface to OpenGL*snappy/app.py
: The core GUI codesnappy/polyviewer.py
: The GUI code for Dirichlet domainssnappy/horoviewer.py
: The GUI code for horoball picturessnappy/database.py
: Interacts with the sqlite3 manifold database
Windows
These instructions have been tested on Windows 10, and describe setting up a development environment using the (free) MSVC compiler. To build the CyPari subcomponent, which few will want or need to do, one must install additional tools.
Install Python 3.13.1, specifically the default 64-bit version (the file name will end in
amd64.exe
). These instructions assume it has been installed in the directoryC:\Python313
which is not the default.With Python 3.13.1, you need the MSVC command line tools. You can get them by using Microsoft’s free Build Tools for Visual Studio 2019 installer and selecting the “C++ command line tools” and installing the following subpackages: “MSVC v142 - VS 2019 C++ build tools”, “Testing tools core features”, “C++/CLI support for v142”, and “Windows 10 SDK (most recent version)”.
If you would like to make your own installer you will also need Inno Setup, specifically the unicode version; tested with version 5.5.9.
Install MSYS2 as appropriate for your version Windows. Follow the instructions on the webpage to update everything to the very latest MSYS2 (
pacman -Sy pacman; pacman -Syu; pacman -Su
etc.). You should also install the ucrt toolchain:pacman -S mingw-w64-ucrt-x86_64-toolchain
Make a shortcut to
c:\msys64\msys2.exe
as you will be using it all the time; alternatively, pinmys2.exe
to your taskbar.Install some additional packages:
pacman -S git make nano openssh perl tar unzip wget winpty patch
Install your favorite text editor, for example you can install Emacs via:
pacman -S mingw-w64-x86_64-emacs
Make it so that MinGW, Python, and Inno Setup are all in your PATH, as well as work around some stupid bug, by making the end of your “~/.bash_profile” file to read:
PATH=/c/Python313:/c/Python313/Scripts:$PATH PATH=$PATH:'/c/Program Files (x86)/Inno Setup 5' export PATH alias emacs="/mingw64/bin/emacs" winpty bash; exit
For example, do:
nano ~/.bash_profile
Make sure you have the right version of Python in your path by typing:
python --version
You should see something like
Python 3.13.1
.Use pip to install some basic tools:
python -m pip install --upgrade pip setuptools wheel # Upgrades pip to the current version. python -m pip install pyreadline sphinx cython cypari pyx FXrays low_index
Fetch the latest development versions of the source straight from the t3m repository:
git clone https://github.com/3-manifolds/plink.git git clone https://github.com/3-manifolds/spherogram.git git clone https://github.com/3-manifolds/snappy.git
Build the components, from easiest to hardest, and then test:
cd plink python setup.py pip_install cd ../Spherogram python setup.py pip_install cd ../SnapPy python setup.py pip_install cd .. python -m SnapPy.test
To run the app, you can just do:
python -m snappy.app
To build the binary installer, you need PyInstaller:
python -m pip install pyinstaller
To build the binary installer do:
cd windows_exe python make.py
You will need to close the SnapPy window that pops up here to complete the build process.
Useful tips for those coming from Unix. In MSYS2, your home directory is really something like:
c:\msys2\home\Nathan Dunfield
whereas your Windows 10 home directory is:
c:\Users\Nathan Dunfield
It is handy to have symbolic links from your MSYS2 home directory to the Downloads and Desktop folders on the Windows side. See this discussion, but basically you start a “Command Prompt” as Administrator and do:
cd "C:\msys64\home\Nathan Dunfield" mklink /D Desktop "C:\Users\Nathan Dunfield\Desktop" mklink /D Downloads "C:\Users\Nathan Dunfield\Downloads"
Linux
Things you’ll need:
Python 3 with Tkinter: You’ll need to have Python (version 3.9 or newer) and Tk (at least version 8.5) with Tkinter to connect them, including the header files. For instance, on Debian or Ubuntu, install the packages “python3-tk”, “python3-pip”, and “python3-dev”. On Fedora, you’ll want e.g. “python3-tkinter”, “python3-pip”, and “python3-devel”, and “python3-wheel”.
Test that Python is in order by installing PLink from source:
python3 -m pip install --user plink python3 -m plink.app # Should start the link editor!
Support for OpenGL (3D graphics): This is built in on OS X and the most installations of Fedora and Ubuntu. But you’ll need the MESA header files “gl.h” and “glu.h” to compile SnapPy. On Debian and Ubuntu, install “libglu1-mesa-dev”; On Fedora install “mesa-libGLU-devel”.
Cython, which you can install via:
python3 -m pip install --user cython
The gcc C++ compiler, g++.
Fetch the latest development versions of the source straight from the repository:
git clone https://github.com/3-manifolds/PLink.git git clone https://github.com/3-manifolds/Spherogram.git git clone https://github.com/3-manifolds/Snappy.git
Build the components, from easiest to hardest, and then test:
cd PLink python setup.py pip_install cd ../Spherogram python setup.py pip_install cd ../SnapPy python setup.py pip_install cd .. python -m SnapPy.test