This document lists the platform requirements and installation instructions for working with the S2 Geometry Library in both C++ and Python. (The S2 Python interfaces uses SWIG to interact with the C++ code.)

Requirements

Running the S2 code requires the following:

  • A MacOSX or Linux platform. (Windows is not supported at this time.)
  • POSIX support (for getrusage()).
  • A compatible C++ compiler supporting at least C++11, such as g++ >= 4.7.
  • Installation of the following libraries:
  • Git for interacting with the S2 source code repository, which is contained on GitHub. To install Git, consult the Set Up Git guide on GitHub.

Installation instructions for the above components are noted below.

Note: this installation guide uses CMake as the official build system for S2, which is supported on most major platforms and compilers. The S2 source code assumes you are using CMake and contains CMakeList.txt files for that purpose.

Although you are free to use your own build system, most of the documentation within this guide will assume you are using CMake.

Installation Instructions

Note: thorough testing has only been done on Ubuntu 14.04.3 and MacOSX 10.12.

Setting Up Your Development Environment (Linux)

Note: we recommend you use a Linux package manager such as apt-get. Alternatively, you may build the dependent libraries from source.

1. Install the additional libraries S2 code requires:

$ sudo apt-get install libgflags-dev libgoogle-glog-dev libgtest-dev libssl-dev
Reading package lists... Done
Building dependency tree
Reading state information... Done
...
After this operation, 3,090 kB of additional disk space will be used.
Do you want to continue? [Y/n] Y
...
Setting up libgtest-dev (1.6.0-1ubuntu6) ...
Processing triggers for libc-bin (2.19-0ubuntu6.13) ...
$

2. (Optional) Install SWIG

If you will be developing in Python, you should also install the SWIG library). Most Python code will invoke the C++ code through this library.

$ sudo apt-get install swig
$

3. Install CMake

$ sudo apt-get install cmake
Reading package lists... Done
Building dependency tree
Reading state information... Done
...
After this operation, 16.6 MB of additional disk space will be used.
Do you want to continue? [Y/n] Y
...
Setting up cmake (2.8.12.2-0ubuntu3) ...
$

Setting Up Your Development Environment (MacOSX)

Note: we recommend you use a MacOSX package manager such as MacPorts or Homebrew. Alternatively, you may build the dependent libraries from source.

1. Install the additional libraries S2 code requires:

# MacPorts
$ sudo port install gflags google-glog openssl

# Homebrew
$ brew install gflags glog openssl

2. Download Googletest release 1.8.0 and unpack it in a directory of your choosing. (Take note of this directory as you will need to point CMake to it.)

3. (Optional) Install SWIG

If you will be developing in Python, you should also install the SWIG library). Most Python code will invoke the C++ code through this library.

# MacPorts
$ sudo port install swig

# Homebrew
$ brew install swig

4. Install CMake

# Note: XCode requires command-line tools, which can be installed with:
$ xcode-select --install

# MacPorts
$ sudo port install cmake

# Homebrew
$ brew install cmake

Getting the S2 Code

The Reference implementation of S2 is written in C++. Once you have CMake and Git installed, you can obtain the S2 code from its repository on GitHub:

# Change to the directory where you want to create the code repository
$ cd ~
$ mkdir Source; cd Source

Clone the S2 code into your development directory:

$ git clone https://github.com/google/s2geometry.git
Cloning into 's2geometry'...
remote: Counting objects: 5672, done.
remote: Compressing objects: 100% (52/52), done.
remote: Total 5672 (delta 21), reused 36 (delta 17), pack-reused 5601
Receiving objects: 100% (5672/5672), 7.15 MiB | 27.21 MiB/s, done.
Resolving deltas: 100% (4503/4503), done.
$

Git will create the repository within a directory named s2geometry. Navigate into this directory.

Alternatively, you can download an archive of the S2 library as a ZIP file and unzip it within your development directory.

$ unzip path_to_ZIP_file/s2geometry-master.zip

Compiling S2

Once you have installed S2’s requirements and the S2 library, you are ready to build S2.

1. Configure the make files using CMake:

$ cd s2geometry  # or geometry-master if you installed from the ZIP file
$ mkdir build
$ cd build
# See Notes below on whether/when to use these cmake args
$ cmake -DWITH_GFLAGS=ON -WITH_GTEST=ON \
-DGTEST_ROOT=googletest_root_dir \
-DOPENSSL_INCLUDE_DIR=openssl_include_dir ..
-- Found OpenSSL: /usr/lib/libcrypto.dylib (found version "1.0.2m")
-- Looking for pthread.h
-- Looking for pthread.h - found
-- Looking for pthread_create
-- Looking for pthread_create - found
-- Found Threads: TRUE
-- Found PythonInterp: /Library/Frameworks/Python.framework/Versions/2.7/bin/python (found version "2.7.11")
-- Found PythonLibs: /Library/Frameworks/Python.framework/Versions/2.7/lib/libpython2.7.dylib (found version "2.7.11")
GTEST_ROOT: /absolute_path/googletest
-- Configuring done
-- Generating done
-- Build files have been written to: /absolute_path/s2geometry-master/build
$

Notes:

  • -DWITH_GFLAGS and -DWITH_GTEST may be omitted to avoid depending on those packages.
  • -DGTEST_ROOT and -DOPENSSL_INCLUDE_DIR must be absolute paths.
  • -DGTEST_ROOTis the root directory for GoogleTest (e.g. /usr/src/gtest on Linux systems, or the directory you directly installed GoogleTest within, such as /Users/username/source/googletest on MacOSX).
  • MacOSX/Homebrew users may need to set -DOPENSSL_INCLUDE_DIR to enable CMake to find your openssl include directory (e.g. /usr/local/homebrew/opt/openssl/include).
  • You can omit the DGTEST_ROOT flag to skip tests.

2. Make the S2 binary (and associated tests if GTEST_ROOT was specified in CMake:

$ make
Scanning dependencies of target gtest
...
Scanning dependencies of target s2
...
[ 35%] Built target s2
...
[100%] Built target point_index
$

3. Run the S2 tests (if GTEST_ROOT was specified in CMake):

$ make test
Running tests...
Test project /.../s2geometry-master/build
      Start  1: id_set_lexicon_test
...
83/83 Test #83: value_lexicon_test .............................   Passed    0.01 sec
100% tests passed, 0 tests failed out of 83
Total Test time (real) =  78.67 sec
$

4. Install the built S2 library:

$ make install
[  1%] Built target gtest
...
[100%] Built target point_index
Install the project...
-- Install configuration: ""
...
$

Congratulations! You’ve successfully installed S2, built the library, and run all of the tests! You’re now ready to move on to the C++ Quickstart.