.. _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
.. _`CDash`: http://www.cdash.org/
.. _`continuous integration`: http://en.wikipedia.org/wiki/Continuous_integration
.. _`libLAS CDash`: http://my.cdash.org/index.php?project=libLAS
.. _`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/