.. _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 ` 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 ` 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 ` 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 `, 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/