Support building from source with user-specified GraphBLAS (#85)

* Support building from source with user-specified GraphBLAS

Look for GraphBLAS first in GraphBLAS_ROOT env var, if empty then fallback to current paths

* Add note about LD_LIBRARY_PATH

README.md

@@ -12,3 +12,33 @@ This is a base package that exposes only the low level CFFI API
 bindings and symbols.  This package is shared by the syntax bindings
 [pygraphblas](https://github.com/Graphegon/pygraphblas) and
 [python-graphblas](https://github.com/python-graphblas/python-graphblas).
+
+
+## Installation from pre-built wheels
+Pre-built wheels for common platforms are available from PyPI and conda. These bundle a compiled copy of SuiteSparse:GraphBLAS.
+
+```bash
+pip install suitesparse-graphblas
+```
+
+or
+
+```bash
+conda install -c conda-forge python-suitesparse-graphblas
+```
+
+## Installation from source
+If you wish to link against your own copy of SuiteSparse:GraphBLAS you may build from source.
+
+Specify the location of your SuiteSparse:GraphBLAS installation in the `GraphBLAS_ROOT` environment variable then use the standard pip build from source mechanism. This location must contain `include/GraphBLAS.h` and `lib/`.
+
+```bash
+export GraphBLAS_ROOT="/path/to/graphblas"
+pip install suitesparse-graphblas-*.tar.gz
+```
+You may also have to appropriately set `LD_LIBRARY_PATH` to find `libgraphblas` at runtime.
+
+For example, to use Homebrew's SuiteSparse:GraphBLAS on macOS, with the sdist from PyPI, and with all dependencies using wheels:
+```bash
+GraphBLAS_ROOT="$(brew --prefix suitesparse)" pip install --no-binary suitesparse-graphblas suitesparse-graphblas
+```

build_graphblas_cffi.py

@@ -10,17 +10,23 @@
 
 ffibuilder = FFI()
 
-include_dirs = [os.path.join(sys.prefix, "include")]
-library_dirs = [os.path.join(sys.prefix, "lib")]
+# GraphBLAS_ROOT env var can point to the root directory of GraphBLAS to link against.
+# Expected subdirectories: include/ (contains GraphBLAS.h), lib/, and bin/ (on Windows only)
+# Otherwise fallback to default system folders.
+graphblas_root = os.environ.get("GraphBLAS_ROOT", None)
+if not graphblas_root:
+    # Windows wheels.yml configures suitesparse.sh to install GraphBLAS to "C:\\GraphBLAS".
+    graphblas_root = "C:\\GraphBLAS" if is_win else sys.prefix
+
+include_dirs = [os.path.join(graphblas_root, "include")]
+library_dirs = [os.path.join(graphblas_root, "lib")]
 if is_win:
     include_dirs.append(os.path.join(sys.prefix, "Library", "include"))
     library_dirs.append(os.path.join(sys.prefix, "Library", "lib"))
 
-    # wheels.yml configures suitesparse.sh to install GraphBLAS here.
-    prefix = "C:\\GraphBLAS"
-    include_dirs.append(os.path.join(prefix, "include"))
-    library_dirs.append(os.path.join(prefix, "lib"))
-    library_dirs.append(os.path.join(prefix, "bin"))
+    include_dirs.append(os.path.join(graphblas_root, "include"))
+    library_dirs.append(os.path.join(graphblas_root, "lib"))
+    library_dirs.append(os.path.join(graphblas_root, "bin"))
 
 ffibuilder.set_source(
     "suitesparse_graphblas._graphblas",