SpatialOps
Building SpatialOps

Dependencies

  • git
  • CMake version 2.8.4 or newer.
  • The Boost libraries version 1.49 or newer.
  • A relatively recent C++ compiler (G++ 4.4 or newer should be adequate). Clang also works fine. If you run into trouble with recent compilers, I would love to hear about it (contact Prof. Sutherland).
  • For the GPU execution, a functioning CUDA NVCC installation with an nVidia GPU card

Quick Guide to Download CMake and Boost on Mac

The remaining dependencies are already installed on most systems. See the maintainers' links above for installation instructions. This section is intended to be a quick guide to get started.

Installing CMake and Boost on a Macintosh

On a Macintosh, the simplest way to install CMake and Boost is via a package management system such as MacPorts or Homebrew.

Installation Commands for MacPorts

To install CMake:

 sudo port install cmake

To install Boost:

 sudo port install boost

If using MacPorts, add /opt/local/bin to the PATH. For further instructions, see Installing MacPorts.

Installation Commands for Homebrew

To install CMake:

 brew install cmake

To install Boost:

 brew install boost

Installing CMake and Boost on Another Operating System

Visit the CMake and Boost websites for more information about installing these tools.

Downloading the Source Code

The source may be obtained via git:

 git clone https://software.crsim.utah.edu:8443/James_Research_Group/SpatialOps.git [destination path]

Configuring SpatialOps

There are three ways to configure SpatialOps for a particular build: using CMake, a command-line build system generator which takes in flags as arguments; using ccmake, an executable for CMake which opens the Curses Interface for CMake, a GUI which allows editing of flags and options; or, using one of the first two options to initially set up the configuration and then manually modifying the CMake files in the build directory.

If the build of SpatialOps must be used in another project which will require it, make install must be run to build the necessary CMake configure file.

The following table summarizes the available build options

Option Default Description
CMAKE_BUILD_TYPE Release [Release | Debug] Specifies the optimization level
CMAKE_INSTALL_PREFIX build dir [path] Location to install the library to (defaults to the build directory)
ENABLE_EXAMPLES ON [ON | OFF] Enable/Disable examples
ENABLE_TESTS ON [ON | OFF] Enable/Disable tests
ENABLE_THREADS OFF [ON | OFF] Enable/Disable tests. When ON, Nebo uses the Pthread library to parallelize its calculations.
NTHREADS 1 Maximum number of active threads in the threadpool (only if ENABLE_THREADS is ON). Nebo also uses NTHREADS as its default for determining how many threads to use in each individual Nebo assignment.
ENABLE_CUDA OFF [ON | OFF] When ON, Nebo attempts to compile its GPU backend. This requires NVCC to be installed on the system. To actually use the GPU backend, a compatible GPU must be a part of the system.
NEBO_GPU_TEST OFF [ON | OFF] Used for testing. When ON, Nebo performs all calculations on a GPU, even if this requires moving memory to and from the GPU. In general, this flag makes Nebo highly inefficient, but it's useful for testing Nebo's GPU backend on code not designed to support GPU memory.
DISABLE_INTROSPECTIONOFF [ON | OFF] Use for cross-compiling to avoid auto-detecting GPU capabilities
CUDA_ARCHITECTURE_MINIMUM 3.0 The minimum compute capability to tolerate for CUDA devices.
NEBO_REPORT_BACKEND OFF [ON | OFF] Used for testing. When ON, each Nebo assignment prints a string to standard output declaring the beginning and ending of that assignment and which backend Nebo is using for that assignment. This is useful when debugging where Nebo is performing calculations.
USE_CLANG OFF [ON | OFF] When OFF, SpatialOps is built with GCC. When ON, Nebo is built with Clang. Depending on the system, GCC can be faster to compile SpatialOps while Clang generally gives better error messages. The performance results of each compiler have not been fully studied, but performance seems roughly comparable.

Building SpatialOps

While not required, it is strongly recommended to build in a directory other than the source code directory. This is recommended because some files are modified for GPU support, and building in the source code directory may break SpatialOps. To avoid this, SpatialOps and Nebo developers may use a build directory which can either be a subdirectory of the source directory or contained in a separate part of the file system.

Making and Installing SpatialOps

After SpatialOps has been configured, it must be built by issuing the make command in the build directory. The make command can take the name of an executable as an option to build only that executable; but, by default, it builds everything. The make command can also take a -j<n> flag where <n> is the number of threads to be used during the build process. (This option may either speed up or slow down the build time, depending on the system being used.)

Note that SpatialOps relies on heavily templated code and can use substantial memory when compiling. Therefore, parallel builds should be done only on systems with adequate memory resources. 1 GB per parallel build process is more than adequate.

Sample Configuration and Build Scripts

  • Build an optimized version and install it in the local build directory
         cmake [path to src] -DCMAKE_BUILD_TYPE=Release
         make -j4 install
  • Build an optimized version and install it in /usr/local
         cmake [path to src]                 \
           -DCMAKE_BUILD_TYPE=Release        \
           -DCMAKE_INSTALL_PREFIX=/usr/local \
           -DENABLE_EXAMPLES=ON
           
         make install
  • Build a project that can be imported into the Eclipse IDE. It will build using 8 cores. Note that if the system has limited memory, -DCMAKE_ECLIPSE_MAKE_ARGUMENTS=-j8 should be eliminated below.
         cmake [path to src]                  \
          -G "Eclipse CDT4 - Unix Makefiles"  \
          -DCMAKE_ECLIPSE_MAKE_ARGUMENTS=-j8  \
          -DCMAKE_BUILD_TYPE=Debug            
  • Build a project with debug flags that can be imported into the XCode IDE.
         cmake [path to src]                  \
          -G "Xcode"                          \
          -DCMAKE_ECLIPSE_MAKE_ARGUMENTS=-j8  \
          -DCMAKE_BUILD_TYPE=Debug            
  • Build a version on a system with a 3.0 compute capability GPU and the CUDA SDK installed:
         cmake [path to src]            \
          -DCMAKE_BUILD_TYPE=Release    \
          -DENABLE_CUDA=ON              \
          -DCUDA_ARCHITECTURE=3.0     
         make -j4          

Installation and Downstream Usage

When running make install, the following directory structure is created:

 install_dir
  |- include
  |   |- spatialops
  |   |   |- ...
  |- lib
  |   |- spatialops
  |   |   |- ...
  |- bin
  |   + spatialops
  |- share
  |   |- SpatialOpsConfig.cmake

If using CMake for downstream applications:

  1. Configure/install SpatialOps as described in the Making and Installing SpatialOps section of this page.
  2. Add the following to the CMakeLists.txt file:
    find_package( SpatialOps REQUIRED )
    Note that CMake's search path should include (or be directed to) the [install_dir]/share folder where SpatialOps was installed to. The find_package command will define two key variables:
    • SpatialOps_INCLUDE_DIR – provides the appropriate inclusion path for the compiler. This should be set using
      include_directories( ${SpatialOps_INCLUDE_DIR} )
    • spatialops – the library to link to using
      target_link_libraries( target spatialops )

If CMake will not be used for downstream applications:

  1. Configure/install SpatialOps as described in the Making and Installing SpatialOps section of this page.
  2. Link lines should include the [install_dir]/lib/spatialops path and the appropriate library located in that directory.
  3. Include [install_dir]/include/ in the inclusion path.

Tests and Examples

To build the tests and examples, set ENABLE_TESTS=ON and ENABLE_EXAMPLES=ON when configuring SpatialOps (see Configuring SpatialOps).

Running Tests

To run tests, simply use:

 ctest

or, to run multiple tests concurrently,

 ctest -jN

where N is the level of concurrency.

Running Examples

If make install has been run, then the examples are installed into [install_dir]/bin/spatialops. Otherwise, just run make; then the examples can be found in the examples directory in the build directory.