Installation#
Built distributions#
The easiest way to install Spherely is via its binary packages available for Linux, MacOS, and Windows platforms on conda-forge and PyPI.
Installation of Python binary wheels (PyPI)#
Install the last released binary wheel, e.g., using pip:
$ pip install spherely
Installation of Conda packages (conda-forge)#
Install the last released conda-forge package using conda:
$ conda install spherely --channel conda-forge
Installation from source#
Compiling and installing Spherely from source may be useful for development purpose and/or for building it against a specific version of S2Geography and/or S2Geometry.
Requirements#
Python
Numpy
s2geography v0.2.0 or higher
s2geometry v0.11.1 or higher
Additional build dependencies:
C++ compiler supporting C++17 standard
CMake
Cloning the source repository#
Spherely’s source code can be downloaded by cloning its source repository:
$ git clone https://github.com/benbovy/spherely
$ cd spherely
Setting up a development environment using pixi#
Spherely provides everything needed to manage its dependencies and run common tasks via pixi.
If you have pixi
installed, you can install a complete development environment
for your platform simply by executing the following command from Spherely’s
project root directory:
$ pixi install --environment all
Running the command below from Spherely’s root directory will install all required tools and dependencies (if not installed yet) in a local environment, build and install Spherely (if needed) and run the tests:
$ pixi run tests
All available tasks are detailed in the pyproject.toml
file or listed via
the following command:
$ pixi task list
Setting up a development environment using conda#
If you don’t have pixi
installed, you can follow the steps below to manually
setup a conda environment for developing Spherely.
After cloning Spherely’s source repository, create a conda environment
with the required (and development) dependencies using the
ci/environment-dev.yml
file:
$ conda env create -f ci/environment-dev.yml
$ conda activate spherely-dev
Build and install Spherely:
$ python -m pip install . -v --no-build-isolation
Note that you can specify a build directory in order to avoid rebuilding the whole library from scratch each time after editing the code:
$ python -m pip install . -v --no-build-isolation --config-settings build-dir=build/skbuild
Run the tests:
$ pytest . -v
Spherely also uses pre-commit for code auto-formatting and linting at every commit. After installing it, you can enable pre-commit hooks with the following command:
$ pre-commit install
(Note: you can skip the pre-commit checks with git commit --no-verify
)
Using the latest S2Geography version#
If you want to compile Spherely against the latest version of S2Geography, use:
$ git clone https://github.com/paleolimbot/s2geography
$ cmake \
$ -S s2geography \
$ -B s2geography/build \
$ -DCMAKE_CXX_STANDARD=17 \
$ -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX
$ cmake --build s2geography/build
$ cmake --install s2geography/build