Development Basics

Submitting patches

The source code for SnapPy and its various parts are hosted on bitbucket as Mercurial repositories. To contribute a patch, create a free bitbucket account, fork the appropriate repository, and then send us a pull request, as described in this tutorial.

OS X

Here is how to get a clean development setup under OS X.

  • Install Active Tcl/Tk 8.6 from ActiveState.

  • Install the latest Python 2.7 from Python.org using the Mac Installer Disk Image. There are currently two versions, one for 10.3 and up (ppc/i386) and one for 10.6 and up (i386/x86_64); you want the second one. Set your path so that “python” is:

    /Library/Frameworks/Python.framework/Versions/2.7/bin/python
    
  • Python 2.7.9 and newer include pip so use it upgrade and install the following packages:

    python -m pip install --upgrade setuptools
    python -m pip install virtualenv
    python -m pip install Cython      # Used for Python-C interfacing
    python -m pip install Sphinx      # For building the documentation
    python -m pip install ipython     # Improved Python shell
    python -m pip install py2app      # For making app bundles
    python -m pip install mercurial   # Source code control software
    
  • Get the source code from the repository. The program “hg” was installed in the last step and lives in the same directory as Python 2.7:

    hg clone https://bitbucket.org/t3m/plink
    hg clone https://bitbucket.org/t3m/Spherogram
    hg clone https://bitbucket.org/t3m/CyPari
    hg clone https://bitbucket.org/t3m/SnapPy
    
  • Test the stand-alone link editor:

    cd plink
    python setup.py install
    python -m plink.app   # Link editor appears!
    

    This last command runs the script “plink/app.py”; the real code for the link editor is in “plink/__init__.py”.

    To make sure it’s using the right Tk, select “File->About Python...” and make sure the version is 8.6, not 8.4. or 8.5. If it’s an older version, go into “SnapPy/release_tools/tkinter-versions” and run the script ”./install_tkinter 8.6”. (If you don’t have both Python 3.2 and 2.7 installed on your system, it will complain. But you can ignore this.)

  • Build and install Spherogram:

    cd ../Spherogram
    python setup.py install
    
  • Build and install CyPari:

    cd ../CyPari
    python setup.py install
    
  • Now build SnapPy itself. One builds it twice to generate the documentation, much of which is extracted from the installed module:

    cd ../SnapPy
    python setup.py install
    python setup.py build_docs install
    

    If ”.” is in your path, you’ll need to change directory before starting SnapPy; otherwise it will attempt to load ”./snappy” which lacks the binary module:

    cd SnapPyApp
    python -m snappy.app   #SnapPy starts!
    

    To build the clickable app, just do the following in the SnapPyApp directory:

    python setup.py py2app
    

Some major parts of the SnapPy codebase are:

  • “SnapPy.pyx”, “SnapPycore.pxi”, “SnapPy.pxi”: The Cython interface to the SnapPea kernel
  • “opengl/CyOpenGL*.pyx”: The Cython interface to OpenGL*
  • “snappy/app.py”: The core GUI code
  • “snappy/polyviewer.py”: The GUI code for Dirichlet domains
  • “snappy/horoviewer.py”: The GUI code for horoball pictures
  • “snappy/database.py”: Interacts with the sqlite3 manifold database

In addition, Jeff’s old prototype for a Tk-based UI can be found in “misc/JeffsOldUI/SnapPeaGUI.py”; just run Python on this file to try it out, after installing PythonMegaWidgets.

Windows

These instructions have been tested on Windows 7 and 8 and quite possibly work on XP and Vista as well.

  • Install Python 2.7, specifically the 32 bit version (Windows x86 not Windows x86-64) and also Inno Setup. The below instructions were checked with Python 2.7.9 and Inno Setup 5.5.4.

  • Install MinGW (including g++, MSYS-base, and the MinGW Development Toolkit), and open an MSYS terminal shell, which is where all the rest of the work will take place. Alternatively, if you’re not going to build CyPari, you can use this Python-specific free version of Microsoft Visual C++ compiler.

  • Create a file “/c/Python27/Lib/distutils/distutils.cfg” consisting of:

    [build]
    compiler=mingw32
    

    This tells Python to use the MinGW compilers. You should skip this step if you’re using the MSVC compiler instead.

  • Make it so that MinGW, Python, and Inno Setup are all in your PATH by adding the below lines to the file “~/.profile”:

    PATH=/c/Python27:/c/Python27/Scripts:/c/mingw/bin:$PATH
    PATH=$PATH:'/c/Program Files/Inno Setup 5'
    export PATH
    
  • Python 2.7.9 and newer include pip so use it upgrade and install the following packages:

    pip install pyreadline
    pip install sphinx
    pip install cython
    pip install ipython
    pip install --allow-all-external pyx==0.12.1
    pip install mercurial   # Installs "hg", used in next step
    
  • Fetch the latest development versions of the source straight from the repository:

    hg clone https://bitbucket.org/t3m/plink
    hg clone https://bitbucket.org/t3m/Spherogram
    hg clone https://bitbucket.org/t3m/CyPari
    hg clone https://bitbucket.org/t3m/SnapPy
    
  • Build and install each piece of the library in turn, and then start SnapPy:

    cd CyPari
    python setup.py install
    cd ../Spherogram
    python setup.py install
    cd ../plink
    python setup.py install
    cd ../SnapPy
    python setup.py install
    cd ../
    python -m snappy.app
    
  • If that works, install py2exe via the binary installer. Then:

    cd SnapPy/SnapPyExe
    python make.py
    

    builds the binary installer “InstallSnapPy.exe” for SnapPy.

Table Of Contents

Previous topic

To Do List

This Page