Difference between revisions of "CMake"

From Second Life Wiki
Jump to navigation Jump to search
m
 
(40 intermediate revisions by 14 users not shown)
Line 1: Line 1:
= What's this about? =
CMake is a system for generating per-platform build files.  Visit [http://cmake.org cmake.org] for general information about CMake.


We're experimenting with the possibility of switching to [http://www.cmake.org/ CMake] for building the Second Life viewer.
Linden Lab switched to CMake for building the Second Life viewer (starting with version 1.21); we are currently using version 2.8.10.2


== Why change what we're doing? ==
= Introduction to CMake =


Our current build system is unsatisfactory in several respects.
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.
 
Within Linden Lab, we use different tools on each platform: [http://www.scons.org/ 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.
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 <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.
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 <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 have we tested? ==
We've performed test build-and-run cycles on the following platforms.
{| class="wikitable"
|-
| Linux
| Debian sarge
| i386
| gcc 3.4
| prebuilt libraries
|-
| Linux
| Fedora 8
| x86_64
| gcc 4.1.2
| 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
|}
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 =
= Performing a build with CMake =


If you want to try a CMake-powered build, it helps to already be familiar with our [[Get source and compile | existing build process]].
Our builds are now managed one layer further out then CMake, using [[Autobuild]]; starting there is recommended.


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.
Per platform build instructions for CMake-based builds of the Second Life viewer are available for these platforms:
* [[Microsoft Windows Builds|Microsoft Windows]]
* [[Compiling the viewer (Mac OS X)|Mac OS X]]
* [[Compiling the viewer (Linux)|Linux]]


To get started, check out a copy of the cmake branch from here.
<pre>
svn co http://svn.secondlife.com/svn/linden/branches/cmake-7 linden
</pre>


You'll also need to download the artwork package, and if you're linking against our prebuilt libraries, the archive of those files.  You can find links to the appropriate archives in [http://svn.secondlife.com/svn/linden/branches/cmake-7/doc/asset_urls.txt in SVN].
= Modifying CMake Files =


As with the regular viewer build, unpack the artwork and (if you're using it) the prebuilt libraries on top of your SVN checkout.
== What to modify ==


== Configuring your tree ==
'''TODO'' - discuss structure of CMake files
 
Before you first run a build, you'll need to configure things.  There's an <code>indra/cmake.py</code> script that will do this for you.  Simply run it from the command line and it will create a reasonably sane default configuration.
 
In the CMake world, we're keeping source and object files separate.  The <code>cmake.py</code> script will create and populate a build directory for you.  On Linux, this will be named <code>viewer-linux-i686</code>.  On OS X, it will be <code>build-darwin-i686</code>.  I don't remember the directory name on Windows; sorry.
 
== What to expect ==
 
Running <code>cmake.py</code> does <i>not</i> 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 <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!  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:
<pre>
build-linux-i686/newview/packaged
</pre>
 
On OS X, it will be here by default:
<pre>
build-darwin-i686/newview/RelWithDebInfo/Second Life.app
</pre>
If you change the kind of build you use, the intermediate directory will also change, e.g. from <code>RelWithDebInfo</code> to <code>Release</code>.
 
On Windows, the built viewer ought to be able to run from VS2005.  Our Windows CMake expert is on vacation, so I can't give you more explicit details.
 
= 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>ON</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 =
= Patching guidelines =
Line 114: Line 32:


If you're sending patches in, please follow a few simple guidelines:
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.
* 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.
* One logical change per patch.
* Use spaces for indentation, not tabs.
* Use spaces for indentation, not tabs.


= JIRA issues =
See [[Submitting patches]] for more details.
 
* {{jira|VWR-2871}} Implement CMake for building the viewer
 
= What are some downsides to CMake? =
 
Please note: none of the following caveats is really serious.
 
The CMake configuration language is weird and ugly.
 
The tool has some peculiar inconsistencies: some variables and actions are inherited across files, and others are not.  There's no obvious regularity to these, so you have to bump into them one by one.
 
The documentation is weak, which makes the initial learning process daunting.  The docs are mostly organised as reference documentation that assumes that you already know how to use CMake.  This presents a much bigger problem for new projects who are trying to figure out how to establish themselves than for ones that have already bit the bullet.  We've already worked through the early "WTF?" stages, and it took a lot of effort.
 
* KitWare mentions that they're publishing a new edition of their CMake book approximately this week (early February).  I don't know if they're publishing the content online under an open license, so it's not clear to me yet how practically significant this is if you don't want to spend money on documentation.
 
The good news, if you have no prior CMake experience, is that it's easy to modify existing CMake files, because you can look around at existing examples of how things are structured.
 
= Additional Instructions =


Please also see the (user contributed) instructions at [http://wiki.secondlife.com/wiki/User:Michelle2_Zenovka/cmake http://wiki.secondlife.com/wiki/User:Michelle2_Zenovka/cmake]
[[Category:Open Source Portal]]
[[Category:Compiling viewer]]

Latest revision as of 09:35, 13 February 2013

CMake is a system for generating per-platform build files. Visit cmake.org for general information about CMake.

Linden Lab switched to CMake for building the Second Life viewer (starting with version 1.21); we are currently using version 2.8.10.2

Introduction to CMake

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.

Performing a build with CMake

Our builds are now managed one layer further out then CMake, using Autobuild; starting there is recommended.

Per platform build instructions for CMake-based builds of the Second Life viewer are available for these platforms:


Modifying CMake Files

What to modify

'TODO - discuss structure of CMake files

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:

  • 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.

See Submitting patches for more details.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=CMake&oldid=1176698"