Difference between revisions of "Getting Started/Build/Environment"

Revision as of 10:34, 18 March 2011

Introduction

Configuring your build environment is the single most important step in building KDE. A wrong decision or mistake here could at best mean you have to rebuild everything from scratch again, or at worst break your system KDE rendering your system unusable.

A lot of very important concepts will be discussed and it is important that you understand them before proceeding.

A set of configuration scripts and bash commands are provided as a recommended configuration when building KDE manually. If you use these as provided then your KDE build will be a lot easier and it will be easier for you to find support online. The one disadvantage to these scripts is that they hide important details from you which you may want to learn about, but the two methods are completely interchangeable so once you are comfortable building KDE using the scripts you can learn more by doing everything yourself.

It is recommended that you build KDE using your normal user account. In some circumstances you may want to build using a separate user account, such as if you are a KWin or Plasma developer wishing to test a full KDE session with compositing effects, but for most circumstances a simple way can be found for achieving the same aim while still running using your normal user account (e.g. Nested X using xypher).

Git Configuration

KDE uses Git as its main source repository and revision control software which you need to configure before you can use it in KDE. You can find the recommended Git configuration for KDE on the Git Configuration page.

Path Configuration

This section explains the different paths that need to be configured for building KDE. The following section will demonstrate a simple method for setting up the required paths.

Source Path

The $KDE_SRC path environment variable defines where the KDE Build System can find the source files.

TODO: Decide how to do stable and unstable source branches in parallel. While Git supports having these in a single source clone to save disk space, it is sometimes nice to have separate clones to allow simultaneous parallel builds, and it takes less scripting to achieve. It's also conceptually closer to how svn works so seems preferable during the transition.

Build Path

The $KDE_BUILD path environment variable defines where the KDE Build System will create the build files.

The KDE build system requires that your source and build files be in different directories (aka out-of-source builds). This keeps your source directories clean and simplifies management of your different build files. :

It makes it very easy to rebuild from scratch, you just delete the build directory to remove all the generated files - even old ones that "make clean" wouldn't remove.
It is easier to look at the source files (grep, ls etc.).
It allows multiple build trees with different settings, e.g. debug and release.

While for some simple build scenarios you could just create a "build" directory inside your 'source' directory (e.g. "kde/src/kdelibs/build"), this negates many of the advantages when used with a full KDE build. Instead clearly separate paths are recommended.

For example if we were building kdelibs we could have the following folders:

/home/myuser/kde/src/kdelibs
/home/myuser/kde/build/kdelibs

If you plan to build multiple branches of KDE such as stable and unstable in parallel then you will need to add an extra level to the directory:

/home/myuser/kde/src/master/kdelibs
/home/myuser/kde/src/4.6/kdelibs
/home/myuser/kde/build/master/kdelibs
/home/myuser/kde/build/4.6/kdelibs

Install Path

The $KDEDIR path environment variable defines where the KDE Build System will install KDE.

It is strongly recommended for a development build that you do a user based install and not a root install, i.e. install your KDE build into a separate user folder and not into the system /usr folder. This provides a number of advantages:

Your root/system installed version of KDE is untouched, meaning your normal desktop and applications remain stable and usable even if your development build breaks
You can build and run multiple development versions of KDE at the same time, i.e. a stable branch for bug fixes and an unstable branch for new features
You can use a single alias or bash command to compile/link/install without having to do a su/sudo in the middle
Doing "make" and "make install" as the same user is a lot quicker as the Makefiles are only parsed once.
No root owned files in the build directory
No problems caused by root not having a correctly configured KDE build environment
It makes it very easy to reinstall from scratch, you just delete the install directory to remove all the installed files and rerun the build.

That said, the build instructions provided are completely generic and will work for building a root system install if you configure your environment to do so, i.e. for Linux from Scratch or doing a root install in a virtual machine for testing or packaging purposes.

For the kdelibs example given above we would then have:

/home/myuser/kde/src/master/kdelibs
/home/myuser/kde/src/4.6/kdelibs
/home/myuser/kde/build/master/kdelibs
/home/myuser/kde/build/4.6/kdelibs
/home/myuser/kde/inst/master/kdelibs
/home/myuser/kde/inst/4.6/kdelibs

Home Path

The $KDEHOME path environment variable defines wat directory KDE will treat as your home folder, i.e. for stroing data writing config files to.

For the same reason as the Install Path, it is strongly recommended that you set your KDE Home Path to be different from your normal home folder.

For the kdelibs example given above we would then have:

/home/myuser/kde/src/master/kdelibs
/home/myuser/kde/src/4.6/kdelibs
/home/myuser/kde/build/master/kdelibs
/home/myuser/kde/build/4.6/kdelibs
/home/myuser/kde/inst/master/kdelibs
/home/myuser/kde/inst/4.6/kdelibs
/home/myuser/kde/home/master/kdelibs
/home/myuser/kde/home/4.6/kdelibs

Other Paths

There are a number of other paths that are required, but these can all be automatically derived and created by the config script given below.

Environment Configuration

The example environment configuration script given below is for building KDE against your system Qt under your normal user account with an out-of-source build and installing into a user directory. By changing just four variables you can use the script to configure any KDE build environment you want.

It is recommended you create a separate script for each build environment you require. If you have separate source directories for each build then save the script into the root source directory with the name ".build-config" to allow the bash scripts in the next section to automatically load the config and create the required directories.

If you don't wish to use the bash scripts then you must manually create the required directories and manually execute the config script.

If you are building KDE using a dedicated user to run a full desktop session, then you should put this config into the users ~/.bashrc file.

Sample .build-config file


 KDE4 Build Environment configuration script

 To configure your build environment set LIB_SUFFIX, BASEDIR, BUILDNAME and
 QTDIR as appropriate

 The default values provided are for a master/trunk/unstable build in your own
 user directory using your own build of Qt

 Uncomment if building on a 64 bit system
export LIB_SUFFIX=64

 Set where your base KDE development folder is located, usually ~/kde

export BASEDIR=~/kde

 Give the build a name, e.g. master, 4.6, debug, etc

export BUILDNAME=master

 Set up which Qt to use
 Use the system Qt, adjust path as required

export QTDIR=/usr

 Uncomment to use your own build of qt-kde
export QTDIR=$BASEDIR/inst/master/qt-kde
export PATH=$QTDIR/bin:$PATH
export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
export PKG_CONFIG_PATH=$QTDIR/lib:$PKG_CONFIG_PATH

 Set up the KDE paths

export KDE_SRC=$BASEDIR/src
export KDE_BUILD=$BASEDIR/build
export KDEDIR=$BASEDIR/inst/$BUILDNAME
export KDEDIRS=$KDEDIR
export KDEHOME=$BASEDIR/home/.$BUILDNAME
export KDETMP=/tmp/$BUILDNAME-$USER
export KDEVARTMP=/var/tmp/$BUILDNAME-$USER
mkdir -p $KDETMP
mkdir -p $KDEVARTMP

 Add the KDE plugins to the Qt plugins path

export QT_PLUGIN_PATH=$KDEDIR/lib/kde4/plugins

 Do we really need these?

export KDE4_DBUS_INTERFACES_DIR=$KDEDIR/share/dbus-1/interfaces
export PYTHON_SITE_PACKAGES_DIR=$KDEDIR/lib/python2.6/site-packages/PyKDE4

 Export the standard paths to include KDE

export PATH=$KDEDIR/bin:$PATH
export LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH
export PKG_CONFIG_PATH=$KDEDIR/lib/pkgconfig:$PKG_CONFIG_PATH

 Export the CMake paths so it searches for KDE in the right places

export CMAKE_PREFIX_PATH=$KDEDIR:$CMAKE_PREFIX_PATH
export CMAKE_LIBRARY_PATH=$KDEDIR/lib:$CMAKE_LIBRARY_PATH
export CMAKE_INCLUDE_PATH=$KDEDIR/include:$CMAKE_INCLUDE_PATH

 Unset XDG to avoid seeing KDE files from /usr

unset XDG_DATA_DIRS
unset XDG_CONFIG_DIRS

 Uncomment if you are using Icecream for distributed compiling
export PATH=/opt/icecream/bin:$PATH

 Report what the environment is set to

echo echo "*** Configured KDE Build Environment " $BUILDNAME " ***" echo echo "QTDIR=" $QTDIR echo "KDEDIR=" $KDEDIR echo "PATH=" $PATH echo

Useful Scripts

findup

Save this script in an executable file called "findup" somewhere in your path, usually ~/bin/findup.


!/bin/sh

arg="$1"
if test -z "$arg"; then exit 1; fi
while ! test -f "$arg"; do

cd ..
if test "$PWD" = "/"; then
   exit 1
fi

done

echo $PWD/$arg

.bashrc




 A script to setup some needed variables and functions for KDE 4 development.
 This should normally go in the ~/.bashrc file of your kde development user.


prepend() { [ -d "$2" ] && eval $1=\"$2\$\{$1:+':'\$$1\}\" && export $1 ; }

 This will make the debug output prettier

export KDE_COLOR_DEBUG=1
export QTEST_COLORED=1

 Make
 Tell many scripts how to switch from source dir to build dir:

export OBJ_REPLACEMENT="s#$KDE_SRC#$KDE_BUILD#"

 Use makeobj instead of make, to automatically switch to the build dir.
 If you don't have makeobj, install the package named kdesdk-scripts or
 kdesdk, or check out kdesdk/scripts from svn, or just don't set the alias
 yet.

alias make=makeobj



 A function to easily build the current directory of KDE.

 This builds only the sources in the current ~/{src,build}/KDE subdirectory.
 Usage: cs KDE/kdebase && cmakekde
   will build/rebuild the sources in ~/src/KDE/kdebase


function cmakekde {

   if test -n "$1"; then
       # srcFolder is defined via command line argument
       srcFolder="$1"
   else
       # get srcFolder for current dir
       srcFolder=`pwd | sed -e s,$KDE_BUILD,$KDE_SRC,`
   fi
   # we are in the src folder, change to build directory
   # Alternatively, we could just use makeobj in the commands below...
   current=`pwd`
   if [ "$srcFolder" = "$current" ]; then
       cb
   fi
   # To disable tests, remove -DKDE4_BUILD_TESTS=TRUE
   # To save disk space change "debugfull" to "debug"
   cmake "$srcFolder" \
         -DCMAKE_INSTALL_PREFIX=$KDEDIR \
         -DKDE4_BUILD_TESTS=TRUE \
         -DCMAKE_BUILD_TYPE=debugfull

       # Comment out the following two lines to stop builds waiting after
       # the configuration step, so that the user can check configure output
       echo "Press <ENTER> to continue..."
       read userinput

       # Note: To speed up compiling, change 'make -j2' to 'make -jx',
       #   where x is your number of processors +1
       nice make -j2 && make install
       #Use this line instead if using icecream
       #nice make CC=icecc -j6 && make install
       RETURN=$?
       cs
       return ${RETURN}

}


function cd() {

 if test -z "$1"; then
   builtin cd
 elif test -z "$2"; then
   builtin cd "$1"
 else
   builtin cd "$1" "$2"
 fi
 _f=`findup .build-config`
 if test -n "$_f" -a "$_lastf" != "$_f"; then
   echo "Loading $_f"
   _lastf="$_f"
   source "$_f"
 fi

}





 A function to easily change to the build directory.
 Usage: cb KDE/kdebase
   will change to $KDE_BUILD/KDE/kdebase
 Usage: cb
   will simply go to the build folder if you are currently in a src folder
   Example:
     $ pwd
     /home/user/src/KDE/kdebase
     $ cb && pwd
     /home/user/build/KDE/kdebase


function cb {

       local dest

   # Make sure build directory exists.
   mkdir -p "$KDE_BUILD"

   # command line argument
   if test -n "$1"; then
       cd "$KDE_BUILD/$1"
       return
   fi
   # substitute src dir with build dir
   dest=`pwd | sed -e s,$KDE_SRC,$KDE_BUILD,`
   if test ! -d "$dest"; then
       # build directory does not exist, create
       mkdir -p "$dest"
   fi
   cd "$dest"

}



 Change to the source directory.  Same as cb, except this
 switches to $KDE_SRC instead of $KDE_BUILD.
 Usage: cs KDE/kdebase
   will change to $KDE_SRC/KDE/kdebase
 Usage: cs
   will simply go to the source folder if you are currently in a build folder
   Example:
     $ pwd
     /home/myuser/kde/build/master/KDE/kdebase
     $ cs && pwd
     /home/myuser/kde/src/master/KDE/kdebase


function cs {

       local dest current

   # Make sure source directory exists.
   mkdir -p "$KDE_SRC"

   # command line argument
   if test -n "$1"; then
       cd "$KDE_SRC/$1"
   else
       # substitute build dir with src dir
       dest=`pwd | sed -e s,$KDE_BUILD,$KDE_SRC,`
       current=`pwd`
       if [ "$dest" = "$current" ]; then
           cd "$KDE_SRC"
       else
           cd "$dest"
       fi
   fi

}



 Add autocompletion to cs function


function _cs_scandir
{

       local base ext

   base=$1
   ext=$2
   if [ -d $base ]; then
       for d in `ls $base`; do
           if [ -d $base/$d ]; then
               dirs="$dirs $ext$d/"
           fi
       done
   fi

}
function _cs()
{

   local cur dirs
   _cs_scandir "$KDE_SRC"
   _cs_scandir "$KDE_SRC/KDE" "KDE/"
   COMPREPLY=()
   cur="${COMP_WORDS[COMP_CWORD]}"
   COMPREPLY=( $(compgen -W "${dirs}" -- ${cur}) )

}
complete -F _cs cs


svndiff ()
{

   svn diff "$*" | colordiff | less;

}

@@ Line 11: / Line 11: @@
 == Git Configuration ==
-Add the following to your ~/.gitconfig:
+KDE uses Git as its main source repository and revision control software which you need to configure before you can use it in KDE.  You can find the recommended Git configuration for KDE on the [[Development/Git/Configuration|Git Configuration]] page.
-<code>
-[url "git://anongit.kde.org/"]
-	insteadOf = kde:
-</code>
 == Path Configuration ==