Source Code

The X-Plane Scenery Tools are available as source code, as well as binaries.  This article describes how to get, compile, and modify the scenery tools code.  See also:

Setting Up Your Build Environment

The X-Plane scenery tools code (XPTools) can be compiled for Mac, Windows, or Linux (port still in progress). Before you can work on the tools, you may need to get/update your development environment.

Mac OS X

To build on OS X, you need OS X 10.6.x and an Intel Macintosh with X-Code 3.2.x. To get X-Code, go to http://developer.apple.com/, register as an ADC develop if needed (it’s free as in beer), and download the X-Code DMG. It’s big. The DMG runs an installer that gets you everything you need.

You will also need the command-line tool CMake, which can be found here: http://www.cmake.org/

Important: if you install CMake using the disk image (.dmg) be sure to say yes when asked if you want to isntall the symbolic links to the command-line tools. If you do not install symbolic links, the libraries will not build.

What, you really want to compile on Lion?  Well, it’s not impossible.  See Chris’s summary about how to force the 10.5 SDK onto Lion here.  Basically the scenery tools code currently requires X-Code 3.2 and the 10.5 SDK so you need to retrofit these build components onto Lion.  Once the code is modernized to the 10.6 SDK, the code should “just work” with current tools.

Windows

There are two choices for tool-chains on Windows.  If you only want to work on WorldEditor and you are willing to work on the code for 1.3 or later (which is in master as of this writing) you can use Microsoft Visual Studio Express 2010 or later.  This is the easier option.  If you want to work on all of the tools or want to work on older versions of WED (1.0 – 1.2) you will need to use Mingw.

Setting up MSVC is straight forward: the standard installation of Microsoft Visual Studio Express 2010 or 2012 is all you need.  You will also need some kind of GIT client; GIT GUI is a simple choice, and the command-line syntax listed here will look in the “GIT Bash” option that comes with it.

The rest of this section covers using MinGW.

WARNING: make sure there are no spaces in the paths up to the code on Windows! The Makefile does not handle this case yet. You may want to consider this when installing the tools.

MinGW is the supported compiler – you will need to set up a full mingw environment with GCC 4.2.x or newer. The simplest way to do that is with the XPTools Environment Installer, which can be downloaded here.

The installer is a net-installer – that is, it will download the latest components to the build environment. The build environment is entirely self-contained – simply delete it when done – it does not install any registry keys, COM components, or other global “stuff”.

To start the environment, run startenv.bat from the root of the installation directory. It will put you automatically in the Scenery Tools Source directory if you choosed to download the sources during the installation, or into your home directory if you skipped that step.

To update the buildenvironment itself (i.e. when we added a new gcc release for example) just start the environment and execute following commands:

cd /
git pull origin master:master

This however might fail when we update bash or git in the environment because Windows locks files which are currently in use. In this case just re-run the Buildenvironment Installer over an existing installation to update the environment (you will need an installer version >= 1.1.1 for this to work).

Similary you can update the Scenery Tools source tree with:

cd /xptools
git pull origin master:master

Note that you aren’t on the master branch after a fresh installation, but a specific commit because the Scenery Tools tree is registered as a git submodule in the build environment. Therefore you need to make sure that you switch to the master branch before building the tools after updating the tree (you need to do this only once after a fresh installation):

cd /xptools
git checkout master

Linux

You will need GCC 4.2.x – 4.5.x, and a few packages:

  • gnu make
  • gnu coreutils
  • binutils, binutils-devel if applicable for libbfd.a
  • libmpfr-devel
  • qt4-devel
  • mesa-libGL-devel, mesa-libGLU-devel or the proprietary variants from ATI or NVidia

Get the source code

The scenery tools source code lives in a public GIT repository.  There are two basic ways to get source code: browse the tree online with CGIT (and download a tarball) or clone the repository.

Browse the tree online

For those who want to keep track of the most recent changes, or only want to steal shamelessly code via copy&paste, have a look at:

http://dev.x-plane.com/cgit/cgit.cgi/xptools.git/

From that link you can download a tarball of the most recent code, or download any major release; binary tools releases have matching tags in the repo.

Clone the Git repository

Those who want to contribute patches and do serious development on the tree, can clone the repository with git, using the fast Git protocol:

git clone git://dev.x-plane.com/xptools.git

If you have trouble cloning using the Git protocol (typically due to a firewall), you can instead use the considerably slower HTTP protocol:

git clone http://dev.x-plane.com/git/xptools.git

Compiling the Program

The scenery tools source code depends on a large number of third party libraries; to make cross-platform development easier, they live in a sub-folder of the code tree.

Building Libraries

(This step is not necessary when using MSVC to build WorldEditor 1.3 or newer on Windows.)

The first time you want to compile, you need to first download and compile your libraries.  From your repository you can do this:

git submodule update --init
cd libs
make

The libraries can take 20-30 minutes to compile!

Building on Linux and Windows (Command line/MinGW)

I tried to make this process as simple as possible. First of all make sure that you have following prerequisites installed:

  • development packages of libbfd (mostly included in binutils), libmpfr, libz and boost
  • gcc (i think :-))
  • gnu make

then just do a

make

in the Scenery Tools root directory. Take a coffee and a walk in your favorite park :-). After serveral aeons the output can be found under

<xptools dir>/build/<platform>/<configuration>

The platform is determined automatically, when building on Linux it is Linux of course. The configuration defaults to debug_opt. you can specify the configuration when building the tools this way:

make conf=<configuration>

where <configuration> can be one of the following:

  • release
  • release_opt
  • debug
  • debug_opt

the _opt variants are built with -O2 set, the others with -O0. release variants are built with -DDEV=0 set, debug variants with -DDEV=1. To clean the tree you can do:

  • make clean, this just deletes the <xptools dir>/build directory
  • make distclean, this deletes the <xptools dir>/build directory and the built 3rd-party libraries located in <xptools dir>/libs/local

You can also build a single tool, e.g.

conf=release_opt make ObjView

Building on Windows (MS Visual Studio)

The MSVC solution file (.sln) can be found in msvc/xtools_wed/xtools_wed.sln, and it contains a project (xtools_wed) that builds WorldEditor.  The MSVC project uses the standard debug and release targets.

Building on OS X (X-Code)

The X-Code project for almost all of the scenery tools is called SceneryTools.xcodeproj and is in the root of the tree. There is one target for each of the scenery tools – simply pick a configuration, target, and build.

Important: before building on the Mac for the first time, you must build the libraries as described above.

The X-Code scenery tools project defines 4 build types. Besides debug and release (the normal configurations), there are two more:

  • DebugOpt is a debug build with the optimizer on. For work with CGAL-based tools (like MeshTool), this means inlining is enabled (which makes the tools a lot faster), but the debug assertion checks are on, to catch program errors.
  • Phone is a debug build with PHONE defined to 1 – this turns on a few special hooks and options that LR uses internally for deploying content to the iphone.

Contribute Patches

Working like in the old days

If you do not have the time or motivation to work on the Scenery Tools on a regular basis and just want to submit a minor fix or feature enhancement, you’ll probably decide to download a snapshot tarball and code against that tree. In this case just create a patch with a diff tool and submit it via email. When using GNU diff, you would do something like this:

diff -Naur <directory with original tree> <directory with fixed tree> > my-fancy-fixes.patch

Using git

I won’t describe basic tasks with git here, since git’s documentation evolved to a very professional state over the time. Have a look at:

The above mentioned repository does have a master branch which reflects the current state of development, as well as release branches for patching binary tools releases. Starting a new development branch based on a commit, usually the most recent, in master is probably a good idea to avoid merge conflicts when pulling from upstream with git pull. I encourage the use of git rebase after pulling new objects and updating the master branch to have your local development branch up-to-date, except you have people pulling from your repository. In this case merging the master branch back to your development branch is a better choice because rebasing causes the creation of new commits with new sha1-sums which might distort the workflow of users pulling from your repository. Once you’ve finished your work and you think it’s time to submit your changes, you can create a series of patches from your development branch with git format-patch and send them via email either manually or automatically using git send-email. Or you can, preferably, file a pull-request via email, naming your repository URL and the branch name you want me to pull from. This will only work if you can publish your repository somewhere on the internet of course.

Sothis is taking all my credit

Once you’ve submitted a series of patches, and when they get accepted, they will appear sooner or later in the master branch (yes they do! :-)). You will notice that the committer and author will be the user ‘sothis’, i.e. me. This is, of course, because i want to get all the credit. Seriously, it is, like mentioned earlier, because of the underlying infrastructure. As long as the main repository is managed by CVS, there is no way around this (except someone else can point me to a solution, please let me know). I have to export patches manually to CVS with git cvsexportcommit, while the git repository gets updated automatically by git cvsimport. Therefore all accepted patches will appear like as if they are written by me. I will add a note in the commit message from whom the patch originally came of course.

Mailing List/Contact

We are using the x-plane-dev yahoo group/mailing list to discuss scenery tools coding; to subscribe, send mail to

x-plane-dev-subscribe@yahoogroups.com