Skip to content

Commit 83acb87

Browse files
committed
Add note about cross-platform support to README
1 parent 98c42d6 commit 83acb87

1 file changed

Lines changed: 29 additions & 2 deletions

File tree

README.md

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,8 +108,35 @@ graph.remove_nodes(nodes[:1000])
108108

109109
A `SpatialGraph` consists of three data structures:
110110

111-
* The `Graph` itself, holding nodes, edges, and their attributes ([graphlite](https://github.com/haasdo95/graphlite)).
112-
* Two R-trees for spatial node and edge queries (based on [rtree.c](https://github.com/tidwall/rtree.c)).
111+
* The `Graph` itself, holding nodes, edges, and their attributes
112+
([graphlite](https://github.com/haasdo95/graphlite)).
113+
* Two R-trees for spatial node and edge queries (based on
114+
[rtree.c](https://github.com/tidwall/rtree.c)). We modified the original code
115+
to also include a fast kNN search.
116+
117+
## Cross-Platform Support
118+
119+
`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
120+
compiler. If you already have one, great! You can use the PyPI package.
121+
122+
If you (or your users) don't have a compiler installed, you either need to
123+
124+
1. Install a compiler. This might be weird for non-technical users.
125+
2. Install `spatial_graph` from `conda-forge`, where we include a compiler
126+
(`clang`) in its dependencies.
127+
128+
### Why is this so complicated?
129+
130+
There is no cross-platform C/C++ compiler that we can install using `pip`.
131+
[`numba`](https://github.com/numba/numba) is maybe the closest to having solved
132+
that problem: `numba` does compile during runtime even if you don't have a
133+
compiler locally installed. This works because `numba` is generating LLVM IR,
134+
an intermediate representation language that LLVM can compile into machine
135+
code. `numba` depends on [`llvmlite`](https://github.com/numba/llvmlite), which
136+
provides a subset of the LLVM API, statically linked into the binaries in that
137+
package. This is just enough to compile the `numba` generated LLVM IR into
138+
machine code. We can't use this strategy, because we compile general C/C++
139+
code. Converting that into LLVM IR is exactly what we need a compiler for.
113140

114141
## For Developers
115142

0 commit comments

Comments
 (0)