<?php
  $site_root = "../";
  $page_title = "In-Source Builds";
  include 'header.inc';
?>

<h2>Why won't CMake let me do an in-source build?</h2>

<p>This is a restriction of the KDE buildsystem. This document will try and explain why this 
restriction was put in place.</p>

<p>First of all, let's make sure we can understand each other. An "in-source" build is referring to
building your software so that all the intermediate files are placed in the same directories
as your source code. If you're not familiar with building KDE, this is the equivalent of calling
"configure" in the same directory it is located:</p>

<code>
[/home/me/source_dir$] ./configure
</code>

<p>If you are familiar with building KDE, it is equivalent to:</p>

<code>
[/home/me/source_dir$] cmake .
</code>

<p>An out-of-source build is referring to creating a new directory so that your intermediate
files are placed there instead. Commonly, this directory is called "build" but a specific
name is not required. You then call the build software from this directory.</p>

<code>
[/home/me/source_dir$] mkdir build<br>
[/home/me/source_dir$] cd build<br>
[/home/me/source_dir/build$] ../configure<br>
</code>

<p>Or in KDE:</p>

<code>
[/home/me/source_dir$] mkdir build<br>
[/home/me/source_dir$] cd build<br>
[/home/me/source_dir/build$] cmake ..<br>
</code>

<p>The KDE buildsystem does not allow an in-source build in any of the main modules, and will display
an error if you attempt to do so. The reason for this restriction has to do with the complexity of
the buildsystem and the common errors that arise because of that.</p>

<p>The KDE build system is a very complex, multistage process, and it will create many, many intermediate
files as it compiles the libraries and programs that make up KDE. For example:</p>

<ul>
<li>CMake creates its own intermediate files, as well as the files that control the entirety of the rest of the build process.</li>
<li>The Qt API uses a metacompiler named "moc" that will create intermediate files from the source code.</li>
<li>The KDE UI building system will create source code that will be compiled with the projects.</li>
<li>Auxiliary scripts are made to allow developers to do testing outside of the main KDE directory.</li>
</ul>

<p>When all is said and done, it's not unusual for a KDE application to have more 2 or 3 times the
number of intermediate files than it originally had source files! With all these extra files lying around,
things can get confusing even for an experienced developer. Mistakes are bound to happen, and this where
the problems begin to occur. Some of these problems are listed here:</p>

<ul>
<li>CMake creates lots of intermediate files while it does its job, and confusion over how to properly
interact with it has caused many problems in the past. A usual culprit is the existence of stale
CMake files in the root source directory, and if a developer decides to switch between in-source and
out-of-source without properly cleaning things up first then all sorts of things can go haywire.</li>
<li>Sometimes developers will try and commit an intermediate file into the svn repository. This is a
<b>very</b> common mistake and usually annoys experienced developers and embarrasses the newer ones.</li>
<li>When attempting to clean a source tree to restart a build from scratch it's very easy to miss things
and leave stale intermediate files lying around, which further complicates whatever problem was occurring
in the first place. KDE provides some special scripts to help in these cases (cvs-clean and svn-clean), but
new developers (the ones most likely to be having build problems) are not always aware of these scripts,
whereas "rm -rf build" is straightforward and available on every distro. Even worse: a frustrated developer
may decide to "rm -rf" his entire source directory and re-checkout from svn, which creates an unnecessary burden
on the svn server, and runs the risk of deleting uncommitted work!</li>
<li>Supporting both methods of builds requires the buildsystem maintainers to make sure that every change
works with both build types. Occasionally, mistakes are made and one build or the other is broken.</li>
</ul>

<p>The restriction against in-source builds is meant to minimize the occurrences of all of these problems by
keeping all the source and intermediate files separate. It reduces the amount of effort needed to maintain
the buildsystem (which is an area few people truly desire to work with) and it reduces the variables
encountered when troubleshooting someone else's (or your own) build problems. All in all, this is just a
way to try and ensure that in most circumstances your KDE build is going to <i>Just Work.</i></p>

<p>Of course, restricting developers to out-of-source builds is not a perfect solution, but during the KDE4 development
process (when the restriction was first implemented) it did vastly reduce a number of the issues described above.
In a perfect world KDE would like to support in-source, out-of-source, and any other kind of build
anyone can come up with, but the real world usually has lots of factors that make things much more
difficult. This is one such case where the downsides of enabling multiple build types vastly outweighed
the advantages.</p>

<?php include 'footer.inc'; ?>