Difference between revisions of "Getting Started/Build/kdesrc-build"

Jump to: navigation, search
(Bump kdesvn-build version a bit.)
m (Introduction to kdesrc-build: Add link)
(55 intermediate revisions by 16 users not shown)
Line 1: Line 1:
== Building KDE using the kdesvn-build tool ==
 
  
=== Introduction to kdesvn-build ===
 
  
[http://kdesvn-build.kde.org/ kdesvn-build] is a tool to allow users and developers to easily download and build the latest versions of KDE (3.5 and 4) from the KDE source code repository.  It automates the following tasks and more:
+
{{note|It is possible to build KDE 3 using older versions of kdesrc-build, but this is not described here.}}
 +
 
 +
== Building KDE using the kdesrc-build tool ==
 +
 
 +
=== Introduction to kdesrc-build ===
 +
 
 +
[http://kdesrc-build.kde.org/ kdesrc-build] (formerly kdesvn-build) is a tool to allow users and developers to easily download and build the latest versions of the  [http://www.kde.org/ KDE Software Compilation] (KDE SC) from the KDE source code repositories.  It automates the following tasks and more:
  
 
* Performing the initial checkout.
 
* Performing the initial checkout.
 
* Handling updates for modules that are already checked out.
 
* Handling updates for modules that are already checked out.
 
* Setting up the build system for the module.
 
* Setting up the build system for the module.
* For KDE 3 modules, setting up for the [http://wiki.kde.org/tiki-index.php?page=unsermake unsermake] build tool.
 
 
* Performing the build and install.
 
* Performing the build and install.
 +
* Specifying your CMake options or configure flags (so you don't have to remember them every time).
 +
* Logging build errors so you can review them easier for troubleshooting.
 +
 +
It is not the end-all for your troubles building KDE, [[../Troubleshooting|Troubleshooting]] still applies. Many errors that occur using other methods occur here too, you read the log files that are stored for you.
  
=== Why use kdesvn-build? ===
+
=== Why use kdesrc-build? ===
  
So why use kdesvn-build?  There are several reasons you may like to use it:
+
So why use kdesrc-build?  There are several reasons you may like to use it:
  
# Less manual editing of commands.  Instead of having to remember to add the correct options to the cmake command line or configure command, you can setup the options once and then kdesvn-build will use your settings from then on, saving you from wasting time because you forgot to enable a setting.
+
# Less manual editing of commands.  Instead of having to remember to add the correct options to the cmake command line or configure command, you can setup the options once and then kdesrc-build will use your settings from then on, saving you from wasting time because you forgot to enable a setting.
# Command logging to help debug build failures.  kdesvn-build logs all command outputs to a file.  This has several advantages:
+
# Command logging to help debug build failures.  kdesrc-build logs all command outputs to a file.  This has several advantages:
 
## When a module fails to build, you already have the error output saved to disk, ready to be viewed and compared with other error messages to aid debugging.
 
## When a module fails to build, you already have the error output saved to disk, ready to be viewed and compared with other error messages to aid debugging.
## Quieter output.  Even with the unsermake and cmake tools, the output of a KDE module build can be extensive.  kdesvn-build does not show the details of a module build (but will show the progress), instead an overview of the build process is displayed.
+
## Quieter output.  Even with CMake, the output of Qt or a KDE SC module build can be extensive.  kdesrc-build does not show the details of a module build (but will show the progress), instead an overview of the build process is displayed.
# It's just easier.  Instead of having to learn how to use the Subversion command and how to setup a KDE build system, you can specify what modules you want build, where to install them to, and any other options you want and then have kdesvn-build actually do it, even while you're away from the computer or busy doing other things.
+
# It's just easier.  Instead of having to learn how to use the Subversion and git tools, and how to setup a KDE build system, you can specify what modules you want build, where to install them to, and any other options you want and then have kdesrc-build actually do it, even while you're away from the computer or busy doing other things.
# It's easy to step in yourself.  kdesvn-build uses a standard source and build directory layout, and calls the same commands you would.  So kdesvn-build will not interfere with you performing the build or editing the source yourself if you so choose.
+
# It's easy to step in yourself.  kdesrc-build uses a standard source and build directory layout, and calls the same commands you would.  So kdesrc-build will not interfere with you performing the build or editing the source yourself if you so choose.
  
 
=== Setting up ===
 
=== Setting up ===
  
 
==== Prerequisites ====
 
==== Prerequisites ====
kdesvn-build is fairly easy to install and setup, but you also need to have the right software installed to build KDE. The requirements to build KDE are available as follows:
+
kdesrc-build is fairly easy to install and setup, but you also need to have the right software installed to build KDE. The requirements to build KDE are available as follows:
  
* KDE 3: [[../Stable_Version#Requirements|KDE 3 Requirements]]
+
* KDE 4: [[../Requirements|KDE 4 Requirements]]
* KDE 4: [[../KDE4#Required Software|KDE 4 Requirements]]
+
  
In addition to those listed requirements, kdesvn-build requires the Perl scripting platform to be installed. It is installed by default with most distributions, and is required to build KDE 3. kdesvn-build is designed to work with 5.6 or later but has only been tested on Perl 5.8.
+
kdesrc-build requires Perl 5.10 or higher. It is installed by default with most distributions, and is included in the link above. Check your version of Perl with:
 +
<syntaxhighlight lang="text">perl -v</syntaxhighlight>
  
{{note|kdesvn-build is developed on a Linux system, but it should work on the various BSD distributions as well (although GNU tools may be required).}}
+
You will also need [https://github.com/gisle/libwww-perl#readme libwww] (sometimes called LWP), a collection of Perl Internet-related modules, and [http://search.cpan.org/~toddr/XML-Parser/Parser.pm XML::Parser] to support the XML-based KDE Project database. Both of these modules are extremely common and should be available in your distribution's packager manager.
  
==== Download and install kdesvn-build ====
+
kdesrc-build itself may be packaged on your distribution, which allows you to easily install its dependencies as well. ([http://packages.debian.org/unstable/main/kdesrc-build Debian provides packages] and a Fedora package is pending a fix to the kdesrc-build sources).
Once your system is setup to be able to compile KDE, you can download kdesvn-build from its website, [http://kdesvn-build.kde.org/ kdesvn-build.kde.org].  The file you download will contain (at least) the kdesvn-build script and a sample configuration file.  Installing kdesvn-build is as simple as saving the file and making it executable.  If you'd like, you can move it to a directory in your PATH, however for this example we'll put it into the KDE source directory that we use (~/kdesvn)
+
  
<pre>mkdir -p ~/kdesvn
+
{{note|kdesrc-build is developed on a Linux system, but it should work on the various BSD distributions as well (although GNU tools may be required).}}
cd ~/kdesvn
+
tar xjvf ~/path/to/kdesvn-build-1.8.tar.bz2
+
cp kdesvn-build-1.8/kdesvn-build .
+
</pre>
+
  
Alternatively, the newest kdesvn-build script (and sample config file) can be pulled directly from svn:
+
==== Download and install kdesrc-build ====
<pre>mkdir -p ~/kdesvn
+
Once your system is setup to be able to compile the KDE SC, you can download kdesrc-build from its website, [http://kdesrc-build.kde.org/ kdesrc-build.kde.org].  The file you download will contain (at least) the kdesrc-build script and a sample configuration file.  Installing kdesrc-build is as simple as saving the file and making it executable.  If you'd like, you can move it to a directory in your PATH, however for this example we'll put it into the KDE source directory that we use (~/kdesrc)
cd ~/kdesvn
+
 
svn cat svn://anonsvn.kde.org/home/kde/trunk/KDE/kdesdk/scripts/kdesvn-build > kdesvn-build
+
<syntaxhighlight lang="bash">
svn cat svn://anonsvn.kde.org/home/kde/trunk/KDE/kdesdk/scripts/kdesvn-buildrc-sample > ~/.kdesvn-buildrc
+
mkdir -p ~/kdesrc &&
chmod +x kdesvn-build
+
cd ~/kdesrc &&
</pre>
+
tar xjvf ~/path/to/kdesrc-build-1.14.1.tar.bz2 &&
 +
cp kdesrc-build-1.14.1/kdesrc-build .
 +
</syntaxhighlight>
 +
 
 +
Alternatively, the newest kdesrc-build script (and sample config file) can be pulled directly from git:
 +
<syntaxhighlight lang="bash">
 +
git clone git://anongit.kde.org/kdesrc-build.git ~/kdesrc
 +
</syntaxhighlight>
  
 
==== Setup the configuration ====
 
==== Setup the configuration ====
Now you should setup your configuration. For the most part the defaults in the included kdesvn-buildrc-sample should be sufficient.
+
Now you should [[Getting Started/Build/kdesrc-build-config|setup your configuration]]. For the most part the defaults in the included kdesrc-buildrc-sample should be sufficient.
  
<pre>cp ~/kdesvn/kdesvn-build-1.4/kdesvn-buildrc-sample ~/.kdesvn-buildrc
+
<syntaxhighlight lang="bash">
# Now edit the ~/.kdesvn-buildrc</pre>
+
cp ~/kdesrc/kdesrc-build-1.14.1/kdesrc-buildrc-sample ~/.kdesrc-buildrc
 +
</syntaxhighlight>
  
{{tip|Note that the config file's name begins with a leading ., making it a hidden file. You may need to show hidden files in Konqueror to find the configuration file to edit it. Or you can edit the sample before copying it to ~/.kdesvn-buildrc.}}
+
Now you can start kdesrc-build using the commands
 +
cd
 +
  ./kdesrc-build
  
While editing the sample file you'll want to take note of the use-stable-kde option.  If you want to build the latest KDE, make sure it is either commented or explicitly set to false.  To build KDE 3.5 by default, uncomment it and set it to true.
+
Now you can edit the configuration file ~/.kdesrc-buildrc
  
Also, make sure that the modules you'll want to build are included. You'll want the following at the least:
+
{{tip|Note that the config file's name begins with a leading ., making it a hidden file. You may need to show hidden files in Dolphin or Konqueror to find the configuration file to edit it. Or, you can edit the sample before copying it to ~/.kdesrc-buildrc.}}
  
* KDE 3: qt-copy, arts, kdesupport, kdelibs, kdebase
+
Also, make sure that the modules you'll want to build are included. You'll want the following at the least:
* KDE 4: qt-copy, kdesupport, kdelibs, kdepimlibs, kdebase
+
  
Modules are built in the order they appear in your ~/.kdesvn-buildrc, so the first module should be qt-copy, kdelibs should be before any other KDE module, and so on.
+
* qt-copy, kdesupport, kdelibs, kdepimlibs, kdebase
 +
 
 +
Modules are built in the order they appear in your ~/.kdesrc-buildrc, so the first module should be qt-copy, kdelibs should be before any other KDE SC module, and so on.
  
 
{{note|The sample configuration file does include these modules by default, you won't need to make many changes unless you'd like to add some modules to the build by uncommenting them.}}
 
{{note|The sample configuration file does include these modules by default, you won't need to make many changes unless you'd like to add some modules to the build by uncommenting them.}}
  
You may want to enable the make-install-prefix option if you are installing KDE or qt-copy to a directory not in your home directory.  make-install-prefix allows you to run su or sudo during the make install process so you can install files as root, or set certain programs as setuid (for instance, this is required for the KDE screensaver locking program).
+
You may want to enable the make-install-prefix option if you are installing KDE SC or Qt to a directory that is not in your home directory.  make-install-prefix allows you to run su or sudo during the make install process so you can install files as root, or set certain programs to execute with higher permissions (This is required for certain programs to execute properly).
  
 
<pre>module kdelibs
 
<pre>module kdelibs
Line 82: Line 95:
 
If a module you'd like to build isn't already present, simply add
 
If a module you'd like to build isn't already present, simply add
  
<pre>module <module-name>
+
<pre>module &lt;module-name&gt;
end module</pre> at the end of the ~/.kdesvn-buildrc.
+
end module</pre> at the end of the ~/.kdesrc-buildrc. &lt;module-name&gt; would be whatever the module is called in the software repository (for instance, kdemultimedia).
  
==== Useful kdesvn-build commands ====
+
===== Git-based modules =====
kdesvn-build is driven from the command line, so here's a guide to some of the more useful command line options:
+
 
 +
Some KDE projects use the "git" source-control software instead of Subversion (as part of an ongoing migration to git). This includes software like Amarok and Konversation.
 +
 
 +
To build these modules in kdesrc-build, you just need to add a couple of lines to the module configuration. For example, konversation is developed in the Git repository at [https://projects.kde.org/projects/extragear/network/konversation/repository]. So you would just add a module (you can pick whatever name for the module you like, as long as it's not already used):
 +
 
 +
<pre>module konversation
 +
    repository git://anongit.kde.org/konversation
 +
    branch master
 +
end module</pre>
 +
 
 +
In this case I selected the "master" branch since that is the default git branch.
 +
 
 +
Now whenever you build konversation, kdesrc-build will use git instead of Subversion.
 +
 
 +
==== Useful kdesrc-build commands ====
 +
kdesrc-build is driven from the command line, so here's a guide to some of the more useful command line options:
  
 
<table cellpadding="2">
 
<table cellpadding="2">
Line 93: Line 121:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>[http://kdesvn-build.kde.org/documentation/cmdline.html#cmdline-pretend --pretend] (Short form -p)</td>
+
<td><tt><span style="white-space:nowrap;">[http://kdesrc-build.kde.org/documentation/cmdline.html#cmdline-pretend --pretend]</span></tt> (Short&nbsp;form&nbsp;<tt><span style="white-space:nowrap;">-p</span></tt>)</td>
<td>This option is like a dry run.  kdesvn-build will process the options and its configuration like normal, and run through the build as normal, but instead of downloading or running the build will instead output what kdesvn-build would have done.  You should always run with -p before running kdesvn-build to make sure it is doing what you expect.</td>
+
<td>This option is like a dry run.  kdesrc-build will process the options and its configuration like normal, and run through the build as normal, but instead of downloading or running the build will instead output what kdesrc-build would have done.  You should always run with -p before running kdesrc-build to make sure it is doing what you expect.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>[http://kdesvn-build.kde.org/documentation/cmdline.html#cmdline-no-svn --no-svn]</td><td>This option skips the source code update step.  This is useful if you're running kdesvn-build again soon after the last update and don't want to wait to find out there were no changes.</td>
+
<td><tt>[http://kdesrc-build.kde.org/documentation/cmdline.html#cmdline-no-svn --no-svn]</tt> (Alt. form <tt>--no-src</tt>)</td><td>This option skips the source code update step.  This is useful if you're running kdesrc-build again soon after the last update and don't want to wait to find out there were no changes.</td>
 
</tr>
 
</tr>
 
<tr>
 
<tr>
<td>[http://kdesvn-build.kde.org/documentation/cmdline.html#cmdline-refresh-build --refresh-build]</td><td>This option causes kdesvn-build to delete the current build information for the given modules and start building them again from scratch.  This option takes a lot of time but gives the best chance of a successful build.</td>
+
<td><tt>[http://kdesrc-build.kde.org/documentation/cmdline.html#cmdline-refresh-build --refresh-build]</tt></td><td>This option causes kdesrc-build to delete the current build information for the given modules and start building them again from scratch.  This option takes a lot of time but gives the best chance of a successful build.</td>
</tr>
+
<tr>
+
<td>[http://kdesvn-build.kde.org/documentation/cmdline.html#cmdline-reconfigure --reconfigure]</td><td>This option runs the configure or cmake command again before starting the build, which is sometimes required when the build system configuration changes from the source update.  The build directory is left intact which can save some time rebuilding but risks a failed build.</td>
+
 
</tr>
 
</tr>
 
</table>
 
</table>
  
Any other non-option arguments on the command line are assumed to be modules to build (and are built in the order provided on the command line).  If no modules are specified, all of the modules listed in the ~/.kdesvn-buildrc (except those with manual-build enabled) are built in the order listed in the file.
+
Any other non-option arguments on the command line are assumed to be modules to build (and are built in the order provided on the command line).  If no modules are specified, all of the modules listed in the ~/.kdesrc-buildrc are built in the order listed in the file.
  
 
== Build ==
 
== Build ==
We're almost there.  If you're happy with your settings then it's time to test out kdesvn-build.  In theory things are as simple as running kdesvn-build and then coming back later. ;)
+
We're almost there.  If you're happy with your settings then it's time to test out kdesrc-build.  In theory things are as simple as running kdesrc-build and then coming back later. ;)
  
<pre>cd ~/kdesvn
+
<syntaxhighlight lang="bash">
./kdesvn-build</pre>
+
cd ~/kdesrc
 +
./kdesrc-build
 +
</syntaxhighlight>
  
 
You may want to test by building qt-copy first however.
 
You may want to test by building qt-copy first however.
  
<pre>cd ~/kdesvn
+
<syntaxhighlight lang="bash">
./kdesvn-build qt-copy</pre>
+
cd ~/kdesrc
 +
./kdesrc-build qt-copy
 +
</syntaxhighlight>
  
{{tip|If you have the GNU screen program available then you should definitely use it to run kdesvn-build, as you can detach your kdesvn-build session and logout while kdesvn-build is still running.}}
+
{{tip|If you have the [http://www.gnu.org/software/screen/ GNU screen] program available then you should definitely use it to run kdesrc-build, as you can detach your kdesrc-build session and logout while kdesrc-build is still running.}}
  
If the build failed (kdesvn-build will error out with a nice bright red error message) then there are several possibilities:
+
If the build failed (kdesrc-build will error out with a nice bright red error message) then there are several possibilities:
  
 
# You are missing a key piece of required software (such as a development library)
 
# You are missing a key piece of required software (such as a development library)
# The KDE code being compiled is broken in some fashion to where it won't build.  This is common on Mondays for KDE 4 code when kdelibs has source or binary-incompatible changes committed.
+
# The KDE SC code being compiled is broken in some fashion to where it won't build.  This is commonly due to newly committed code that worked on the developer's machine, or occasionally on Mondays (when incompatible changes are permitted to kdelibs).
# kdesvn-build is not setup properly.  You may be trying to install to a directory that you have no permissions to access for instance, or you may have specified a qtdir that does not exist.
+
# kdesrc-build is not setup properly.  You may be trying to install to a directory that you have no permissions to access for instance, or you may have specified a system qtdir that does not exist.
# The module may depend on a newer version of qt-copy or kdelibs (or other module).  In this case you'll have to run kdesvn-build to update the out-of-date module first.
+
# The module may depend on a newer version of qt-copy or kdelibs (or other module).  In this case you'll have to run kdesrc-build to update the out-of-date module first.
  
How do you find out what the error was?  The output of the failing command will be in the log directory.  By default, all log output is in the {{path|log}} subdirectory of the KDE source directory.  The log directory is laid out like this: log/date-run/module/output-file.log.  To simplify finding the appropriate file, there are a couple of symlinks created:
+
How do you find out what the error was?  The output of the failing command will be in the log directory.  By default, all log output is in the {{path|log}} subdirectory of the KDE SC source directory.  The log directory is laid out like this: {{path|log/date-run/module/output-file.log}}.  To simplify finding the appropriate file, there are a couple of symlinks created:
  
log/latest always has the debugging output for the last time kdesvn-build was run (--pretend doesn't count toward this)
+
{{path|log/latest}} always has the debugging output for the last time kdesrc-build was run (--pretend doesn't count toward this)
log/latest/<module>/error.log has the debugging output for the command that caused a module build to fail.
+
{{path|log/latest/&lt;module&gt;/error.log}} has the debugging output for the command that caused a module build to fail.
  
 
For instance if qt-copy just failed to build you could read the output like this:
 
For instance if qt-copy just failed to build you could read the output like this:
  
<pre>cd ~/kdesvn
+
<syntaxhighlight lang="bash">
kwrite log/latest/qt-copy/error.log</pre>
+
cd ~/kderc
 +
kwrite log/latest/qt-copy/error.log
 +
</syntaxhighlight>
  
 
Replace kwrite with your preferred editor.  Hopefully the output can guide you to resolving the problem.  For instance, if the failure is a cmake output saying you're missing a library, install that library and try again. ;)  For link errors you can try running a --refresh-build on the module (or if that doesn't work, required libraries like qt-copy and kdelibs).
 
Replace kwrite with your preferred editor.  Hopefully the output can guide you to resolving the problem.  For instance, if the failure is a cmake output saying you're missing a library, install that library and try again. ;)  For link errors you can try running a --refresh-build on the module (or if that doesn't work, required libraries like qt-copy and kdelibs).
Line 145: Line 176:
 
== Running KDE ==
 
== Running KDE ==
  
Assuming you got enough of the modules to build and install to have a working KDE installation, you'll still need to setup your environment correctly to run it.  kdesvn-build doesn't help you out here (yet), but the instructions at [[../../Increased_Productivity_in_KDE4_with_Scripts/.bashrc|the .bashrc wiki page]] apply just as well, except that you'll need to set the environment variables to the settings that are in your ~/.kdesvn-buildrc.
+
Assuming you got enough of the modules to build and install to have a working KDE installation, you'll still need to setup your environment correctly to run it.  kdesrc-build doesn't help you out here (yet), so you should follow the instructions [[Getting_Started/Using_an_IDE_with_KDE4|here]].
  
For the KDEDIRS and KDEDIR variable use the setting of the "prefix" option (in the global section).
+
Make sure to use the same paths as the ones you defined in .kdesrc-buildrc: for the KDEDIRS and KDEDIR variable use the setting of the "prefix" option (in the global section). For the QTDIR variable use the setting of the "qtdir" option.
For the QTDIR variable use the setting of the "qtdir" option.
+
 
+
{{tip|When copying settings over to the .bashrc, change any ~'s in the paths to $HOME, as the ~ character is not expanded correctly in the .bashrc.}}
+
 
+
Once your .bashrc is setup logout and log back in again and then you should be able to run your new KDE installation.
+
  
 
== Keeping KDE up to date ==
 
== Keeping KDE up to date ==
  
Keeping your KDE installation up to date is as simple as running kdesvn-build again.  Every kdesvn-build has these phases:
+
Keeping your KDE installation up to date is as simple as running kdesrc-build again.  Every kdesrc-build has these phases:
  
 
# Update the source code for all modules being built.
 
# Update the source code for all modules being built.
Line 163: Line 189:
 
Old build directories are not deleted by default, so the build after a small update will not normally take as long as the initial build of a module.  This is called "incremental make".  However it may be necessary at times to perform a full rebuild due to inconsistencies between the build directory configuation and changes to the source directory.  You can use the --refresh-build option to force a full rebuild.
 
Old build directories are not deleted by default, so the build after a small update will not normally take as long as the initial build of a module.  This is called "incremental make".  However it may be necessary at times to perform a full rebuild due to inconsistencies between the build directory configuation and changes to the source directory.  You can use the --refresh-build option to force a full rebuild.
  
For more information on how to take advantage of kdesvn-build, see the [http://kdesvn-build.kde.org/documentation online documentation] for kdesvn-build, which describes all of the module options and command line options available for kdesvn-build and gives tips on how to perform various useful tasks.
+
For more information on how to take advantage of kdesrc-build, see the [http://kdesrc-build.kde.org/documentation online documentation] for kdesrc-build, which describes all of the module options and command line options available for kdesrc-build and gives tips on how to perform various useful tasks.
  
 
If you have any questions that are not answered please feel free to add them under the Discussion entry for this page and hopefully someone will be able to get the answer.
 
If you have any questions that are not answered please feel free to add them under the Discussion entry for this page and hopefully someone will be able to get the answer.
 +
 +
 +
= See also =
 +
* To browse the KDE Subversion repository, use [http://websvn.kde.org/trunk/KDE WebSVN].
 +
* To browse any of the various KDE projects using git, you can go to [http://projects.kde.org KDE Git Projects] or to [http://gitweb.kde.org KDE Git Web].
 +
* The Nokia Qt toolkit used by KDE can be browsed at [http://qt.gitorious.org/qt Nokia's Qt version on gitorious].
  
 
[[Category:Build_KDE]]
 
[[Category:Build_KDE]]
 
[[Category:Tutorial]]
 
[[Category:Tutorial]]

Revision as of 04:26, 23 December 2012


noframe
 
Note
It is possible to build KDE 3 using older versions of kdesrc-build, but this is not described here.

Contents

Building KDE using the kdesrc-build tool

Introduction to kdesrc-build

kdesrc-build (formerly kdesvn-build) is a tool to allow users and developers to easily download and build the latest versions of the KDE Software Compilation (KDE SC) from the KDE source code repositories. It automates the following tasks and more:

  • Performing the initial checkout.
  • Handling updates for modules that are already checked out.
  • Setting up the build system for the module.
  • Performing the build and install.
  • Specifying your CMake options or configure flags (so you don't have to remember them every time).
  • Logging build errors so you can review them easier for troubleshooting.

It is not the end-all for your troubles building KDE, Troubleshooting still applies. Many errors that occur using other methods occur here too, you read the log files that are stored for you.

Why use kdesrc-build?

So why use kdesrc-build? There are several reasons you may like to use it:

  1. Less manual editing of commands. Instead of having to remember to add the correct options to the cmake command line or configure command, you can setup the options once and then kdesrc-build will use your settings from then on, saving you from wasting time because you forgot to enable a setting.
  2. Command logging to help debug build failures. kdesrc-build logs all command outputs to a file. This has several advantages:
    1. When a module fails to build, you already have the error output saved to disk, ready to be viewed and compared with other error messages to aid debugging.
    2. Quieter output. Even with CMake, the output of Qt or a KDE SC module build can be extensive. kdesrc-build does not show the details of a module build (but will show the progress), instead an overview of the build process is displayed.
  3. It's just easier. Instead of having to learn how to use the Subversion and git tools, and how to setup a KDE build system, you can specify what modules you want build, where to install them to, and any other options you want and then have kdesrc-build actually do it, even while you're away from the computer or busy doing other things.
  4. It's easy to step in yourself. kdesrc-build uses a standard source and build directory layout, and calls the same commands you would. So kdesrc-build will not interfere with you performing the build or editing the source yourself if you so choose.

Setting up

Prerequisites

kdesrc-build is fairly easy to install and setup, but you also need to have the right software installed to build KDE. The requirements to build KDE are available as follows:

kdesrc-build requires Perl 5.10 or higher. It is installed by default with most distributions, and is included in the link above. Check your version of Perl with:

perl -v

You will also need libwww (sometimes called LWP), a collection of Perl Internet-related modules, and XML::Parser to support the XML-based KDE Project database. Both of these modules are extremely common and should be available in your distribution's packager manager.

kdesrc-build itself may be packaged on your distribution, which allows you to easily install its dependencies as well. (Debian provides packages and a Fedora package is pending a fix to the kdesrc-build sources).

noframe
 
Note
kdesrc-build is developed on a Linux system, but it should work on the various BSD distributions as well (although GNU tools may be required).

Download and install kdesrc-build

Once your system is setup to be able to compile the KDE SC, you can download kdesrc-build from its website, kdesrc-build.kde.org. The file you download will contain (at least) the kdesrc-build script and a sample configuration file. Installing kdesrc-build is as simple as saving the file and making it executable. If you'd like, you can move it to a directory in your PATH, however for this example we'll put it into the KDE source directory that we use (~/kdesrc)

mkdir -p ~/kdesrc &&
cd ~/kdesrc &&
tar xjvf ~/path/to/kdesrc-build-1.14.1.tar.bz2 &&
cp kdesrc-build-1.14.1/kdesrc-build .

Alternatively, the newest kdesrc-build script (and sample config file) can be pulled directly from git:

git clone git://anongit.kde.org/kdesrc-build.git ~/kdesrc

Setup the configuration

Now you should setup your configuration. For the most part the defaults in the included kdesrc-buildrc-sample should be sufficient.

cp ~/kdesrc/kdesrc-build-1.14.1/kdesrc-buildrc-sample ~/.kdesrc-buildrc

Now you can start kdesrc-build using the commands

cd
./kdesrc-build

Now you can edit the configuration file ~/.kdesrc-buildrc

Ktip.png
 
Tip
Note that the config file's name begins with a leading ., making it a hidden file. You may need to show hidden files in Dolphin or Konqueror to find the configuration file to edit it. Or, you can edit the sample before copying it to ~/.kdesrc-buildrc.


Also, make sure that the modules you'll want to build are included. You'll want the following at the least:

  • qt-copy, kdesupport, kdelibs, kdepimlibs, kdebase

Modules are built in the order they appear in your ~/.kdesrc-buildrc, so the first module should be qt-copy, kdelibs should be before any other KDE SC module, and so on.

noframe
 
Note
The sample configuration file does include these modules by default, you won't need to make many changes unless you'd like to add some modules to the build by uncommenting them.

You may want to enable the make-install-prefix option if you are installing KDE SC or Qt to a directory that is not in your home directory. make-install-prefix allows you to run su or sudo during the make install process so you can install files as root, or set certain programs to execute with higher permissions (This is required for certain programs to execute properly).

module kdelibs
  make-install-prefix sudo -S # sudo with no stdin
end module

module kdebase
  make-install-prefix sudo -S
end module

If a module you'd like to build isn't already present, simply add

module <module-name>
end module
at the end of the ~/.kdesrc-buildrc. <module-name> would be whatever the module is called in the software repository (for instance, kdemultimedia).
Git-based modules

Some KDE projects use the "git" source-control software instead of Subversion (as part of an ongoing migration to git). This includes software like Amarok and Konversation.

To build these modules in kdesrc-build, you just need to add a couple of lines to the module configuration. For example, konversation is developed in the Git repository at [1]. So you would just add a module (you can pick whatever name for the module you like, as long as it's not already used):

module konversation
    repository git://anongit.kde.org/konversation
    branch master
end module

In this case I selected the "master" branch since that is the default git branch.

Now whenever you build konversation, kdesrc-build will use git instead of Subversion.

Useful kdesrc-build commands

kdesrc-build is driven from the command line, so here's a guide to some of the more useful command line options:

OptionEffect
--pretend (Short form -p) This option is like a dry run. kdesrc-build will process the options and its configuration like normal, and run through the build as normal, but instead of downloading or running the build will instead output what kdesrc-build would have done. You should always run with -p before running kdesrc-build to make sure it is doing what you expect.
--no-svn (Alt. form --no-src)This option skips the source code update step. This is useful if you're running kdesrc-build again soon after the last update and don't want to wait to find out there were no changes.
--refresh-buildThis option causes kdesrc-build to delete the current build information for the given modules and start building them again from scratch. This option takes a lot of time but gives the best chance of a successful build.

Any other non-option arguments on the command line are assumed to be modules to build (and are built in the order provided on the command line). If no modules are specified, all of the modules listed in the ~/.kdesrc-buildrc are built in the order listed in the file.

Build

We're almost there. If you're happy with your settings then it's time to test out kdesrc-build. In theory things are as simple as running kdesrc-build and then coming back later. ;)

cd ~/kdesrc
./kdesrc-build

You may want to test by building qt-copy first however.

cd ~/kdesrc
./kdesrc-build qt-copy
Ktip.png
 
Tip
If you have the GNU screen program available then you should definitely use it to run kdesrc-build, as you can detach your kdesrc-build session and logout while kdesrc-build is still running.


If the build failed (kdesrc-build will error out with a nice bright red error message) then there are several possibilities:

  1. You are missing a key piece of required software (such as a development library)
  2. The KDE SC code being compiled is broken in some fashion to where it won't build. This is commonly due to newly committed code that worked on the developer's machine, or occasionally on Mondays (when incompatible changes are permitted to kdelibs).
  3. kdesrc-build is not setup properly. You may be trying to install to a directory that you have no permissions to access for instance, or you may have specified a system qtdir that does not exist.
  4. The module may depend on a newer version of qt-copy or kdelibs (or other module). In this case you'll have to run kdesrc-build to update the out-of-date module first.

How do you find out what the error was? The output of the failing command will be in the log directory. By default, all log output is in the log subdirectory of the KDE SC source directory. The log directory is laid out like this: log/date-run/module/output-file.log. To simplify finding the appropriate file, there are a couple of symlinks created:

log/latest always has the debugging output for the last time kdesrc-build was run (--pretend doesn't count toward this) log/latest/<module>/error.log has the debugging output for the command that caused a module build to fail.

For instance if qt-copy just failed to build you could read the output like this:

cd ~/kderc
kwrite log/latest/qt-copy/error.log

Replace kwrite with your preferred editor. Hopefully the output can guide you to resolving the problem. For instance, if the failure is a cmake output saying you're missing a library, install that library and try again. ;) For link errors you can try running a --refresh-build on the module (or if that doesn't work, required libraries like qt-copy and kdelibs).

If you're stumped by the error you may want to wait a day and try updating again, and hope that the reason for the error has been fixed. You can also try mailing the kde-devel mailing list to see if others know about the problem or have had similar issues.

Running KDE

Assuming you got enough of the modules to build and install to have a working KDE installation, you'll still need to setup your environment correctly to run it. kdesrc-build doesn't help you out here (yet), so you should follow the instructions here.

Make sure to use the same paths as the ones you defined in .kdesrc-buildrc: for the KDEDIRS and KDEDIR variable use the setting of the "prefix" option (in the global section). For the QTDIR variable use the setting of the "qtdir" option.

Keeping KDE up to date

Keeping your KDE installation up to date is as simple as running kdesrc-build again. Every kdesrc-build has these phases:

  1. Update the source code for all modules being built.
  2. Build and then install all the modules.

Old build directories are not deleted by default, so the build after a small update will not normally take as long as the initial build of a module. This is called "incremental make". However it may be necessary at times to perform a full rebuild due to inconsistencies between the build directory configuation and changes to the source directory. You can use the --refresh-build option to force a full rebuild.

For more information on how to take advantage of kdesrc-build, see the online documentation for kdesrc-build, which describes all of the module options and command line options available for kdesrc-build and gives tips on how to perform various useful tasks.

If you have any questions that are not answered please feel free to add them under the Discussion entry for this page and hopefully someone will be able to get the answer.


See also


KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal