compilation.txt

.. _compilation:

******************************************************************************
Compilation
******************************************************************************

.. contents::
    :depth: 3
    :backlinks: none


:Author: Mateusz Loskot
:Contact: mateusz at loskot dot net
:Author: Howard Butler
:Contact: hobu.inc at gmail dot com

.. warning::
    This document is only for the 1.6 libLAS release.  Unfortunately,
    there is no documentation for building earlier libLAS releases at this time, though
    it is a straightforward `Autoconf`_ setup for unix and nmake files for
    windows.

As of libLAS 1.6, `CMake`_ 2.8.1+ is the prescribed tool for building
libLAS from source as well as running unit tests. `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 libLAS-supported operating systems
and compiler platforms.

Like a combination of autoconf/autotools, except that it actually works on
Windows (and works without eye-stabbing pain in general), `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 libLAS project
to avoid maintaining these build options by hand and target a single configuration
and build platform.

This tutorial will describe how to build libLAS using CMake on both a
Unix platform and a Windows platform.

.. note::
    The only supported build environment libLAS moving forward from the 1.6
    release is `CMake`_. `Autoconf`_ configuration will be phased out and will
    no longer be updated after the 1.6 release.

.. _prerequisites:

Prerequisites
..............................................................................

In addition to `CMake`_ 2.8.1+, you also need a C/C++ compiler.  The
following compilers are known to work:

* MSVC 2003 (VC 7.1) (not all optional libraries work with 2003)
* MSVC 2005 (VC 8.0)
* MSVC 2008 (VC 9.0)
* MSVC 2010
* GCC 4.0
* GCC 4.2
* LLVM 4.8/Clang 2.8

`Boost`_
------------------------------------------------------------------------------

`Boost`_ is required to build libLAS 1.6.  Set ``Boost_INCLUDE_DIR`` if
CMake cannot find it in a default location.  Additionally, set ``Boost_LIBRARY_DIRS``
if it cannot find your libraries.

.. warning::
    You need Boost version 1.38.0 or higher to build libLAS 1.6.

.. note::

    If you are building on Windows, http://www.boostpro.com/download/ has an
    excellent installer. The boost installer defaults are not enough, however,
    and you will need to scroll down and select "Boost ProgramOptions", "Boost Thread", and
    "Boost Serialization" components, and select static + multithreaded as the
    types. If you want to link in a different way, you will have to change
    your CMake cache variables ``Boost_USE_STATIC_LIBS`` and ``Boost_USE_MULTITHREADED``
    accordingly.

    .. figure:: ./images/boostpro-options.png
        :alt: Selecting program_options with the Boostpro.com installer

.. _optional_libraries:

Optional libraries
..............................................................................

The base libLAS library can work without optional libraries to read and write
LAS files, but linking in libraries like `GDAL`_, and `libgeotiff`_ will
provide a boost in functionality to libLAS. libLAS linkage of GDAL and
libgeotiff enhances spatial coordinate system description and provides data
reprojection support. By linking `OCI`_ with the `Oracle Instant Client`_,
libLAS can be used to load LAS data into `Oracle Point Cloud`_ -enabled Oracle
tables.

Building these libraries is beyond the scope of this document, but all except
`OCI`_ can be built from source and installed at your leisure.

`GDAL`_
------------------------------------------------------------------------------

Obtain `GDAL`_ via whatever method is convenient.  Linux platforms such as
`Debian`_ have `DebianGIS`_, Mac OS X has the `KyngChaos`_ software frameworks,
and Windows has the `OSGeo4W`_ platform.

* GDAL 1.7+ is required.

.. note::
    If you are using `OSGeo4W`_ as your provider of GDAL, you must use the
    ``gdal-dev`` package, which is GDAL 1.8 as of 11/19/2010.


`libgeotiff`_
------------------------------------------------------------------------------

Obtain `libgeotiff`_ from the same place you got `GDAL`_.

* libgeotiff 1.3.0+ is required

.. note::
    `GDAL` surreptitiously embeds a copy of `libgeotiff`_ in its library build
    but there is no way for you to know this.  In addition to embedding
    libgeotiff, it also strips away the library symbols that libLAS needs,
    meaning that libLAS can't simply link against `GDAL`_.  If you are
    building both of these libraries yourself, make sure you build GDAL
    using the "External libgeotiff" option, which will prevent the
    insanity that can ensue on some platforms.  `OSGeo4W`_ users, including
    those using that platform to link and build libLAS themselves, do
    not need to worry about this issue.

`OCI`_
------------------------------------------------------------------------------

Obtain the `Oracle Instant Client`_ and install in a location on your system.
Be sure to install both the "Basic" and the "SDK" modules. Set your
``ORACLE_HOME`` environment variable system- or user-wide to point to this
location so the CMake configuration can find your install.

.. warning::
    `OCI`_'s libraries are inconsistently named.  You may need to create
    symbolic links for some library names in order for the `CMake`_ to find
    them::

        cd $ORACLE_HOME
        ln -s libocci.so.11.1 libocci.so
        ln -s libclntsh.so.11.1 libclntsh.so
        ln -s libociei.so.11.1 libociei.so

.. note::
    MSVC should only require the oci.lib and oci.dll library and dlls.

* Oracle 11g is recommended, but OCI for 10g will work.

.. _`libgeotiff`: http://www.remotesensing.org/geotiff/geotiff.html
.. _`7/28/2008`: http://lists.maptools.org/pipermail/geotiff/2008-July/000501.html
.. _`proj.4`: http://proj.maptools.org/
.. _`GDAL`: http://www.gdal.org
.. _`Oracle Instant Client`: http://www.oracle.com/technology/tech/oci/instantclient/index.html
.. _`OCI`: http://www.oracle.com/technology/tech/oci/index.html
.. _`R-tree`: http://en.wikipedia.org/wiki/R-tree
.. _`Oracle Point Cloud`: http://download.oracle.com/docs/cd/B28359_01/appdev.111/b28400/sdo_pc_pkg_ref.htm
.. _`DebianGIS`: http://wiki.debian.org/DebianGis
.. _`Debian`: http://www.debian.org
.. _`KyngChaos`: http://www.kyngchaos.com/software/unixport
.. _`OSGeo4W`: http://trac.osgeo.org/osgeo4w/
.. _`libtiff`: http://remotesensing.org/libtiff/



Using "Unix Makefiles" on Linux
..............................................................................

Get the source code
------------------------------------------------------------------------------

See :ref:`source` for how to obtain the latest development version or visit
:ref:`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 libLAS on Mac OS X.

::

    $ cd liblas
    $ 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 libLAS utilities to build - done
    -- Configuring done
    -- Generating done
    -- Build files have been written to: /Users/hobu/hg/liblas-cmake/makefiles

Issue the `make` command
------------------------------------------------------------------------------

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

::

    $ make
    -- Enable libLAS utilities to build - done
    -- Configuring done
    -- Generating done
    -- Build files have been written to: /Users/hobu/hg/liblas-cmake/makefiles
    Scanning dependencies of target las
    [  3%] Building CXX object src/CMakeFiles/las.dir/lasclassification.cpp.o
    ...
    [ 60%] Building CXX object src/CMakeFiles/las.dir/detail/writer/writer.cpp.o
    Linking CXX static library ../bin/Debug/liblas.a
    [ 60%] Built target las
    Scanning dependencies of target las_c
    [ 63%] Building CXX object src/CMakeFiles/las_c.dir/las_c_api.cpp.o
    Linking CXX shared library ../bin/Debug/liblas_c.dylib
    [ 63%] Built target las_c
    Scanning dependencies of target las2las
    ...
    [100%] Built target txt2las

.. _make_install:

Run ``make install`` and test your installation with a :ref:`lasinfo` command
------------------------------------------------------------------------------

``make install`` will install the :ref:`utilities <utilities>` in the location
that was specified for 'CMAKE_INSTALL_PREFIX'.  Once installed, ensure that
you can run lasinfo.

::

    $ lasinfo ../test/data/TO_core_last_clip.las

    ---------------------------------------------------------
      Header Summary
    ---------------------------------------------------------
      File Name: ../test/data/TO_core_last_clip.las
      Version:                    1.0
      Source ID:                  0
      Reserved:                   0
      Project ID/GUID:           '00000000-0000-0000-0000-000000000000'
      System Identifier:         ''
      Generating Software:       'TerraScan'
      File Creation Day/Year:    0/0
      Header Size                227
      Offset to Point Data       229
      Number Var. Length Records 0
      Point Data Format          1
      Point Data Record Length   28
      Number of Point Records    213093
      Number of Points by Return 128621 84472 0 0 0
      Scale Factor X Y Z         0.01 0.01 0.01
      Offset X Y Z               -0.000000 -0.000000 -0.000000
      Min X Y Z                  630250.000000 4834500.000000 46.830000
      Max X Y Z                  630500.000000 4834750.000000 170.650000
     Spatial Reference
    Geotiff_Information:
       Version: 1
       Key_Revision: 1.0
       Tagged_Information:
          End_Of_Tags.
       Keyed_Information:
          End_Of_Keys.
       End_Of_Geotiff.

    ---------------------------------------------------------
      Point Inspection Summary
    ---------------------------------------------------------
      Header Point Count: 213093
      Actual Point Count: 213093

      Minimum and Maximum Attributes (min,max)
    ---------------------------------------------------------
      Min X,Y,Z:        630250.000000,4834500.000000,46.830000
      Max X,Y,Z:        630500.000000,4834750.000000,170.650000
      Bounding Box:     630250.00,4834500.00,630500.00,4834750.00
      Time:         413162.560400,414095.322000
      Return Number:    1,2
      Return Count:     1,2
      Flightline Edge:  0,0
      Intensity:        10,50200
      Scan Direction Flag:  0,0
      Scan Angle Rank:  0,0
      Classification:   1,1
      Point Source Id:  0,0
      Minimum Color:     0 0 0
      Maximum Color:     0 0 0

      Number of Points by Return
    ---------------------------------------------------------
        (0) 128621  (1) 84472   (2) 0   (3) 0   (4) 0
     Total Points: 213093

      Number of Returns by Pulse
    ---------------------------------------------------------
        (1) 128621  (2) 84472   (3) 0   (4) 0   (5) 0   (6) 0   (7) 0
     Total Pulses: 213093

      Point Classifications
    ---------------------------------------------------------
          213093 Unclassified (1)


.. _configure_optional_libraries:

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.

.. csv-table::

    "`GDAL`_","GDAL_CONFIG", "/usr/local/bin/gdal-config"
    "","GDAL_INCLUDE_DIR", "/usr/local/include"
    "","GDAL_LIBRARY", "/usr/local/lib/libgdal.so"
    "`libgeotiff`_","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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.


.. figure:: ./images/ccmake-osx-start.png
    :alt: 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.

.. figure:: ./images/cmake-gui-osx-start.png
    :alt: 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:

* libLAS headers (typically in a location ./include/liblas/...)
* libLAS C++ (liblas.a or liblas.so) library
* libLAS C (liblas_c.a or liblas_c.so) library
* :ref:`Utility <utilities>` programs

::

    make install

Using "XCode" on OS X
..............................................................................


Get the source code
------------------------------------------------------------------------------

See :ref:`source` for how to obtain the latest development version or visit
:ref:`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 libLAS 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 liblas
    $ 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 libLAS utilities to build - done
    -- Enable libLAS unit tests to build - done
    -- Configuring done
    -- Generating done
    -- Build files have been written to: /Users/hobu/hg/liblas-cmake/xcode


Alternatively, if you have `KyngChaos`_ frameworks for `GDAL`_ and `libgeotiff`_ 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 \
      ..


::

    $ open libLAS.xcodeproj/

.. figure:: ./images/xcode-start.png
    :alt: Building libLAS 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.

.. figure:: ./images/xcode-set-default-executable.png
    :alt: Setting the default executable

Set arguments for :ref:`lasinfo`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Set the arguments for :ref:`lasinfo` so it can be run from within XCode. We
use the ${PROJECT_DIR} environment variable to be able to tell lasinfo the
location of our test file. This is similar to the :ref:`same command
<make_install>` above in the "Unix Makefiles" section.

.. figure:: ./images/xcode-lasinfo-arguments.png
    :alt: Setting the arguments for lasinfo

Build and run the :ref:`lasinfo` command
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open the console by pressing CMD-SHIFT-R or by navigating to the Run-Console
menu and press the `Build and Run` button.


.. figure:: ./images/xcode-lasinfo-output.png
    :alt: lasinfo output in XCode


Configure `Optional Libraries`_
------------------------------------------------------------------------------

As :ref:`before <configure_optional_libraries>`, use ``ccmake ../`` or ``cmake-gui ../`` to
configure your :ref:`optional_libraries`.


.. figure:: ./images/cmake-gui-osx-configured.png
    :alt: Configuring optional libraries with CMake GUI

    Configuring `Optional Libraries`_ with CMake GUI



Using "Visual Studio 9 2008" on Windows
..............................................................................

Get the source code
------------------------------------------------------------------------------

See :ref:`source` for how to obtain the latest development version or visit
:ref:`download` to get the latest released version.

.. _msvc_prerequisites:

Prerequisites
------------------------------------------------------------------------------

* Ensure that you have `CMake 2.8.0+`_ installed on your system.


* Install `OSGeo4W`_ on your system to get `Optional Libraries`_ in
  pre-compiled form.  You can build these from source yourself, but it is
  much more convenient to get them from OSGeo4W.

  * gdal-dev
  * libtiff
  * libgeotiff

  .. figure:: ./images/windows-osgeo4w-advanced-install.png
            :alt: OSGeo4W installation

            Choose the "Advanced install" to be able to pick the libraries
            and their headers that you need.

  .. figure:: ./images/windows-osgeo4w-choosing-packages.png
            :alt: Choosing libraries

            Open up the "Libs" tree and choose the libraries you need



Run ``cmake-gui.exe``
------------------------------------------------------------------------------

* Run ``cmake-gui.exe`` from a "Visual Studio 2008 Command Prompt"

::

    cd d:\\liblas
    cmake-gui .

.. figure:: ./images/windows-cmake-start.png
    :alt: Starting CMake

    Upon opening cmake-gui, nothing will be configured.

    .. note::
        The Visual Studio Prompt can be found by navigating through the start
        bar to "Start" -- "Microsoft Visual Studio 2008" -- "Visual Studio
        Tools " -- "Visual Studio 2008 Command Prompt". This command prompt
        sets a number of environment variables necessary for Visual Studio to
        run, and `CMake`_ must have these variables set in order for it to
        work properly.

        .. figure:: ./images/windows-command-prompt.png
            :alt: Visual Studio Command prompt

.. figure:: ./images/windows-cmake-generator-visual-studio-9.png
    :alt: Generating a project

* Click "Configure" and a window will pop up asking what type of build to
  generate. Choose "Visual Studio 9 2008."

* Click "Generate" and a "libLAS.sln" file will be in ``d:\\liblas``

* Open and build the project

.. image:: ./images/windows-msvc-build.png


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.

.. note::
    If you are building using `OSGeo4W`_ libraries, you must use the "gdal-dev"
    version, not the base `GDAL`_ build.  libLAS requires GDAL 1.7+ to
    operate, and this is provided by the "gdal-dev" `OSGeo4W`_ version.

.. note::
    You will need to choose "Advanced View" and select the location of the
    libTIFF library explicitly.

.. csv-table::

    "`GDAL`_","GDAL_INCLUDE_DIR", "c:\\osgeo4w\\apps\\gdal-dev\\include"
    "","GDAL_LIBRARY", "c:\\osgeo4w\\apps\\gdal-dev\\lib\\gdal_i.lib"
    "`libgeotiff`_","GEOTIFF_INCLUDE_DIR","c:\\osgeo4w\\include"
    "","GEOTIFF_LIBRARY","c:\\osgeo4w\\lib\\geotiff_i.lib"
    "`libtiff`_","TIFF_INCLUDE_DIR","c:\\osgeo4w\\include"
    "","TIFF_LIBRARY","c:\\osgeo4w\\lib\\libtiff_i.lib"


------------------------------------------------------------------------------

.. _`CMake`: http://www.cmake.org/
.. _`CTest`: http://cmake.org/cmake/help/ctest-2-8-docs.html
.. _`CMake 2.8.0+`: http://www.cmake.org/cmake/help/cmake-2-8-docs.html
.. _`continuous integration`: http://en.wikipedia.org/wiki/Continuous_integration
.. _`Curses`: http://en.wikipedia.org/wiki/Curses_%28programming_library%29
.. _`Autoconf`: http://www.gnu.org/software/autoconf/
.. _`LLVM`: http://llvm.org/
.. _`OSGeo4W`: http://trac.osgeo.org/osgeo4w/
.. _`Boost`: http://www.boost.org/