Difference between revisions of "CMake"
| Line 17: | Line 17: | ||
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. | 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 instructs your build system in how to rebuild its input files when it detects changes to CMake's configuration files. This means that you only need to run <code>cmake</code> once. After that, <code>make</code> or your IDE should keep the CMake files and its own project files in sync for you. | |||
== What are the disadvantages of CMake? == | == What are the disadvantages of CMake? == | ||
| Line 24: | Line 26: | ||
The documentation is poor. This is a much bigger problem for new projects than ones that already have CMake in place. We've already survived the early "WTF?" stages; it's much easier to hack on existing CMake files than it is to create new ones from scratch. | The documentation is poor. This is a much bigger problem for new projects than ones that already have CMake in place. We've already survived the early "WTF?" stages; it's much easier to hack on existing CMake files than it is to create new ones from scratch. | ||
= | = Performing a build with CMake = | ||
First of all, you'll need to [http://www.cmake.org/HTML/Download.html download CMake], and install it. On Linux distros, it's usually available as a native package. On Windows and OS X, just use the prebuilt binaries. | First of all, you'll need to [http://www.cmake.org/HTML/Download.html download CMake], and install it. On Linux distros, it's usually available as a native package. On Windows and OS X, just use the prebuilt binaries. | ||
| Line 48: | Line 50: | ||
This does <i>not</i> run 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 <code>make</code> or load it into your IDE, and away you go! | This does <i>not</i> run 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 <code>make</code> 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! | |||
== 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 <code>ccmake</code>, you should see a <code>STANDALONE</code> option that determines whether the build will use your system's libraries or our prepackaged ones. Flipping this to <code>TRUE</code> 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 <code>cmake</code> will fail if a required library (such as OpenJPEG) isn't installed. We welcome all patches that help out with this. | |||
== Patching guidelines == | |||
If you're sending patches in, please follow a few simple guidelines: | |||
* Use regular context diffs. | |||
* 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. | |||
I'd like to try an experiment with the development process. Instead of creating JIRA issues, please send your patches to <code>bos at lindenlab dot com</code>, and CC <code>sldev</code>. Inline patches are preferred over attachments, unless your email client trashes white space (as many do). | |||
Revision as of 16:20, 10 December 2007
Building the viewer using CMake
We're experimenting with the possibility of switching to CMake for building the Second Life viewer.
== Why change what we're doing?
Our current build system is unsatisfactory in several respects.
Within Linden Lab, we use different tools on each platform: scons on Linux, Visual Studio 2003 on Windows, and XCode on OS X.
- Any time we add or rename a source file, updating the various build instructions is painful.
- We can't easily stay up to date with newer tools, such as Visual Studio 2005 or 2008.
- Merging changes to the project files used by XCode and Visual Studio is a nightmare.
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 instructs your build system in 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 are the disadvantages of CMake?
The CMake configuration language is weird and ugly.
The documentation is poor. This is a much bigger problem for new projects than ones that already have CMake in place. We've already survived the early "WTF?" stages; it's much easier to hack on existing CMake files than it is to create new ones from scratch.
Performing a build with CMake
First of all, you'll need to download CMake, and install it. On Linux distros, it's usually available as a native package. On Windows and OS X, just use the prebuilt binaries.
These are Linux/Mac instructions. The Windows instructions are presumably similar, except you wave your mouse around instead of running commands.
Check out a copy of the viewer cmake branch:
svn co http://svn.secondlife.com/svn/linden/branches/cmake
Create a build directory:
mkdir mybuild
Go into your build directory, and run cmake or ccmake in there, pointing it at the parent directory. If you want to generate a makefile for use by GNU Make, the defaults will work.
cmake ..
If you're on a Mac and want to use XCode, use this command instead.
cmake -G XCode ..
This does not run 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!
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 TRUE 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.
Patching guidelines
If you're sending patches in, please follow a few simple guidelines:
- Use regular context diffs.
- 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.
I'd like to try an experiment with the development process. Instead of creating JIRA issues, please send your patches to bos at lindenlab dot com, and CC sldev. Inline patches are preferred over attachments, unless your email client trashes white space (as many do).