Subversion"> kdesvn-build"> ]> MichaelPyne

michael.pyne@kdemail.net

CarlosWoelz

carloswoelz@imap-mail.com

2005 Michael Pyne 2005 Carlos Woelz &FDLNotice; 2005-06-18 0.98 The &kdesvn-build; is a Perl script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository. KDE kdesdk SVN Subversion KDE development &kdesvn-build; is a Perl script to help users install &kde; from &svn;. You may also want to consider the kde-build script include with &kde;'s kdesdk module. Here we document the &kdesvn-build; configuration file syntax and options, its command line options, features, and an overview of all necessary steps required to build &kde; from source, including the steps which you should perform using other tools, or in other words, steps that are not automatically performed by the &kdesvn-build; script. In this chapter, we show how to use the &kdesvn-build; to checkout modules from the &kde; repository and build them. We also provide a basic explanation of the &kde; &svn; structure and the steps you have to perform before running the script. All topics present in this chapter are covered with even more detail in the Building &kde; from Source Step by Step Guide, at the &kde; Quality Team Website. If you are compiling KDE for the first time, it is a good idea to read it, or consult it as a reference source. You will find detailed information about packaging tools and requirements, common compilation pitfalls and strategies and information about running your new &kde; installation. It is recommended that you download and build &kde; using a user account. If you already have &kde; packages installed, the best choice would be to create a different (dedicated) user to build and run the new &kde;. The advantage of building &kde; with a dedicated user is you can not break the base system, and you will always have a way to comfortably work when things go wrong. Later, you can do a root installation if you wish. This document does not cover a root installation. If you are performing a system wide install, you probably already know what you are doing anyway. Before using the &kdesvn-build; script (or any other building strategy) you must install the development tools and libraries needed for &kde;. You need the Qt library, version 3.3.0 or greater, Automake 1.8, Autoconf 2.5X (better if >=2.57 as a bug was reported with lower versions), the subversion (svn) client, the gcc compiler with C++ support, libxml2, openssl, libbz2, and many more (for a complete list, visit the KDE Compilation Requirements). You can usually get those tools packaged for your system from your distribution or vendor. Some of these packages are divided into libs, programs or utilities and development packages. You will need at least the program or library and its development package. If in doubt, install all. The libraries you need will change depending on the modules you intend to build, as each module has its own requirements. The Building &kde; from Source Step by Step Guide has more details about the specific tools and techniques used to install and find the required software. You probably already have a version of the &kdesvn-build; script installed in your system. &kdesvn-build;requires you to create a configuration file, named .kdesvn-buildrc. This file should be installed on the home folder (~/), and contain all configuration data required for the script to run, like configuration options, compiling options, location of the sources, the destination of the installation (prefix), the modules that should be built, &etc;. The default configuration data is provided by the kdesvn-buildrc-sample file. You can find more information about the syntax of the configuration file in and in . A good way to get the latest version is to browse the kdesdk/scripts page at the websvn.kde.org website. You will see a list of the files available in the kdesdk/scripts directory in the &kde; &svn; repository. Click the &kdesvn-build; link and download the latest version of the script. Do the same for the kdesvn-buildrc-sample file. Make the script executable, and be sure it is in your path. To use the script, you must have a file in your home directory called .kdesvn-buildrc, which sets the general options and sets the modules you would like to download and build. Use the kdesvn-buildrc-sample file as a template, setting global options, and the modules you want to build. Select the server used to check out from &svn;, by setting the svn-server global option. The default is the anonymous &svn; repository, svn://anonsvn.kde.org/, but change it if you have a &kde; &svn; account, or if there is a mirror close to you. Pay close attention to the kdedir and qtdir global variables, as the first sets where your &kde; build is going to be installed, (by default to ~/kde), and the second where (and if) your qt library is going to be built and installed, (by default to ~/kdesvn/build/qt-copy). You will need to know the kdedir and qtdir location later, to set up the environment variables that are necessary to run your new installation. Check if the listed modules are in fact the modules you want to build. The default options from the kdesvn-buildrc-sample file should be enough to get a fairly complete &kde; installation. Save the resulting as .kdesvn-buildrc in your home folder. If you wish to fine tune your .kdesvn-buildrc, consult for detailed information about all configuration options. Now you are ready to run the script. From a terminal window, log in to the user you are using to compile &kde; and execute the script: %su - devel-username %kdesvn-build Now, the script should start downloading the sources and compiling them. It is unlikely that you will succeed in the first time you compile &kde;. Do not despair! Check the log files to see if you are missing some tools or development packages (the location of the log files is set by the log-dir variable in the configuration file). Sometimes, the main development branch get very unstable and hard to build, especially when a development freeze is close. Be patient. You can find more common examples of things that can go wrong and their solutions, as well as general tips and strategies to build &kde; in the Building &kde; from Source Step by Step Guide. Assuming you are using a dedicated user to build &kde;, and you already have an installed &kde; version, running your new &kde; may be a bit tricky, as the new &kde; has to take precedence over the old. Change the environment variables to make sure it does. Open or create the .bash_profile file in the home directory with your favorite editor, and add to the end of the file: KDEDIR=(path to kdedir) KDEDIRS=$KDEDIR PATH=$KDEDIR/bin:$QTDIR/bin:$PATH LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH export KDEDIRS PATH LD_LIBRARY_PATH If you are building the qt-copy module, add instead: QTDIR=(path to qtdir) KDEDIR=(path to kdedir) KDEDIRS=$KDEDIR PATH=$KDEDIR/bin:$QTDIR/bin:$PATH MANPATH=$QTDIR/doc/man:$MANPATH LD_LIBRARY_PATH=$KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH export QTDIR KDEDIRS PATH MANPATH LD_LIBRARY_PATH If you are not using a dedicated user, set a different $KDEHOME for your new environment in your .bash_profile: export KDEHOME="${HOME}/.kde-svn" # Create it if needed [ ! -e ~/.kde-svn ] && mkdir ~/.kde-svn If later your menu is empty or too crowded with applications from your distribution, you may have to set the xdg environment variables in your .bash_profile: XDG_CONFIG_DIRS="/etc/xdg" XDG_DATA_DIRS="${KDEDIR}/share:/usr/share" export XDG_CONFIG_DIRS XDG_DATA_DIRS Now that we are done with the you have to make sure that the right startkde script is going to be used: Open the .xinitrc text file (or .xsession, depending on the distribution) from the home directory, or create it if necessary. Add the line: exec ${KDEDIR}/bin/startkde Now start your fresh &kde;: in BSD and Linux systems with virtual terminal support, Ctrl+Alt+F1...F12 keystroke combinations are used to switch to Virtual Console 1 through 12. This allows you to run more than one desktop environment at the same time. The fist six are text terminals and the following six are graphical displays. If when you boot you are presented to the graphical display manager instead, you can use the new KDE environment, even if it is not listed as an option. Press Crtl + Alt + F2, and you will be presented to a text terminal. Log in using the dedicated user and type: startx -- :1 You can run the KDE from sources and the old KDE at the same time! Log in using your regular user, start the stable KDE desktop. Press Crtl + Alt + F2 (or F1, F3, etc..), and you will be presented to a text terminal. Log in using the dedicated user and type "startx -- :1". You can go back to the regular user by pressing Crtl + Alt + F6 (Or F7, F8, etc... Try them out! One of them is the right one.) To return to KDE from sources, press Crtl + Alt + F7 (or F6, F8,etc..). Now you can switch between your KDE versions, and test the new one knowing you can quickly return to the safety of the stable KDE desktop. &kdesvn-build; features include: Automatically checks out or updates modules from &svn;, as appropriate. Times the build process for modules. Automatically tries to rebuild modules that were using incremental make, which is prone to failure after certain kinds of commits. Can resume a previous script, or start the build process from a particular module. Comes built-in with a sane set of default options appropriate for building a base &kde; single-user installation from the anonymous &svn; repository. Comes with Unsermake support. Tilde-expansion for your configuration options. For example, you can specify: qtdir ~/kdesvn/build/qt-copy Configurable build, source, and logging directories Automatically sets up a build system, with the source directory not the same as the build directory, in order to keep the source directory pristine. The exception is qt-copy, which is not designed to be built like that (unless you would like to test the qt with a separate build directory hack). You can specify global options to apply to every module to check out, and you can specify options to apply to individual modules as well. Since the autotools sometimes get out of sync with changes to the source tree, you can force a rebuild of a module by creating a file called .refresh-me in the build directory of the module in question, or by running &kdesvn-build; with the --refresh-build option. You can specify various environment values to be used during the build, including KDEDIR, QTDIR, DO_NOT_COMPILE, and CXXFLAGS. Command logging. Logs are dated and numbered so that you always have a log of a script run. Also, a special symlink called latest is created to always point to the most recent log entry in the log directory. If you are using a user build of &kde; instead of a system build (for which you must be root to install), you can use the script to install for you. I haven not audited this code, and it makes ample use of the system() call, so I would not recommend running it as root at this point. You can use make-install-prefix to prefix the make install command line with a separate command, which is useful for sudo. You can use the apidox option to automatically build and install the API documentation for some modules. You can check out only a portion of a &kde; &svn; module. For example, you could check out only the taglib from kdesupport, or only K3B from extragear/multimedia. The script will automatically pull in kde-common if necessary to make the build work. You can pretend to do the operations. If you pass --pretend or -p on the command line, the script will give a very verbose description of the commands it is about to execute, without actually executing it. Support for checking out specific branches of &svn; modules. This work still needs to be completed, but you already select the branch you want to build using the module-base-path configuration option. Things that &kdesvn-build; does NOT do: Find the fastest &kde; &svn; mirror. There is not even a list shipped with the script at this point, although the default server should work fine. Brush your teeth. You should remember to do that yourself. The script probably is not bug-free. Sorry. To use the script, you must have a file in your home directory called .kdesvn-buildrc, which describes the modules you would like to download and build. It starts with the global options, specified like the following: global option-name option-value [...] end global It is then followed by one or more module sections, specified like the following: module module-name option-name option-value [...] end module module-name must be a module from the &kde; &svn; repository (for example, kdelibs or kdebase). Some options override global options, some add to global options, and some global options simply can't be overridden. The following is an alphabetized list of options you can use. Click on the option to find out more about it. If one is not documented, please e-mail the authors using the address you can find above. apidox, to build API Documentation apply-qt-patches, to enhance qt-copy binpath, to set the PATH variable. branch, to checkout from a branch instead of /trunk. build-dir, to set the directory to build in. checkout-only, to checkout only parts of a module. colorful-output to add color to the script output. configure-flags to define what flags to configure a module with. cxxflags to define the CXXFLAGS variable. dest-dir to change the directory name for a module. disable-agent-check, to keep kdesvn-build from checking on ssh-agent's status. do-not-compile, to mark directories to skip building. inst-apps, to only build and install some directories. install-after-build, to avoid installing after the build process. kdedir, to set the directory to install KDE to. libpath, to set the LD_LIBRARY_PATH variable. make-install-prefix, to run a helper program (like sudo) during make install. make-options, to pass options to the make program. manual-build, to avoid building the module automatically. manual-update, to avoid doing anything to the module automatically. module-base-path, to change where to download the module from (useful for branches and tags). niceness, to change the CPU priority. no-rebuild-on-fail, to avoid running make again if it fails. qtdir, to set the path to Qt. set-env, to set an environment variable. source-dir, to change where to download the source code to. stop-on-failure, to make kdesvn-build stop as soon as a failure is encountered. svn-server, to change the server the sources are downloaded from. use-qt-builddir-hack, to give Qt a separate build directory from its source like KDE. use-unsermake, to use the advanced unsermake build system. Here is a table of the various options, and some comments on them. Any option which overrides the global option will override a command line setting as well. Option-name Module -> Global Behavior Notes apidox Overrides global Set this option to true in order to have &kdesvn-build; automatically build and install the API documentation for the module after the normal build/install process. This only works for modules where make apidox does something, including kdelibs, kdebase, and koffice, among others. apply-qt-patches Overrides global This option is only useful for qt-copy. If it is set to a non-zero value, then the apply-patches script in qt-copy will be run prior to building, in order to apply the non-official patches to the qt-copy. Since these patches are normally the reason for using qt-copy instead of a stock Qt, it shouldn't do any harm to enable it. The default is to enable the patches. binpath Can't be overridden Set this option to set the environment variable PATH while building. You can't override this setting in a module option. The default value is /bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin. This environment variable should include the colon-separated paths of your development toolchain. The paths $KDEDIR/bin and $QTDIR/bin are automatically added. You may use the tilde (~) for any paths you add using this option. branch Overrides global Set this option to checkout from a branch of KDE instead of the default of "trunk", where KDE development occurs. For instance, to checkout KDE 3.4 branch, you would set this option to "3.4". Note that some modules use a different branch name. Notably, the required arts module doesn't go by KDE version numbers. The arts that accompanied KDE 3.4 was version 1.4. If kdesvn-build fails to properly download a branch with this option, you may have to manually specify the URL to download from using the override-url option. build-dir Overrides global Use this option to change the directory to contain the built sources. There are three different ways to use it: Relative to the &kde; &svn; source directory (see the source-dir option). This is the default, and the way the script worked up to version v0.61. This mode is selected if you type a directory name that doesn't start with a tilde (~) or a slash (/). The default value is build. Absolute path. If you specify a path that begins with a /, then that path is used directly. For example, /tmp/kde-obj-dir/. Relative to your home directory. If you specify a path that begins with a ~, then the path is used relative to your home directory, analogous to the shell's tilde-expansion. For example, ~/builddir would set the build directory to /home/user-name/builddir. Perhaps surprisingly, this option can be changed per module. checkout-only Overrides global Set this option to checkout &svn; sources piece by piece. The value for this option should be a space separated list of directories to checkout. If you don't include the admin directory, it will automatically be included (if necessary). When checking out piece by piece, the admin directory will be pulled in from kde-common, which is where it exists on the &svn; server. Although this option overrides the global option, be aware that setting this as a global option makes no sense. configure-flags Appends to global option(except for qt-copy) Use this option to specify what flags to pass to ./configure when creating the build system for the module. When this is used as a global-option, it is applied to all modules that this script builds. qt-copy uses a much different set of configure options than the rest of &kde;, so this option overrides the global settings when applied to qt-copy. colorful-output Can't be overridden Set this option to false to disable the colorful output of &kdesvn-build;. This option defaults to true. Note that &kdesvn-build; won't output the color codes to anything but a terminal (such as xterm, &konsole;, or the normal Linux console). cxxflags Appends to global option Use this option to specify what flags to pass to ./configure as the CXXFLAGS when creating the build system for the module. This option is specified here instead of with configure-flags because this option will also set the environment variable CXXFLAGS during the build process. dest-dir Overrides global Use this option to change the name a module is given on disk. For example, if your module was extragear/network, you could rename it to extragear-network using this option. disable-agent-check Can't be overridden Normally if you're using SSH to download the Subversion sources (such as if you're using the svn+ssh protocol), kdesvn-build will try and make sure that if you're using ssh-agent, it is actually managing some SSH identities. This is to try and prevent SSH from asking for your passphrase for every module. You can disable this check by setting disable-agent-check to true. do-not-compile Overrides global Use this option to set the DO_NOT_COMPILE environment variable prior to running the configure script. According to the &kde; Developer FAQ, this should cause any toplevel directory you pass to not be built. The directories should be space-separated. Note that the sources to the programs will still be downloaded. You can use the checkout-only directive to choose directories that you want to check out. email-address Can't be overridden Set this option to the e-mail address kdesvn-build should send from should it ever need to send e-mail. You do not need to worry about this if you don't use any feature which send e-mail. (They are all disabled by default). Currently only email-on-compile-error needs this option. email-on-compile-error Can't be overridden You can set this option to the email address to send a report to when a module fails to build. kdesvn-build will wait until all the modules are done and collate all of the results in the report. The report is only sent if a module fails to build. Please see the email-address option to set the address kdesvn-build should send from, since the default is usually not what you want. inst-apps Overrides global This is the opposite of the do-not-compile option. This option makes it so that only the given toplevel directories are built. The directories should be space-separated. Any changes don't take effect until the next time make -f Makefile.cvs is run, either automatically by the script, or manually by the --refresh-build or --recreate-configure options. Note that the sources to the programs will still be downloaded. You can use the checkout-only directive to choose directories that you want to check out. install-after-build Overrides global This option is used to install the package after it successfully builds. This option is enabled by default. If you want to disable this, you need to set this option to 0 in the configuration file. You can also use the --no-install command line flag. kdedir Can't be overridden This option sets the directory that &kde; will be installed to after it is built. It defaults to ~/kde. If you change this to a directory needing root access, you may want to read about the make-install-prefix option as well. libpath Can't be overridden Set this option to set the environment variable LD_LIBRARY_PATH while building. You can't override this setting in a module option. The default value is blank, but the paths $KDEDIR/lib and $QTDIR/lib are automatically added. You may use the tilde (~) for any paths you add using this option. log-dir Overrides global Use this option to change the directory used to hold the log files generated by the script. This setting can be set on a per-module basis as of version 0.64 or later. make-install-prefix Overrides global Set this variable to a space-separated list, which is interpreted as a command and its options to precede the make install command used to install modules. This is useful for installing packages with sudo for example, but please be careful while dealing with root privileges. make-options Overrides global Set this variable in order to pass command line options to the make command. This is useful for programs such as distcc. distcc allows you to share your compilation work among more than one computer. To use it, you must use the -j option to make. Now you can. According to the docs, 2 * number_of_network_cpus is recommended. I have 1 CPU total, so it would be -j2 in my case. manual-build Overrides global Set the option value to true to keep the build process from attempting to build this module. It will still be kept up-to-date when updating from &svn;. This option is exactly equivalent to the --no-build command line option. manual-update Overrides global Set the option value to true to keep the build process from attempting to update (and by extension, build or install) this module. If you set this option for a module, then you have pretty much commented it out. module-base-path Overrides global Set this option to override &kdesvn-build;'s default directory path to the module in question. This can be used, for example, to pull specific branches or tagged versions of libraries. The &kde; Source Viewer is invaluable in helping to pick the right path. Note that &kdesvn-build; constructs the final path according to the following template: $svn-server/home/kde/$module-base-path/$module-name. The default value is either trunk or trunk/KDE, depending on the modulename. niceness Can't be overridden Set this option to a number between 20 and 0. The higher the number, the lower a priority &kdesvn-build; will set for itself. The default is 10. no-rebuild-on-fail Overrides global Set this option value to true to always prevent &kdesvn-build; from trying to rebuild this module if it should fail an incremental build. Normally &kdesvn-build; will try to rebuild the module from scratch to counteract the effect of a stray &svn; update messing up the build system. override-url Overrides global If you set this option, kdesvn-build will use its value as the URL to pass to Subversion completely unchanged. You should generally use this if you want to download a specific release but kdesvn-build can't figure out what you mean using branch. qtdir Can't be overridden Set this option to set the environment variable QTDIR while building. You can't override this setting in a module option. If you don't specify this option, it defaults to $(source-dir)/build/qt-copy, which uses the qt-copy module included in the &kde; source repository. You may use a tilde (~) to represent your home directory. remove-after-install Overrides global If you are low on hard disk space, you may want to use this option in order to automatically delete the build directory (or both the source and build directories for one-time installs) after the module is successfully installed. Possible values for this option are: none - Do not delete anything (This is the default). builddir - Delete the build directory, but not the source. all - Delete both the source code and build directory. Note that using this option can have a significant detrimental impact on both your bandwidth usage (if you use 'all') and the time taken to compile KDE, since kdesvn-build will be unable to perform incremental builds. set-env Overrides global This option accepts a space-separated set of values, where the first value is the environment variable to set, and the rest of the values is what you want the variable set to. For example, to set the variable RONALD to McDonald, you would put in the appropriate section this command: set-env RONALD McDonald This option is special in that it can be repeated without overriding earlier set-env settings in the same section of the configuration file. This way you can set more than one environment variable per module (or globally). source-dir Can't be overridden This option is used to set the directory on your computer to store the &kde; &svn; sources at. If you don't specify this value, the default is ~/kdesvn. If you do specify this value, use an absolute path name. svn-server Can't be overridden This option is used to set the server used to check out from &svn;. The default is the anonymous &svn; repository, svn://anonsvn.kde.org/ stop-on-failure Overrides global Set this option value to true to cause the script to stop execution after an error occurs during the build or install process. This option is off by default. tag Overrides global Use this option to download a specific release of a module. NOTE: The odds are very good that you DO NOT WANT to use this option. KDE releases are available in tarball form from The KDE FTP site or one of its mirrors. If you are using kdesvn-build because you have having trouble getting a KDE release to build on your distribution, consider using the Konstruct build tool instead, which works from the release tarballs. use-qt-builddir-hack Overrides global Although this option overrides the global option, it only makes sense for qt-copy. Set this option to true to enable the script's experimental srcdir != builddir mode. When enabled, &kdesvn-build; will copy the qt-copy source module to the build directory, and perform builds from there. That means your QTDIR environment variable should be set to $(qt-copy-build-dir)/qt-copy/lib instead. You should also change your qtdir option accordingly. Incremental make should still work in this mode, as the timestamps will be preserved after the copy. If you use the apply-qt-patches option, the patches will be applied in the build directory, not the source directory. This option defaults to true. use-unsermake Overrides global Set this option to true in order to use the experimental unsermake program instead of automake when running the configure script. This can lead to some serious decreases in build time, especially for distributed building systems. This option defaults to true (for most modules). Normally if you use this option kdesvn-build will automatically keep unsermake up-to-date. This may start to get annoying, especially if you are managing unsermake yourself. If this is the case, you can set this option to self, and kdesvn-build will still use unsermake, but will not do anything special to keep it updated. This script doesn't use environment variables. If you need to set environment variables for the build or install process, please see the set-env option. The script accepts the following command-line options: --help only display simple help on this script. --version display the program version. --author display contact information for the author. --color enable colorful output. --no-color disable colorful output. --pretend (or -p) don't actually DO anything, but act like you did. --quiet (or -q) Don't be as noisy with the output. With this switch only the basics are output. --really-quiet Only output warnings and errors. --verbose Be very descriptive about what's going on, and what kdesvn-build is doing. --svn-only only perform the source update. --build-only only perform the build process. --ignore-modules don't include the modules passed on the rest of the command line in the update/build process. --no-svn skip contacting the &svn; server. --no-build skip the build process. --no-install don't automatically install packages after they're built. --debug enables debug mode for the script. Currently this means that all output will be dumped to STDOUT in addition to being logged in the log directory like normal. Also, many functions are much more verbose about what they're doing in debugging mode. --no-rebuild-on-fail don't try and rebuild modules that have failed building from scratch. &kdesvn-build; will never try to do this to a module that already was tried to be built from scratch. --refresh-build recreate the build system and make from scratch. --reconfigure run the configure script again without cleaning the build directory. --recreate-configure run make -f Makefile.cvs again to create the configure script, and continue building as normal. This option implies --reconfigure. --resume which tries to continue building from where the script stopped last time. The script starts building the module after the last module to be compiled last time the script was run, whether or not it succeeded. This option implies --no-svn. You should not specify other module names on the command line. --resume-from which is like --resume, except that you supply the module to start building from as the next parameter on the command line. This option implies --no-svn. You should not specify other module names on the command line. --rc-file which interprets the next command line parameter as the file to read the configuration options from. The default value for this parameter is ~/.kdesvn-buildrc. --prefix=</path/to/kde> which allows you to change the directory that &kde; will be installed to from the command line. This option implies --reconfigure. --build-system-only stop after running make -f Makefile.cvs. The configure script will still need to be run, which &kdesvn-build; will do next time. This lets you prepare all the configure scripts at once so you can view the ./configure --help for each module, and edit your configure-flags accordingly. --install If this is the only command-line option, it tries to install all of the modules contained in successfully-built, except for qt-copy, which doesn't need installation. If command-line options are specified after --install, they are all assumed to be modules to install. --<option-name>= You can use this option to override an option in your configuration file for every module. For instance, to override the log-dir option, you would do: --log-dir=/path/to/dir. --<module-name>,<option-name>= You can use this option to override an option in your configuration file for a specific module. For instance, to override the use-unsermake option for kdemultimedia, you would do: --kdemultimedia,use-unsermake=false. Any other command-line options are assumed to be modules to update and build. Please, don't mix building with installing. &underFDL;