Table of Contents
First, read CONTRIBUTING
Still having trouble? Well we should probably identify the problem and add it to the docs. However, this wiki page has some useful tricks and tips. Think of it as a staging area for the official docs...
Virtualenvs
Virtualenvs are a requirement for developing rasterio.
$ # example
$ mkvirtualenv -p python3.5 /tmp/env
$ source /tmp/env/bin/activate
Or even better, install virtualenv_wrapper (one of the few things I install globally with sudo pip install) according to: http://virtualenvwrapper.readthedocs.io/en/latest/install.html
This allows for workflows like
$ mkvirtualenv tmp
$ workon tmp
$ rmvirtualenv tmp
I'd recommend adding
PIP_REQUIRE_VIRTUALENV=true
to your bash profile so that pip only installs in a venv.
GDAL version
GDAL from homebrew may be fine if you want 1.11.3
brew install gdal
GDAL 2.1 from source is fine if you want to install your own.
KyngChaos builds work well for some people.
I've also got an experimental gdal 2.1 formula for homebrew which can be installed alongside the official 1.11 release
brew install perrygeo/test/libgdal-21
export PATH=/usr/local/opt/libgdal-21/bin:$PATH
With any of these methods, it's important to check that your PATH environment variable is set to pick up on the correct version of GDAL before you install Rasterio.
which gdalinfo
gdalinfo --version
If you're not seeing the correct version, set PATH accordingly
pip
Always upgrade pip
pip install -U pip # the first line you should type in any virtualenv
cleaning
When switching between virtualenvs and gdal versions, you may need to clean our some build artifacts from Rasterio to get a clean build. Some of this is overkill but may help get you out of a pickle if your build env gets screwy.
pip uninstall -y rasterio
python setup.py clean --all
find . -name '__pycache__' -delete -print -o -name '*.pyc' -delete -print
pip install -e .
The pyc deletion is so handy that you might want to make that a bash alias
alias pyc="find . -name '__pycache__' -delete -print -o -name '*.pyc' -delete -print"
Checking lib links
otool and file are your friend
The following tells us a) which libgdal we're linked to and b) which libgeos lib is linked to our libgdal
$ otool -L rasterio/_io.so
rasterio/_io.so:
/usr/local/opt/libgdal-21/lib/libgdal.20.dylib (compatibility version 22.0.0, current version 22.0.0)
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1213.0.0)
$ otool -L /usr/local/opt/libgdal-21/lib/libgdal.20.dylib | grep geos
/usr/local/opt/geos/lib/libgeos_c.1.dylib (compatibility version 11.0.0, current version 11.0.0)
and there are occasionally architecture-related issues with 32-bit binaries so file can help diagnose the build architecture
$ file rasterio/_io.so
rasterio/_io.so: Mach-O universal binary with 2 architectures
rasterio/_io.so (for architecture i386): Mach-O bundle i386
rasterio/_io.so (for architecture x86_64): Mach-O 64-bit bundle x86_64
$ file /usr/local/opt/libgdal-21/lib/libgdal.20.dylib
/usr/local/opt/libgdal-21/lib/libgdal.20.dylib: Mach-O 64-bit dynamically linked shared library x86_64
$ file /usr/local/opt/geos/lib/libgeos_c.1.dylib
/usr/local/opt/geos/lib/libgeos_c.1.dylib: Mach-O 64-bit dynamically linked shared library x86_64