[[PageOutline]]
= Building osgEarth =

osgEarth is a cross-platform library. It uses the [http://www.cmake.org/ CMake] cross-platform build system, ''version 2.8 or newer''.  This is the same build system that [http://www.openscenegraph.org OpenSceneGraph] uses.

----
== GET THE SOURCE CODE ==

=== Option 1: use GIT ===

osgEarth source is hosted on !GitHub.  You will need a git client to access it.  We recommend [http://code.google.com/p/tortoisegit/ TortoiseGit] for Windows users.

To clone the repository, point your client at:

 [git://github.com/gwaldron/osgearth.git]

The latest tagged release is ''Version 2.3''. The git tag [https://github.com/gwaldron/osgearth/archive/osgearth-2.3.zip osgearth-2.3].

=== Option 2: download a tarball ===

To download a tarball, visit the [http://github.com/gwaldron/osgearth/tags Tags Page] and select the one you want.

== GET THE DEPENDENCIES ==

The following are '''REQUIRED DEPENDENCIES''':

 * [http://www.openscenegraph.org OpenSceneGraph] 3.0 or later, with the CURL plugin enabled

 * [http://gdal.org/ GDAL] 1.6 or later - Geospatial Data Abstraction Layer (version 1.5 will work too)

 * [http://curl.haxx.se/libcurl/ CURL] - HTTP transfer library (comes with OSG 3rd party library distros)

The following are '''OPTIONAL DEPENDENCIES'''. osgEarth will compile without them, but some functionality will be missing:

 * [http://trac.osgeo.org/geos/ GEOS] 3.2.0 or later - C++ library for topological operations. This library is used by the osgEarthFeatures module to perform various geometry manipulation operations like buffering and intersection. If you plan to display vector/feature data in osgEarth, get this.

 * [http://www.winimage.com/zLibDll/minizip.html MiniZip] - zip file extractor; include this is you want to read KMZ files. (Win32/VS9 binary at the bottom of this page)

 * [http://www.sqlite.org SQLite] 3.6 or later - embedded relational database engine. This is used by the cache_sqlite driver to cache tile data to an sqlite3 database.

 * [http://code.google.com/p/v8 V8] - Google's !JavaScript interpreter. Inlcude this if you want to embed !JavaScript code in your earth file.

=== Option: get the pre-built 3rd Party Binaries for Win32 ===

 * [http://openscenegraph.alphapixel.com/osg/downloads/openscenegraph-third-party-library-downloads OSG pre-built 3rd-party dependencies] from !AlphaPixel
 * [http://mew.cx/osg/ OSG pre-built installations and 3rd-party dependencies] from MEW (including CURL and GDAL)
 * [http://sourceforge.net/project/showfiles.php?group_id=10127 Pre-built Expat] for Win32
 * [http://www.osgearth.org/attachment/wiki/Downloads/minizip-win32-vs9.zip MiniZIP] for Win32 VS9
 * [http://vbkto.dyndns.org:1280/sdk/Default.aspx Some pre-built GDAL/OGR/PROJ downloads] for various architectures

== BUILD IT ==

osgEarth uses the [http://www.cmake.org/ CMake] build system, version 2.8 or newer.

Tips:

 * For optional dependencies (like GEOS or V8) you can just leave the entries blank (even if CMake complains).
 * For OSG, just input the OSG_DIR variable, generate, and CMake will find all the other OSG folder automatically. 
 * Ensure the "DYNAMIC_OSGEARTH" flag is ON. Building osgEarth as a static library does not yet work on all platforms.
 * For the OPTIONAL dependencies listed above, just leave the corresponding entries blank if you don't want to use them.
 * Sometimes CMake will complain that it cannot run osgversion. You can safely ignore this in most cases.

----
== GET PRE-BUILT BINARIES ==

=== Debian/Ubuntu Packages === 

osgEarth is available pre-built for Debian Sid, Ubuntu Lucid, Maverick and 
Natty. Ubuntu packages are available from the ''!UbuntuGis PPA''. 
Installation: 

{{{ 
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable 
}}} 
{{{ 
sudo aptitude install osgearth osgearth-data 
}}} 

For trying osgEarth without installation you can download the OSGeo Live-DVD 
from http://live.osgeo.org/

Thanks to Pirmin Kalberer for developing and maintaining these packages.

=== Windows Pacakges ===

 * [http://www.nlneilson.com/wwposts/OsgEarth_nln.zip osgEarth 2.0, VS10] (Built Feb 2011 - Thanks to Neil Neilson)

----
= Testing =

Sample earth files are located within the subversion repository [http://wush.net/trac/osgearth/browser/trunk/tests here]. Simple use 'osgviewer' (from the !OpenSceneGraph distribution) to view a .earth file:

  {{{ osgviewer gdal_tiff.earth }}}

== Basic Troubleshooting ==

The most common pitfall is shared libraries missing from your path. Your path should include:

 * OSG and osgEarth binaries
 * All of osgEarth's dependencies (Expat, CURL, and GDAL shared libs)
 * OSG's 3rd-party dependencies (particularly zlib and the libpng)

If you get an error complaining about a missing CURL plugin:

 * The CURL plugin is optional in the OSG CMake configuration. Make sure you enable and build it.

If you cannot get the GDAL driver to work properly:

 * Make sure the GDAL shared library is in your path
 * Set the GDAL_DATA environment variable to point to the folder containing GDAL's .csv files

If you still have problems, please [http://forum.osgearth.org search the forums or post a question].