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