From 425cfe92a330049ac27c82548577932cca15ce0f Mon Sep 17 00:00:00 2001 From: Michael Pyne Date: Fri, 8 Jan 2010 23:46:09 +0000 Subject: [PATCH] Now that trunk is open again, update the kdesvn-build documentation to the latest version present on the kdesvn-build website. CCMAIL:lueck@hube-lueck.de svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=1071901 --- doc/index.docbook | 963 ++++++++++++++++++++++++---------------------- 1 file changed, 501 insertions(+), 462 deletions(-) diff --git a/doc/index.docbook b/doc/index.docbook index fdec40e..7234828 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -1,16 +1,16 @@ + - Kdesvn-build"> - Autoconf'> - Automake'> + kdesvn-build"> BSD'> + Git'> CMake'> Make'> SSH'> + Cron'> Subversion'> Sudo'> URL'> @@ -20,7 +20,6 @@ --> configure-flags'> - apply-qt-patches'> kdedir'> qtdir'> build-dir'> @@ -31,10 +30,7 @@ email-on-compile-error'> colorful-output'> tag'> - apidox'> branch'> - no-rebuild-on-fail'> - inst-apps'> do-not-compile'> checkout-only'> svn-server'> @@ -50,16 +46,10 @@ --nice'> --ignore-modules'> --resume-from'> - --no-rebuild-on-fail'> --reconfigure'> --refresh-build'> ]> - @@ -68,12 +58,12 @@ is konstrukt really working for kde4? MichaelPyne -
michael.pyne@kdemail.net
 - +
mpyne@kde.org
 + CarlosWoelz
carloswoelz@imap-mail.com
 - + @@ -84,6 +74,8 @@ is konstrukt really working for kde4? 2006 2007 2008 +2009 +2010 Michael Pyne @@ -92,14 +84,14 @@ is konstrukt really working for kde4? Carlos Woelz - &FDLNotice; -2009-03-13 -1.8 +2010-01-08 +1.11 -&kdesvn-build; is a script which builds and installs &kde; directly from the sources found in the &kde; &subversion; repository. +&kdesvn-build; is a script which builds and installs &kde; software +directly from the &kde; project's source code repositories. @@ -107,6 +99,8 @@ is konstrukt really working for kde4? kdesdk SVN Subversion +git +gitorious KDE development @@ -116,37 +110,48 @@ is konstrukt really working for kde4? Introduction -&kdesvn-build; is a script to help users install &kde; from its &subversion; source repository. +&kdesvn-build; is a script to help users install &kde; software from its &subversion; and &git; source repositories. + -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. +This guide is an overview to describe the following aspects of &kdesvn-build; +operation: - + +Notable features. +An overview of the steps +required to get started. +The configuration file syntax +and options. +The command line options. + +Also documented are the steps which you should perform using +other tools, (in other words, steps that are not automatically performed by +&kdesvn-build;). + + + Getting Started -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; -&subversion; structure and the steps you have to perform before running the 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; &subversion; 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; 4 from Source, at the -&kde; Techbase site. +Building &kde; 4 from Source article, at the +&kde; TechBase site. 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 @@ -160,14 +165,17 @@ strategies and information about running your new &kde; installation. Setup a new user account -It is recommended that you download and build &kde; using a separate user -account. If you already have &kde; packages installed, the best choice +It is recommended that you use a different user account to build, install, +and run your &kde; software from, since less permissions are required, and +to avoid interfering with your distribution's packages. +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. +Leaving your system &kde; untouched also allows you to have an +emergency fallback in case a compiled &kde; is unstable for whatever reason. + + Later, you can do a system installation if you wish. This document does not cover a system installation. If you are performing a system @@ -182,66 +190,63 @@ in order to prepare and use the system installation correctly. Before using the &kdesvn-build; script (or any other building strategy) you must install the development tools and libraries needed for &kde;. -The complete list of required tools can be found from the -&kde; Compilation -Requirements page. Requirements for the &kde; 4 series may be obtained -from the KDE TechBase. +The complete list of required tools can be found from +the KDE TechBase. Here is a list of some of the things you will need: -If you are building &kde; 3, you will need the GNU Autotools (i.e. &automake; -and &autoconf;). +You will need &cmake;. The required version will vary +depending on what version of &kde; 4 you are building, see TechBase for +specifics. -If you are building &kde; 4, you will need &cmake;. The required -version will vary depending on what version of &kde; 4 you are building, see the -TechBase for specifics. +Also needed is the &subversion; client program, including +support for Secure HTTP (https). To ensure needed support, you can run +svn . If +the output says that it handles the https scheme (for write access to +svn.kde.org) or svn scheme (for readonly access to anonsvn.kde.org) then you +should be set to go. -The &subversion; client program, including support for Secure -HTTP (https). To ensure needed support, you can run -svn . -If the output says that it handles the https scheme (for write access to svn.kde.org) -or svn scheme (for readonly access to anonsvn.kde.org) then you should be -set to go. +If you are building &Qt; or any of the various &kde; modules +that are available from Gitorious +then you will need the Git source control +manager installed as well. -The gcc compiler, with support for C++. -Versions 3.3 or higher are the best supported. - -Be sure to check the &kde; Compilation -Requirements page to make sure that any other needed libraries are -included. +You will need a C++ development environment. GCC 3.4 or +later is recommended. -One exception is the &Qt; library. &kdesvn-build; will normally install a -copy of &Qt; whether you have it installed or not, so it is not necessary for you -to have it. If you do not want to use the &Qt; copy, you need to do these things: - +Most operating system distributions include a method of easily +installing required development tools. Consult the TechBase Getting Started +page's Required Packages from your Distribution section to see +if these instructions are already available. + +One exception to the required libraries is the &Qt; library. +&kdesvn-build; will normally install a copy of &Qt; whether you have it +installed or not, so it is not necessary for you to have it. If you do not want +to use the &Qt; copy, you need to do these things: - Make sure to remove the qt-copy module from your configuration file, as you - will not need it, and having it would add extra time to your build. + Make sure to remove the qt-copy module from your configuration file, as you will not need it, + and having it would add extra time to your build. Change the setting of the qtdir - option in your configuration file to point to your system &Qt;. This is normally - equal to the setting of $QTDIR for your system. + option in your configuration file to + point to your system &Qt;. This is normally equal to the setting of + $QTDIR for your system. If you do not already have &Qt; installed, install it, including any - relevant -dev or -devel packages. You will need at least &Qt; 3.3 if you are - building &kde; 3.5, or &Qt; 4.5 if you are building &kde; 4. - - If you are building &kde; 4 it is highly recommended to use the - qt-copy version of &Qt;, making sure to apply recommended patches (this is - the default setting, controlled by the apply-qt-patches - option). + relevant -dev or -devel packages. You will need at least + &Qt; 4.6 if you are building &kde; 4. @@ -310,7 +315,7 @@ by default installs a useful &kde; installation using very generic installation flags, which may be different from your needs. So it is best to use a configuration file. -The configuration file should be called .kdesvn-buildrc. +The configuration file should be called .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, @@ -358,13 +363,6 @@ The default settings should actually already be appropriate to perform a directories that will be searched for commands. This is exactly the same as the PATH variable in the shell. -use-stable-kde to -change the default version to build of &kde; modules. By default &kdesvn-build; -will build the trunk version of &kde; (currently &kde; 4). If you want to build -the latest stable release of &kde; instead of using your distribution packages -(right now the &kde; 3.5 branch is stable) you would set this option to true. - - kdedir, which changes the destination directory that &kde; is installed to. This defaults to ~/kde, which is a single-user installation. @@ -409,8 +407,7 @@ 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 +$kdesvn-build @@ -429,14 +426,14 @@ it is sufficient to look at ~/kdesvn/log/latest/--reconfigure option after install the +linkend="cmdline-reconfigure">--reconfigure option after installing the missing packages. -Or, if the error appears to be a build error -then it is probably an error with the &kde; source, which will hopefully be -resolved within a few days. If it is not resolved within that time, feel free -to mail the kde-devel@kde.org (subscription may be required first) -in order to report the build failure. +Or, if the error appears to be a build error then it is probably an error +with the &kde; source, which will hopefully be resolved within a few days. If +it is not resolved within that time, feel free to mail the +kde-devel@kde.org mailing list (subscription may be required +first) in order to report the build failure. 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 @@ -688,7 +685,7 @@ linkend="conf-revision">revision is checked out of a module. &kdesvn-build; can automatically switch a source directory to checkout from a different repository, branch, or tag. This happens automatically when you change an option that changes what the repository &url; should be, but you must -use the --svn-only option to let +use the --src-only option to let &kdesvn-build; know that it is acceptable to perform the switch. @@ -698,6 +695,13 @@ module, for those situations where you only need one program from a large module. + +The initial download of some modules can be accelerated by &kdesvn-build;, +which will (if available) automatically download a module snapshot from the +&kde; mirrors and use that to setup the initial checkout. This saves time +and bandwidth for both your system and the &kde; servers. + + For developers: &kdesvn-build; will remind you if you use svn+ssh:// but ssh-agent is @@ -892,7 +896,7 @@ and not under ${log-dir}/latest/kde In each module log directory, you will find a set of files for each operation that &kdesvn-build; performs. If &kdesvn-build; updates a module, -you may see filenames such as svn-co.log (for a +you may see filenames such as svn-co.log (for a module checkout) or svn-up.log (when updating a module that has already been checked out). If the configure command was run, then you would expect to see a configure.log @@ -926,7 +930,10 @@ but is instead at the &konsole; or terminal where you ran &kdesvn-build;. -The Format of .kdesvn-buildrc +Configuring &kdesvn-build; + + +Overview of &kdesvn-build; configuration To use the script, you must have a file in your home directory called @@ -970,7 +977,6 @@ authors using the address you can find above. -apply-qt-patches, to enhance qt-copy. async, to update and build at the same time. binpath, to set the PATH variable. branch, to checkout from a branch instead of /trunk. @@ -983,7 +989,6 @@ authors using the address you can find above. 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. kde-languages, to set the translation packages to download and install. @@ -1002,6 +1007,9 @@ authors using the address you can find above. svn-server, to change the server the sources are downloaded from. + + +Table of available configuration options Here is a table of the various options, and some comments on them. Any @@ -1039,11 +1047,9 @@ for older modules of course. 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 should not -do any harm to enable it. The default is to enable the patches. +This option was removed in kdesvn-build 1.10. To get the same effect, +see and the repository option. @@ -1061,7 +1067,7 @@ to enabling asynchronous mode. To disable, set this option to fals Overrides global Set this option to set the environment variable PATH while building. You cannot override this setting in a module option. The default value is -/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin. This environment +the $PATH that is set when the script starts. This environment variable should include the colon-separated paths of your development toolchain. The paths $KDEDIR/bin and $QTDIR/bin are automatically added. You @@ -1074,14 +1080,14 @@ may use the tilde (~) for any paths you add using this option. 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 does not go by &kde; version numbers. The arts that -accompanied &kde; 3.4 was version 1.4. +For instance, to checkout &kde; 4.4 branch, you would set this option to +4.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. +linkend="conf-module-base-path">module-base-path or override-url options. +Note: This option also works with source modules that use +&git; instead of &subversion;. @@ -1090,23 +1096,27 @@ linkend="conf-override-url">override-url option. 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; &subversion; source directory (see the source-dir option). This is the default, and -the way the script worked up to version 0.61. This mode is selected if you -type a directory name that does not 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. +Relative to the &kde; &subversion; source directory (see the source-dir option). This is the default, +and is selected if you type a directory name that does not 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. @@ -1116,27 +1126,27 @@ Perhaps surprisingly, this option can be changed per module. checkout-only Overrides global -Set this option to checkout &subversion; sources piece by piece. The value -for this option should be a space separated list of directories to checkout. -If you do not 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 &subversion; server. -Although this option overrides the global option, be aware that setting this as -a global option makes no sense. - +Set this option to checkout &subversion; sources piece by piece. The +value for this option should be a space-separated list of directories to +checkout. Although this option overrides the global option, be aware that +setting this as a global option makes no sense. + + +Note that this setting has no effect on &git; modules due to the +operation of the &git; source control system. cmake-options Appends to global options (not applicable to qt-copy) -Use this option to specify what flags to pass to &cmake; 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. When used as a module option, -it is added to the end of the global options. This allows you to specify -common &cmake; options in the global section. +Use this option to specify what flags to pass to &cmake; 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. When used as a module +option, it is added to the end of the global options. This allows you to +specify common &cmake; options in the global section. -This option replaces configure-flags -for all &kde; 4 modules, since they use &cmake; to build. +This option does not apply to qt-copy (which does not use &cmake;). Use +configure-flags instead. Since these options are passed directly to the &cmake; command line, they should be given as they would be typed into &cmake;. For example: @@ -1146,22 +1156,21 @@ should be given as they would be typed into &cmake;. For example: Since this is a hassle, &kdesvn-build; takes pains to ensure that as long as the rest of the options are set correctly, you should be able to leave this -option blank. +option blank. (In other words, required &cmake; parameters +are set for you automatically) configure-flags -Appends to global options (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. - +Overrides global +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. This option +only works for qt-copy. -This option applies to qt-copy and all &kde; 3 modules. &kde; 4 modules use -&cmake;, which is controlled using the cmake-options -option. +To change configuration settings for KDE 4 modules, see +cmake-options. + @@ -1178,8 +1187,8 @@ color codes to anything but a terminal (such as xterm, &konsole;, or the normal 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 +Use this option to specify what flags to use for building the +module. This option is specified here instead of with configure-flags or cmake-options because this option will also @@ -1207,11 +1216,12 @@ or directory separators in the name as this will interfere with any disable-agent-check Cannot be overridden -Normally if you are using &ssh; to download the &subversion; sources (such as -if you are using the svn+ssh protocol), &kdesvn-build; will try and make sure that -if you are using ssh-agent, it is actually managing some &ssh; identities. This is -to try and prevent &ssh; from asking for your pass phrase for every module. You can -disable this check by setting to true. +Normally if you are using &ssh; to download the &subversion; sources +(such as if you are using the svn+ssh protocol), &kdesvn-build; will try and +make sure that if you are using ssh-agent, it is actually managing some &ssh; +identities. This is to try and prevent &ssh; from asking for your pass phrase +for every module. You can disable this check by setting + to true. @@ -1221,9 +1231,6 @@ disable this check by setting to Use this option to select a specific set of directories not to be built in a module (instead of all of them). The directories not to build should be space-separated. -This feature is supported for both &kde; 3 and &kde; 4. KDE 4 support was added in -&kdesvn-build; 1.6.3. - 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. @@ -1237,14 +1244,13 @@ compiling, you would add "do-not-compile juk kscd" to your kdemultimedia setting email-address Cannot 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 do not -use any feature which send e-mail. (They are all disabled by default). +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 +do not use any feature which send e-mail. (They are all disabled by default). Currently only email-on-compile-error -needs this option. - +needs this option. @@ -1268,24 +1274,8 @@ 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 top-level directories are built. The directories should -be space-separated. - -Any changes do not take effect until the next time -make Makefile.cvs is -run, either automatically by the script, or manually by the or options. - - -This option does not yet work with modules built using -the &cmake; build system. - -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. + +This option was removed in version 1.10 @@ -1293,52 +1283,57 @@ 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 - command line flag. +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 command line +flag. kdedir Overrides global -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. +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. kde-languages Cannot be overridden -This option allows you to choose to download and install localization -packages along with &kde;. You might do this if you do not live in the United -States and would like to &kde; translated into your native language. +This option allows you to choose to download and install +localization packages along with &kde;. You might do this if you do not live in +the United States and would like to &kde; translated into your native +language. To use this option, set it to a space-separated list of languages to -install. Each language has a language code associated with it, which you +install. Each language has a language code associated with it, which you can look up at this page: http://i18n.kde.org/teams/. -It is alright to choose only one language. By default, none are downloaded, -which means &kde; will display in American English. +It is alright to choose only one language. By default, none are +downloaded, which means &kde; will display in American English. For instance, to choose to install French, you would set the option to -something like: fr. -You would still need to use &systemsettings; in order to choose the -French language, however. +something like: +fr. You would still need to use +&systemsettings; in order to choose the French language, however. libpath Overrides global -Set this option to set the environment variable LD_LIBRARY_PATH while -building. You cannot 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. +Set this option to set the environment variable +LD_LIBRARY_PATH while building. You cannot 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. @@ -1346,8 +1341,7 @@ 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. +generated by the script. @@ -1363,8 +1357,8 @@ 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 Set this variable in order to pass command line options to the +make command. This is useful for programs such as distcc or systems with more than one processor core. @@ -1373,19 +1367,21 @@ systems with more than one processor core. 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 &subversion;. -This option is exactly equivalent to the command line option. +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 &subversion;. This option is exactly equivalent +to the +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. +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 essentially +commented it out. @@ -1396,12 +1392,17 @@ option for a module, then you have pretty much commented it out. 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. +$svn-server/home/kde/$module-base-path. -The default value is either trunk or -trunk/KDE, depending on the module name. + +The default value is either trunk/$module or trunk/KDE/$module, depending on +the module name. + Use the branch or tag options instead whenever they are applicable. @@ -1427,10 +1428,8 @@ module if it normally would have tried anyways. 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 &subversion; update messing up the build system. +This option was removed in version 1.10, since this behavior no longer helps +due to fixes in the underlying build system. @@ -1443,6 +1442,30 @@ cannot figure out what you mean using branch. + +prefix +Overrides global +This option controls where to install the module (normally the + setting is used). + + + + +purge-old-logs +Overrides global +This option controls whether old log directories are automatically +deleted or not. The default value is false. + +Even if you have not set this option to true, you can manually purge the +old log directories by running: + +kdesvn-build --no-src --no-build --purge-old-logs kdelibs + +You can use any module name in the above command line, it does not have +to be kdelibs. + + + qtdir Overrides global @@ -1477,6 +1500,15 @@ since &kdesvn-build; will be unable to perform incremental builds. + +repository +Overrides global +This option was introduced with version 1.10, and is used to +specify the &git; repository to download the source code for the module. +&Qt; (and therefore qt-copy) would need this option, as well as various +&kde; modules that are in the process of conversion to use &git;. + + revision Overrides global @@ -1488,6 +1520,16 @@ updated further unless this option is changed or removed from the configuration. + +run-tests +Overrides global +If set to true, then the module will be +built with support for running its test suite, and the test suite will be +executed as part of the build process. &kdesvn-build; will show a simple +report of the test results. This is useful for developers or those who want +to ensure their system is setup correctly. + + set-env Overrides global @@ -1537,10 +1579,6 @@ The default is the anonymous &subversion; repository, svn://anonsvn.kd 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. @@ -1555,42 +1593,18 @@ require &cmake;, and &cmake; use is not permitted on any other modules. 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 -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. +This option has been removed due to improvements in the &Qt; build +system. use-stable-kde Cannot be overridden -Since &kdesvn-build; has support for building &kde; 3 and 4, there -needs to be some way to tell which version to build. By default, &kdesvn-build; -will build the main line of &kde; development (called /trunk). But, this is -for &kde; 4, which is not yet ready for wide release. - - -You can use the &branch; option globally or for a module in order to -download for &kde; 3.5 (or 3.4, etc.). However, this is not convenient as some -modules (such as kdesupport) are shared by 3.5 and 4. In addition, it is a -lot of branch options that must be added to the configuration file. - -So, if you set this global option to true, &kdesvn-build; -will automatically download the &kde; 3.5 version of modules such as kdelibs -and qt-copy, instead of downloading the &kde; 4 version. You can still use -the &branch; or &tag; options for a module to override the setting that -&kdesvn-build; picks. This way you can easily choose to download &kde; 3.5 -instead of the release &kde; 4. + +This option was removed in version 1.10, which limits support to KDE 4, +removing the effect of this option. + @@ -1599,17 +1613,26 @@ instead of the release &kde; 4. + Command Line Options and Environment Variables + +Supported Environment Variables + -This script does not use environment variables. If you need to set environment +&kdesvn-build; does not use environment variables. If you need to set environment variables for the build or install process, please see the set-env option. + + + +Supported command-line parameters + The script accepts the following command-line options: @@ -1617,30 +1640,31 @@ The script accepts the following command-line options: - +--async -Enables the asynchronous mode to update and build -at the same time. This is the default, this option only needs specified if you -have disabled it in the configuration. +Enables the asynchronous mode, which can +perform the source code updates and module builds at the same time. This is +the default, this option only needs specified if you have disabled it in the +configuration. - +--help Only display simple help on this script. - +--version Display the program version. - +--author Display contact information for the author. @@ -1648,22 +1672,24 @@ author. - +--color -Enable colorful output. +Enable colorful output. (This is the default for interactive terminals). - +--nice=value -Sets the &niceness; value to value for the duration -of this run. value should be between 0 and 20. +This value adjusts the computer CPU priority requested by &kdesvn-build;, and +should be in the range of 0-20. 0 is highest priority (because it is the +least nice), 20 is lowest priority. &kdesvn-build; defaults +to 10. - +--no-async Disables the asynchronous mode of updating. Instead the update will be performed in its entirety before the build starts. @@ -1674,21 +1700,28 @@ while running &kdesvn-build; try using this option, and submitting a - +--no-color Disable colorful output. - (or ) +--pretend (or -p) -Do not actually do anything, but act like you did. +&kdesvn-build; will run through the update and build process, but instead of +performing any actions to update or build, will instead output what the +script would have done (e.g. what commands to run, general steps being taken, +etc.). + +Note: Simple read-only commands (such as reading file information) may +still be run to make the output more relevant (such as correctly simulating +whether source code would be checked out or updated). - (or ) +--quiet (or -q) Do not be as noisy with the output. With this switch only the basics are output. @@ -1696,74 +1729,79 @@ output. - +--really-quiet Only output warnings and errors. - +--verbose (or -v) Be very descriptive about what is going on, and what &kdesvn-build; is doing. - - + +--src-only (or --svn-only) -Only perform the source update. +Only perform the source update. (The --svn-only is +only supported for compatibility with older scripts). - +--build-only Only perform the build process. - +--ignore-modules -Do not include the modules passed on the rest of the command line in the update/build -process. +Do not include the modules passed on the rest of the command line in the +update/build process (this is useful if you want to build most of the modules +in your configuration file and just skip +a few). - - + +--no-src (or --no-svn) -Skip contacting the &subversion; server. +Skip contacting the &subversion; server. (The --no-svn +parameter is only supported for compatibility with older versions of the +script). - +--no-build Skip the build process. - +--no-install Do not automatically install packages after they are built. - +--debug -Enables debug mode for the script. Currently -this means that all output will be dumped to the standard output in addition to being -logged in the log directory like normal. Also, many functions are much more -verbose about what they are doing in debugging mode. +Enables debug mode for the script. Currently this means that all output will be +dumped to the standard output in addition to being logged in the log directory +like normal. Also, many functions are much more verbose about what they are +doing in debugging mode. - +--no-rebuild-on-fail Do not try to rebuild modules that have failed building from scratch. &kdesvn-build; will @@ -1773,104 +1811,155 @@ scratch. - +--refresh-build Recreate the build system and make from scratch. - - -Run the configure script again without cleaning the build directory. - - - - - +--reconfigure -Run make -Makefile.cvs again to create the configure script, and continue -building as normal. This option implies . +Run cmake (for &kde; modules) or +configure (for &Qt;) again, without cleaning the build +directory. You should not normally have to specify this, as &kdesvn-build; will +detect when you change the relevant options and automatically re-run the build +setup. This option is implied if --refresh-build is used. - +--resume-from This option is used to resume the build starting from the given module, which -should be the next option on the command line. This option -implies . You should not specify -other module names on the command line. +should be the next option on the command line. This option implies --no-src. 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. +This interprets the next command line parameter as the file to read the +configuration options from. The default value for this parameter is +kdesvn-buildrc (checked in the current directory) if +it is present, or ~/.kdesvn-buildrc otherwise. See +also . - +--run This option interprets the next item on the command line as a program to run, and &kdesvn-build; will then finish reading the configuration file, update the environment as normal, and then execute the given program. -This will not work to start a shell with the &kdesvn-build; environment in -most cases however, since interactive shells typically reset at least part of -the environment variables (such as PATH and +This will not work to start a shell with the &kdesvn-build; environment +in most cases however, since interactive shells typically reset at least part +of the environment variables (such as PATH and KDEDIRS) in the startup sequence. - + + +If you want to see the environment used by &kdesvn-build;, you +can run the printenv command: + +$ kdesvn-build --run printenv +KDE_SESSION_VERSION=4 +SDL_AUDIODRIVER=alsa +LANGUAGE= +XCURSOR_THEME=Oxygen_Blue +LESS=-R -M --shift 5 +QMAIL_CONTROLDIR=/var/qmail/control +... etc. + + + - +--prefix=</path/to/kde> + +This allows you to change the directory that &kde; will be installed to from +the command line. This option implies --reconfigure, +but using --refresh-build +may still be required. + + + + +--revision -This allows you to change the directory that &kde; will be installed to from the command line. -This option implies . +This option causes &kdesvn-build; to checkout a specific numbered revision +for each &subversion; module, overriding any branch, +tag, or revision +options already set for these modules. + +This option is likely not a good idea, and is only supported for +compatibility with older scripts. - +--build-system-only -Stop after running make 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 - for each module, and edit your configure-flags accordingly. +This option causes &kdesvn-build; to abort building a module just before +the make command would have been run. This is supported +for compatibility with older versions only, this effect is not helpful for +the current &kde; build system. - +--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 does not need installation. If command-line -options are specified after , they are all assumed to be modules to install. +If this is the only command-line option, it tries to install all of the modules +contained in log/latest/build-status. If command-line +options are specified after --install, they are all +assumed to be modules to install (even if they did not successfully build on +the last run). +--purge-old-logs + +This option causes &kdesvn-build; to delete unneeded log directories after +the build, to save disk space. All log directories that are not needed to +satisfy a link from log/latest will be deleted. This is disabled +by default. To enable this option by default, see the purge-old-logs +option. + + + +--no-snapshots + +Supplying this option causes &kdesvn-build; to always prefer a &subversion; +initial checkout of a module instead of using a &subversion; module snapshot. + + +Module snapshots are real &subversion; +checkouts. You should not need to specify this option, it is only a troubleshooting +aid. + + + - +--<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. +a specific module. @@ -1881,6 +1970,8 @@ Any other command-line options are assumed to be modules to update and build. Please, do not mix building with installing. + + @@ -1909,41 +2000,49 @@ do with this tool. qt-copy support -&kdesvn-build; strives to maintain excellent support for the qt-copy -module included in the &kde; &subversion; repository. +&kdesvn-build; supports building the &Qt; toolkit used by &kde; software +as a convenience to users. This support is handled by a special module named +qt-copy. - -qt-copy is a copy of the source code for the latest release of the &Qt; toolkit -used by &kde;. It also contains a patchset of optimization and bug improvement -patches which may optionally be applied. These patches are still compatible -with the &Qt; library so that code produced using qt-copy will run with normal -&Qt;. - +&Qt; is developed under a separate repository from &kde; software +located at http://qt.gitorious.org/qt. -Most of the differences required for qt-copy are handled automatically by -&kdesvn-build;. However, there are a few differences you may need to know -about. +In order to build &Qt;, you should make sure that the +qtdir setting is set to the directory you'd +like to install &Qt; to, as described in . - -Normally the value for &configure-flags; for a module is -appended to the global setting for &configure-flags;. However, the -&configure-flags; setting for qt-copy will replace the global setting since -they are not equivalent command lines. - +You should then ensure that the qt-copy module is added to +your .kdesvn-buildrc, before any other modules in the +file. If you are using the sample configuration file, you can simply +uncomment the existing qt-copy module entry. -&kdesvn-build; will automatically define some extra environment -variables to build qt-copy that are not normally required for the rest of &kde;. - +Now you should verify the repository option and branch options are set appropriately: - -qt-copy also has support for an optional patch set containing some bug fixes -and optimizations that have not yet made it to the official &Qt;. To enable -these, set the &apply-qt-patches; option to true. After -making this change you may have to run kdesvn-build - . - + +The first option is to build with a grouping of recommended bug +fix and optimization patches applied (this used to be controlled using an +option called apply-patches). This collection is developed in a separate +repository at http://gitorious.org/+kde-developers/qt/kde-qt. +If you would like to build with patches applied (most &kde; developers do) then +you should set your repository option to +git://gitorious.org/+kde-developers/qt/kde-qt.git + - +Otherwise, to build the standard &Qt;, set your repository +option to +git://gitorious.org/qt/qt.git + + +In both cases, the branch option should be set to master (unless you'd +like to build a different branch). + +In some cases the underlying source control software is unable to +work when run from &kdesvn-build;, but will still work fine when run from the +command prompt. This bug is still under investigation. @@ -2008,7 +2107,7 @@ permanently, then you need to adjust the &niceness; setting in the configuration file. The &niceness; setting controls how nice &kdesvn-build; is to other programs. In other words, having a higher &niceness; gives &kdesvn-build; a lower priority. So to give &kdesvn-build; a higher priority, reduce the -&niceness; (and vice versa). The &niceness; can go from 0 (not nice at all, +&niceness; (and vice versa). The &niceness; can go from 0 (not nice at all, highest priority) to 20 (super nice, lowest priority). You can also temporarily change the priority for &kdesvn-build; by @@ -2144,7 +2243,7 @@ adding directories to the option to figure out. One final note to make about this option: If you change the value of this -option, you should use kdesvn-build +option, you should use kdesvn-build in order to ensure that the module is reconfigured properly. In addition, &kdesvn-build; will never remove existing files if you take away the number of @@ -2168,7 +2267,7 @@ directories that should not be compiled. Also like &checkout-only;, this option requires at least that the configure script is run again for the module after changing -it. This is done using the kdesvn-build +it. This is done using the kdesvn-build command. @@ -2185,25 +2284,6 @@ end module - -Compiling a few directories from a full module - -You can use the &inst-apps; option to specify that only a few directories -out of a full module are to be built (but the entire module is still -downloaded). - - -This option is like the combination of &checkout-only; and &do-not-compile;: -it downloads the entire module like &do-not-compile;, but only compiles the -directories you specify, like &checkout-only;. Because of this it is usually -better to simply use &checkout-only; instead. - - -The same warnings apply as for the other two options: you must reconfigure -the module if you change the value of &inst-apps;. - - - @@ -2341,45 +2421,28 @@ as well. Automatic rebuilds -Due to various issues with the &kde; build system &kdesvn-build; will automatically perform -a series of steps to automatically try to get a module to compile when it -fails. +&kdesvn-build; used to include features to automatically attempt to +rebuild the module after a failure (as sometimes this re-attempt would work, +due to bugs in the build system at that time). Thanks to switching to &cmake; +the build system no longer suffers from these bugs, and so &kdesvn-build; will +not try to build a module more than once. There are situations where +&kdesvn-build; will automatically take action though: - -On the first failure, &kdesvn-build; will simply re-run the -make. Believe it or not, but this sometimes actually works, -and is quick to fail if it will not work. - + - -On the second failure, &kdesvn-build; will try to reconfigure the module and -then rebuild it. This usually catches situations where a build-system file -that requires reconfiguration changed, but the build system did not perform that -step automatically. - +If you change configure-flags +or cmake-options for a module, then +&kdesvn-build; will detect that and automatically re-run configure or cmake +for that module. -The module build directory is left intact for this step, so, except for the -reconfigure step, this will also fail quickly if the build cannot be performed. - - +If the buildsystem does not exist (even if &kdesvn-build; did +not delete it) then &kdesvn-build; will automatically re-create it. This is +useful to allow for performing a full --refresh-build for a specific module +without having that performed on other modules. - -If the module still fails to build, &kdesvn-build; will give up and move on -to the next module. There are still things that you can do to manually try to get the module to build, -however. - - - - -&kdesvn-build; will detect most cases where the build system needs to be -reconfigured, and will reconfigure automatically in that case. - + -Also, if &kdesvn-build; was building the module for the first time, all -of these steps are skipped, since the clean rebuild does not usually fail except -for a real error. - @@ -2414,37 +2477,18 @@ If you change the setting of the &build-dir; option, then use that instead of - -Controlling rebuild behavior -You may not want &kdesvn-build; to always try and rebuild a module. -You can permanently disable this behavior by changing the option &no-rebuild-on-fail; -to have the value true. - -You can disable this behavior temporarily (for one command) by using -the &cmd-no-rebuild-on-fail; command line option. - - - -% kdesvn-build - - - - - Changing environment variable settings -&kdesvn-build; does not read the environment from the caller like the -vast majority of most programs do. Instead, it uses the settings it reads -from the configuration file to construct the environment. This is done mainly to -ensure that builds are repeatable. In other words, -&kdesvn-build; can build a module even if you forgot what you set your -environment variables to in the shell you ran &kdesvn-build; from. +Normally &kdesvn-build; uses the environment that is present when +starting up when running programs to perform updates and builds. This is useful +for when you are running &kdesvn-build; from the command line. -However, you may want to change the setting for environment variables -that &kdesvn-build; does not provide an option for directly. -This is possible with the &set-env; option. +However, you may want to change the setting for environment variables +that &kdesvn-build; does not provide an option for directly. (For instance, +to setup any required environment variables when running &kdesvn-build; on +a timer such as &cron;) This is possible with the &set-env; option. Unlike most options, it can be set more than once, and it accepts two entries, separated by a space. The first one is the name of the environment @@ -2569,13 +2613,13 @@ syntax is similar: --module,option-name< access the &kde; source repository do not accidentally forget to leave the &ssh; Agent tool enabled. This can cause &kdesvn-build; to hang indefinitely waiting for the developer to type in their &ssh; password, -so by default, &kdesvn-build; will check if the Agent is running before +so by default &kdesvn-build; will check if the Agent is running before performing source updates. This is only done for &kde; developers using &ssh;. This is because -no password is required for the default anonymous checkout. &subversion; will handle -passwords for the second possible protocol for &kde; developers, https. +no password is required for the default anonymous checkout. &subversion; will +handle passwords for the second possible protocol for &kde; developers, https. You may wish to disable the &ssh; Agent check, in case of situations where @@ -2799,14 +2843,14 @@ autotools-based system that &kde; has used from the beginning. A introduction to &cmake; page is available on the &kde; TechBase. -Basically, instead of running make +Basically, instead of running make Makefile.cvs, then configure, then &make;, we simply run &cmake; and then &make;. &kdesvn-build; has support for &cmake;. A few features of &kdesvn-build; -were really features of the underlying buildsystem, including inst-apps, -configure-flags, +were really features of the underlying buildsystem, including +configure-flags and do-not-compile. When equivalent features are available, they are provided. For instance, the equivalent to the configure-flags option is cmake-options, and the @@ -2814,11 +2858,6 @@ configure-flags option is cmake-options -However, some options (like inst-apps) have no direct -equivalent, and are disabled. Should I find a way to implement them with &cmake; -I will do so and re-enable the option. However, more or less everything works -the same. -