Unix Compilation

Author:Howard Butler
Contact:howard@hobu.co
Date:10/27/2015

CMake 2.8.11+ is the prescribed tool for building from source, with CMake 3.0+ being desired. CMake is a cross-platform build system that provides a number of benefits, and its usage ensures a single, up-to-date build system for all PDAL-supported operating systems and compiler platforms.

Like a combination of autoconf/autotools, except that it works on Windows with minimal eye-stabbing pain, CMake is somewhat of a meta-building tool. It can be used to generate MSVC project files, GNU Makefiles, NMake files for MSVC, XCode projects on Mac OS X, and Eclipse projects (as well as many others). This functionality allows the PDAL project to avoid maintaining these build options by hand and target a single configuration and build platform.

This tutorial will describe how to build PDAL using CMake on a Unix platform. PDAL is known to compile on Linux 2.6’s of various flavors and OSX with XCode.

See also

Docker contains an automated way to build PDAL and all of its dependencies.

Note

Dependencies contains more information about specific library version requirements and notes about building or acquiring them.

Using “Unix Makefiles” on Linux

Get the source code

See Development Source for how to obtain the latest development version or visit Download to get the latest released version.

Prepare a build directory

CMake allows you to generate different builders for a project, and in this example, we are going to generate a “Unix Makefiles” builder for PDAL on Mac OS X.

$ cd PDAL
$ mkdir makefiles
$ cd makefiles

Configure base library

Configure the basic core library for the “Unix Makefiles” target:

$ cmake -G "Unix Makefiles" ../
-- The C compiler identification is GNU
-- The CXX compiler identification is GNU
-- Checking whether C compiler has -isysroot
-- Checking whether C compiler has -isysroot - yes
-- Check for working C compiler: /usr/bin/gcc
-- Check for working C compiler: /usr/bin/gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Checking whether CXX compiler has -isysroot
-- Checking whether CXX compiler has -isysroot - yes
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Enable PDAL utilities to build - done
-- Configuring done
-- Generating done
-- Build files have been written to: /Users/hobu/dev/git/PDAL-cmake/makefiles

Note

The ./cmake/examples/hobu-config.sh shell script contains a number of common settings that I use to configure my Homebrew-based Macintosh system.

Issue the make command

This will build a base build of the library, with no extra libraries being configured.

Run make install and test your installation with a Testing command

make install will install the utilities in the location that was specified for ‘CMAKE_INSTALL_PREFIX’. Once installed, ensure that you can run pdal info.

Configure your Optional Libraries.

By checking the “on” button for each, CMake may find your installations of these libraries, but in case it does not, set the following variables, substituting accordingly, to values that match your system layout.

GDAL GDAL_CONFIG /usr/local/bin/gdal-config
  GDAL_INCLUDE_DIR /usr/local/include
  GDAL_LIBRARY /usr/local/lib/libgdal.so
GeoTIFF GEOTIFF_INCLUDE_DIR /usr/local/include
  GEOTIFF_LIBRARY /usr/local/lib/libgeotiff.so
OCI ORACLE_INCLUDE_DIR /home/oracle/sdk/include
  ORACLE_NNZ_LIBRARY /home/oracle/libnnz10.so
  ORACLE_OCCI_LIBRARY /home/oracle/libocci.so
  ORACLE_OCIEI_LIBRARY /home/oracle/libociei.so
  ORACLE_OCI_LIBRARY /home/oracle/libclntsh.so

CCMake and cmake-gui

Warning

The following was just swiped from the libLAS compilation document and it has not been updated for PDAL. The basics should be the same, however. Please ask on the mailing list if you run into any issues.

While CMake can be run from the command-line, and this is the preferred way for many individuals, it can be much easier to run CMake from a GUI. Now that we have a basic library building, we will use CMake’s GUIs to help us configure the rest of the optional components of the library. Run ccmake ../ for the Curses interface or cmake-gui ../ for a GUI version.

Running CCMake in OS X

Running the Curses CMake interface. This interface is available to all unix-like operating systems.

Note

If your arrow keys are not working with in CCMake, use CTRL-N and CTRL-P to move back and forth between the options.

Running cmake-gui in OS X

Running the cmake-gui CMake interface. This interface is available on Linux, Windows, and Mac OS X.

Build and install

Once you have configured your additional libraries, you can install the software. The main pieces that will be installed are:

  • PDAL headers (typically in a location ./include/pdal/...)
  • PDAL C++ (PDAL.a or PDAL.so) library
  • PDAL C (PDAL_c.a or PDAL_c.so) library
  • Utility programs
make install

Using “XCode” on OS X

Get the source code

See Development Source for how to obtain the latest development version or visit Download to get the latest released version.

Prepare a build directory

CMake allows you to generate different builders for a project, and in this example, we are going to generate an “Xcode” builder for PDAL on Mac OS X. Additionally, we’re going to use an alternative compiler – LLVM – which under certain situations can produce much faster code on Mac OS X.

$ export CC=/usr/bin/llvm-gcc
$ export CXX=/usr/bin/llvm-g++
$ cd PDAL
$ mkdir xcode
$ cd xcode/

Configure base library

Configure the basic core library for the Xcode build:

$ cmake -G "Xcode" ..
-- The C compiler identification is GNU
-- The CXX compiler identification is GNU
-- Checking whether C compiler has -isysroot
-- Checking whether C compiler has -isysroot - yes
-- Check for working C compiler: /usr/bin/llvm-gcc
-- Check for working C compiler: /usr/bin/llvm-gcc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Checking whether CXX compiler has -isysroot
-- Checking whether CXX compiler has -isysroot - yes
-- Check for working CXX compiler: /usr/bin/llvm-g++
-- Check for working CXX compiler: /usr/bin/llvm-g++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Enable PDAL utilities to build - done
-- Enable PDAL unit tests to build - done
-- Configuring done
-- Generating done
-- Build files have been written to: /Users/hobu/hg/PDAL-cmake/xcode

Alternatively, if you have KyngChaos frameworks for GDAL and GeoTIFF installed, you can provide locations for those as part of your cmake invocation:

$ cmake -G "Xcode" \
  -D GDAL_CONFIG=/Library/Frameworks/GDAL.framework/Programs/gdal-config \
  -D GEOTIFF_INCLUDE_DIR=/Library/Frameworks/UnixImageIO.framework/unix/include \
  -D GEOTIFF_LIBRARY=/Library/Frameworks/UnixImageIO.framework/unix/lib/libgeotiff.dylib \
  ..

Note

I recommend that you use in Homebrew for GDAL and friends. Its configuration is featureful and up-to-date.

$ open PDAL.xcodeproj/
Building PDAL using the XCode project

Set default command for XCode

Set the default executable for the project to be lasinfo by opening the “Executables” tree, choosing “lasinfo,” and clicking the bubble next to the “Executable name” in the right-hand panel.

Setting the default executable

Set arguments for Testing

Set the arguments for Testing so it can be run from within XCode. We use the ${PROJECT_DIR} environment variable to be able to tell pdal_test the location of our test file. This is similar to the same command above in the “Unix Makefiles” section.

Setting the arguments for lasinfo

Configure Optional Libraries

As before, use ccmake ../ or cmake-gui ../ to configure your Dependencies.

Configuring optional libraries with CMake GUI