S2 Installation
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:
- OpenSSL (for its bignum library)
- gflags command line flags {:target=”_blank”} (optional, disabled by default)
- glog logging module {:target=”_blank”} (optional, disabled by default)
- googletest testing framework
- SWIG (optional, for Python interface)
- 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_GFLAGSand-DWITH_GTESTmay be omitted to avoid depending on those packages.-DGTEST_ROOTand-DOPENSSL_INCLUDE_DIRmust be absolute paths.-DGTEST_ROOTis the root directory for GoogleTest (e.g./usr/src/gteston Linux systems, or the directory you directly installed GoogleTest within, such as/Users/username/source/googleteston MacOSX).- MacOSX/Homebrew users may need to set
-DOPENSSL_INCLUDE_DIRto enable CMake to find your opensslincludedirectory (e.g./usr/local/homebrew/opt/openssl/include). - You can omit the
DGTEST_ROOTflag 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.