Development Guide

There is a Makefile for development in local environment. See available commands via invoking make help.

You will need to install pyenv and tox_ globally in your local environment:

brew install pyenv tox
pyenv install 2.7.14  # and also

Requirement

The requirement changes of testing and document building environment need to be included in requirements-test.in and docs/requirements.in. You will need to invoke make deps to compile them into requirements*.txt.

Test

For running test in all supported Python versions, you will need pyenv:

# Enter the multi-version Python environment (2.7, 3.6, pypy2, pypy3)
pyenv shell 2.7.14:3.6.5:pypy2.7-5.10.0:pypy3.5-5.10.1

make test

For debugging, you may want to test in a specific Python version, such as 2.7:

tox -e py27                               # Default pytest options
tox -e py27 -- -vxs --log-cli-level=DEBUG # Custom pytest options

Package

For packaging a new distribution, make dist will be helpful. It assumes you are using macOS and the Docker for Mac has been installed and started also. The binary wheel packages for macOS (with your current ABI) and Linux (with manylinux API) will be present. Using pyenv and bumpversion is a good idea:

# Enter the multi-version Python environment (2.7, 3.6, pypy2, pypy3)
pyenv shell 2.7.14:3.6.5:pypy2.7-5.10.0:pypy3.5-5.10.1

bumpversion minor           # Commit and tag a new major/minor/patch release
make dist                   # Build release packages
make dist options="-b dev0" # Build pre-release packages

Clean up

You could clean up the workspace with make clean. It removes files which was ignored in the version control except the .tox.

Debugg C Extension

Debugging the C extension of Python needs different toolchains and skills. The lldb or gdb will be useful in that:

tox -e py27                  # Run test until it hangs
vim tests/_orphanage_poll.c  # Inspect the CFFI generated code
lldb --attach-pid=100001     # Attach to the target process
lldb> breakpoint set -f _orphanage_poll.c -l 434
lldb> continue
lldb> bt all

For unexpected crashing, the coredump will include useful information:

ulimit -c unlimited         # Turn on coredump in current shell
tox -e py27                 # Run test until it crashes
lldb --core /cores/cores.10 # Open the coredump named with its pid
lldb> bt all                # Print the backtrace