CMake

What's this about?

We recently (June 2008) switched to CMake for building the Second Life viewer.

What does CMake buy us?

CMake has the advantage of generating per-platform build files for us. On Linux, it will generate Makefiles and KDevelop project files. On OS X, it will generate Makefiles and Xcode project files. On Windows, it will generate Makefiles (for nmake) and Visual Studio project files.

All of the "smarts" stay in the CMake files, so there's just one authoritative source of build knowledge. This means that people can use the development environment they prefer without having to worry so much about breaking other people's builds. Because CMake files are plain text, merging is easy, as is maintaining experimental patches.

CMake tells your build system how to rebuild its input files when it detects changes to CMake's configuration files. This means that you only need to run cmake once. After that, make or your IDE should keep the CMake files and its own project files in sync for you.

What have we tested?

We've performed test build-and-run cycles on the following platforms.

Linux	Debian sarge	i386	gcc 3.4	prebuilt libraries
Linux	Debian sarge	i386	gcc 4.1.2	prebuilt libraries
Linux	Fedora 9	x86_64	gcc 4.3.0	standalone
Linux	Ubuntu 7.04	i686	gcc 4.1.2	prebuilt libraries
Linux	Ubuntu 8.04	i686	gcc 4.2.3	standalone
Mac OS X	10.5 (Leopard)	i386	Xcode 3.0	prebuilt libraries
Mac OS X	10.5	PowerPC	Xcode 3.0	prebuilt libraries
Windows	XP	i386	VS 2005	prebuilt libraries
Windows	XP	i386	VS 2008	prebuilt libraries

Not every platform has been equally tested, and not every feature is fully functional. Please help us to track problems by reporting any trouble you run into.

Performing a build with CMake

If you want to try a CMake-powered build, it helps to already be familiar with our build process.

First of all, you'll need to download CMake (as of this writing, the latest version is 2.6.2), and install it. On Linux distros, it's usually available as a native package. On Windows and OS X, just use the prebuilt binaries.

Note: There are many known issues with CMake 2.6.0 and 2.6.1 in conjunction with building the Second Life viewer. CMake 2.4.8 is supported, as well as 2.6.2 and beyond.

To start, you'll need:

• The source code, art, and library archives from the Source_downloads page, all extracted to the same directory.
• Fmod 3.75 (not 4.x), and its source files copied to the correct locations (see the Fmod sections of Linux, Mac, Windows).

  (Fmod is the only bit of manual copying needed as of late July 2008; later, this could become automated.)

  • The target directories do not exist until you did the steps in the next section

If you are building on Windows, you will need:

• The Windows Platform SDK. Get the latest version (as of 29 Oct 2008) here: Windows SDK for Windows Server 2008 and .NET Framework 3.5
• DirectX 9.0 SDK. Get the latest version (as of 29 Oct 2008) here: DirectX 9.0 SDK (August 2008)
• Cygwin installed on your system (specifically, make sure that patchutils, flex, and bison (all under "devel") are installed. These packages are NOT selected for install by default.). Cygwin
• Python installed on your system (If you are using a version of Python newer than v2.5, you may need to change the Python.cmake file. See discussion for details (this change was necessary as of 1.21-r99587 source branch). ) Python Download
• Verify that Cygwin, CMake, and Python are in the windows "PATH".
• If applicable/desired, Quicktime SDK for Windows installed

NOTE: DO NOT use the Cygwin version of CMake or Python. The Build will fail. (CMake specifically excludes the Cygwin version of Python, in the 'Python.cmake' file) Run the 'develop.py' script from a windows command prompt in the \linden\indra\ directory.

Configuring your tree

Before you first run a build, you'll need to configure things.

There's a develop.py script that will do this for you. Simply run it from the command line and it will create a reasonably sane default configuration. Note: You need to cd into the intra subdirectory for it to work.

• if you're using VisualStudio 2005, use "python develop.py -G VC80". See Discussion for more info.

• if you're using VisualStudio 2008, use "python develop.py -G VC90".

NOTE: The above commands will configure a "non-standalone" version of the source code tree. This means that the required third party library packages (as built by Linden Lab) will be downloaded during the CMake process.

TODO : "How to configure a standalone source code tree." (probably as a link to a new page, as this is a significantly involved task and will break up the flow of this document)

In the CMake world, we keep source and object files separate. The develop.py script will create and populate a build directory for you.

On Linux, this will be named viewer-linux-i686.

On OS X, it will be build-darwin-universal.

On Windows, it will be 'build-vc71' (VS 2003) , 'build-vc80' (VS 2005) or 'build-vc90' (VS 2008).

What to expect

Running develop.py does not actually start a build. It just generates the makefiles, project files, or whatever that you'll need. After you're done, you'll have a top-level makefile or project file in your build directory. Run make or load it into your IDE, and away you go!

In principle, your build should run to completion. If you run into any problems, please report them. Better yet, if you can fix them and supply patches, we'd be thrilled! Please follow the usual contribution agreement guidelines.

Where's the built viewer?

The location of the newly built viewer depends on your platform. On Linux, it'll be here:

build-linux-i686/newview/packaged

On OS X, it will be here by default:

build-darwin-universal/newview/RelWithDebInfo/Second Life.app

If you change the kind of build you use, the intermediate directory will also change, e.g. from RelWithDebInfo to Release.

On Windows, the built viewer ought to run from VS2005.

Prebuilt libraries vs. standalone builds

While many users will want to use the prebuilt libraries that we provide, we're also interested in making life as easy as possible for packagers who want to use their platform's native libraries.

If you run ccmake, you should see a STANDALONE option that determines whether the build will use your system's libraries or our prepackaged ones. Flipping this to ON should be all you need to do to perform a packager-friendly build.

For standalone builds, we'd really like to beef up the checks for system libraries so that for example cmake will fail if a required library (such as OpenJPEG) isn't installed. We welcome all patches that help out with this.

• Compiling standalone builds on Linux Ubuntu

Patching guidelines

We welcome your patches! We can't test on every permutation of platform, compiler, IDE, and libraries, so if you have problems that you can fix, please contribute your fixes and we'll do our best to ensure that you only have to fix problems once.

If you're sending patches in, please follow a few simple guidelines:

• Use regular context diffs. If you're attaching a patch, please try to make sure it has Unix line endings and pathnames, not Windows.
• Follow the existing coding style in the CMake files. I don't like code shouting at me, so prefer lowercase letters.
• One logical change per patch.
• Use spaces for indentation, not tabs.

Please also see the (user contributed) instructions at http://wiki.secondlife.com/wiki/User:Michelle2_Zenovka/cmake