From 2da73860ea586c164617dacdc319cb8bb658ac41 Mon Sep 17 00:00:00 2001 From: Michael Pyne Date: Wed, 2 May 2007 02:55:09 +0000 Subject: [PATCH] Revise and modernize the documentation/help text for kdesvn-build a bit. Unless something breaks for someone overnight this will be kdesvn-build 1.4 tomorrow. svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=660238 --- doc/index.docbook | 219 ++++++++++++++++++++++++++-------------------- kdesvn-build | 56 ++++++------ 2 files changed, 155 insertions(+), 120 deletions(-) diff --git a/doc/index.docbook b/doc/index.docbook index 2e62ac2..47a869d 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -78,6 +78,7 @@ 2006 +2007 Michael Pyne @@ -89,8 +90,8 @@ &FDLNotice; -2006-03-28 -1.1 +2007-05-01 +1.4 &kdesvn-build; is a script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository. @@ -189,10 +190,8 @@ Requirements page. Autoconf version 2.57, or higher. (KDE 3 only) CMake 2.4.0, or -higher. Some version 2.3 snapshots may compile KDE 4 as well, please see the -CMake Introduction Wiki page. (KDE 4 -only) +url="http://www.cmake.org/">CMake 2.4.5, or +higher. The &svn; client program, including support for Secure HTTP (https). To ensure needed support, you can run @@ -200,8 +199,8 @@ HTTP (https). To ensure needed support, you can run If the ra_dav module says that it handles the https scheme then you should be set to go. -The gcc compiler, with support for C++. Version 3.3 or 3.4 works -the best at this point. +The gcc compiler, with support for C++. Versions 3.3 or higher +are the best supported. Be sure to check the &kde; Compilation @@ -230,7 +229,13 @@ to have it. If you don't want to use the &Qt; copy, you need to do these things If you don't already have &Qt; installed, install it, including any relevant -dev or -devel packages. You'll need at least &Qt; 3.3 if you're - building &kde; 3.5, or &Qt; 4.0 if you're building &kde; 4. + building &kde; 3.5, or &Qt; 4.3 if you're 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). @@ -259,6 +264,12 @@ in your system. However, if you don't, you can download it from &homepage;, or you can find it from its home in the &kde; source repository. +&kdesvn-build; is included with the kdesdk module, and the module +is often installed by distributions already. If you have downloaded +&kdesvn-build; ensure that you are using the version you downloaded. You can +use the --version option to be sure you are running the version you think +you are. + To download &kdesvn-build; from its &homepage;, simply go to the &homepage; and download the latest appropriate release. The release is @@ -280,7 +291,7 @@ if you need to. kdesvn-build file is executable. For convenience you should make sure it is in a directory contained in the PATH environment variable, otherwise you may get messages saying that the command -was not found. +was not found, or you may run a previously-installed version by mistake. @@ -340,12 +351,25 @@ The default settings should actually already be appropriate to perform a binpath, to change the list of 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. + qtdir, which controls the path to the installation of &Qt; to use. The defaults to using the qt-copy -module from the &kde; &svn; repository. (~/kdesvn/build/qt-copy) +module from the &kde; &svn; repository. (~/kdesvn/build/qt-copy) + +For Qt versions that support installation, this also controls where to +install qt-copy. + svn-server, which selects what URL to download the sources from. This is useful if you are a developer with a &kde; @@ -395,9 +419,13 @@ the caused an error for a module in the last &kdesvn-build; command, usually it is sufficient to look at ~/kdesvn/log/latest/module-name/error.log. In that file, you will see the error that caused the build to fail for -that module. If the file says (at the bottom) that you're missing some packages, -try installing the package (including any appropriate -dev packages) before -trying to build that module. Or, if the error appears to be a build error +that module. If the file says (at the bottom) that you're missing some +packages, try installing the package (including any appropriate -dev packages) +before trying to build that module, and pass the --reconfigure option after install 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 isn't resolved within that time, feel free to mail the kde-devel@kde.org (subscription may be required first) @@ -596,7 +624,8 @@ to your &kdesvn-build; &kde;. For developers: Supports building the API -documentation for a module. +documentation for a module. Note that this only works for KDE 3 +modules when not using the unsermake script. @@ -605,10 +634,12 @@ ranging from being very quiet to a full debug level. -&kdesvn-build; can, with the assistance of the kdesvn-build website, -allow for speedy checkouts of some modules. If the module you are checking out -has already been packaged at the website, then kdesvn-build will download the -snapshot and prepare it for use on your computer. +&kdesvn-build; can, with the assistance of the kdesvn-build website and the +KDE FTP server (FTP since &kdesvn-build; 1.4), allow for speedy checkouts of +some modules. If the module you are checking out has already been packaged at +the website, then kdesvn-build will download the snapshot and prepare it for +use on your computer. This is faster for you, and helps to ease the load on the kde.org @@ -640,6 +671,20 @@ standard flags as appropriate to save you the trouble and possible errors from typing them yourself. + +&kdesvn-build; can checkout a specific branch +or tag of a module. You can also ensure that a specific 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 +&kdesvn-build; know that it is acceptable to perform the switch. + + &kdesvn-build; can checkout only portions of a module, for those situations where you only need one program from a @@ -647,9 +692,9 @@ large module. -For developers: Will remind you if -you use svn+ssh:// but ssh-agent is not running, as -this will lead to repeated password requests from +For developers: &kdesvn-build; will remind +you if you use svn+ssh:// but ssh-agent is +not running, as this will lead to repeated password requests from ssh. @@ -696,16 +741,6 @@ given module. You can even ignore some modules temporarily for a given build. - -&kdesvn-build; also supports using the ~/ sequence to stand for your home -directory in the &rcfile;. - - - -Automatically checks out or updates modules from &svn;, as -appropriate. - - &kdesvn-build; can quickly perform a partial build of a module directly from the command line, when you only need @@ -715,13 +750,14 @@ to update part of a module. &kdesvn-build; will automatically download and create the required /admin directory for a module if it isn't downloaded from &svn; the first time for -some reason. +some reason. This only applies to KDE 3 modules, as /admin is not required +for qt-copy or KDE 4 modules. &kdesvn-build; will show the progress of your -build when using &unsermake;, and will always time the build process so -you know after the fact how long it took. +build when using &unsermake; and CMake, and will always time the build +process so you know after the fact how long it took. @@ -729,10 +765,6 @@ Automatically tries to rebuild modules that were using incremental make, which is prone to failure after certain kinds of commits. - -Can resume a build 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. @@ -748,16 +780,10 @@ 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). +pristine. @@ -797,11 +823,6 @@ 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 @@ -817,13 +838,6 @@ 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. - - @@ -1018,7 +1032,9 @@ process. This only works for modules where make apidox does including kdelibs, kdebase, and koffice, among others. This option does not work for modules using &unsermake; support, due to -deficiencies in the unsermake build system. +deficiencies in the &unsermake; build system. This option does not work for +KDE 4 modules because the required build system support has been migrated to +a different program which &kdesvn-build; has not been corrected to use yet. @@ -1055,7 +1071,7 @@ default of "trunk", where &kde; development occurs. For instance, to checkout 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 +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. @@ -1176,7 +1192,7 @@ 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 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 pass phrase for every module. You can disable this check by setting disable-agent-check to true. @@ -1197,7 +1213,7 @@ the checkout-only directive to choose directories that you want to check out. This option does not yet work with modules built using -&cmake; +&cmake;. @@ -1205,7 +1221,7 @@ 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 +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). @@ -1221,13 +1237,13 @@ needs this option. 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 +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 +option to set the address &kdesvn-build; should send from, since the default is usually not what you want. @@ -1333,12 +1349,9 @@ please be careful while dealing with root privileges. 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 - 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 - in my case. +url="http://distcc.samba.org/">distcc or +systems with more than one processor core. + @@ -1373,6 +1386,9 @@ following template: The default value is either trunk or trunk/KDE, depending on the module name. +Use the branch or tag options instead whenever they are applicable. + @@ -1396,9 +1412,9 @@ 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 +If you set this option, &kdesvn-build; will use its value as the URL to pass to &svn; completely unchanged. You should -generally use this if you want to download a specific release but kdesvn-build +generally use this if you want to download a specific release but &kdesvn-build; can't figure out what you mean using branch. @@ -1433,10 +1449,21 @@ installed. 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. +since &kdesvn-build; will be unable to perform incremental builds. + +revision +Overrides global +If this option is set to a value other than 0 (zero), &kdesvn-build; +will force the Subversion update to bring the module to the exact revision +given, even if options like branch are in +effect. If the module is already at the given revision then it will not be +updated further unless this option is changed or removed from the +configuration. + + set-env Overrides global @@ -1462,13 +1489,6 @@ you do specify this value, use an absolute path name. - -svn-server -Overrides global -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 @@ -1478,6 +1498,13 @@ by default. + +svn-server +Overrides global +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/ + + tag Overrides global @@ -1486,23 +1513,27 @@ by default. 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 +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. + +unsermake-options +Overrides global +This option is just like make-options +but for &unsermake;, which accepts some options that make +cannot understand. + + + use-cmake Overrides global - -This option allows you to force &kdesvn-build; to try (or not try) to use -CMake with a given module. Normally &kdesvn-build; will always try to use CMake -if it is present in the module, as this will be required to build KDE 4. This -option is available to ease the transition from unsermake to CMake. This option -will be removed once all KDE 4 modules require CMake. - +This option was removed in &kdesvn-build; 1.4 as all KDE 4 modules +require CMake, and CMake use is not permitted on any other modules. @@ -1511,7 +1542,7 @@ will be removed once all KDE 4 modules require CMake. 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, +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 @@ -1552,16 +1583,16 @@ instead of the pre-release &kde; 4. use-unsermake Overrides global Set this option to true in order to use the -experimental unsermake program instead of automake when running the configure +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 +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 +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. diff --git a/kdesvn-build b/kdesvn-build index 25ea7e8..2043732 100755 --- a/kdesvn-build +++ b/kdesvn-build @@ -6,7 +6,7 @@ # Please also see the documentation that should be included with this program, # from the kdesdk/doc/scripts/kdesvn-build directory. # -# Copyright © 2003 - 2006 Michael Pyne. +# Copyright © 2003 - 2007 Michael Pyne. # Home page: http://kdesvn-build.kde.org/ # # You may use, alter, and redistribute this software under the terms @@ -18,7 +18,7 @@ =over -=item B - automate the kde svn build process +=item B - automate the KDE build process from its source repository =back @@ -36,7 +36,7 @@ The B script is used to automate the download, build, and install process for KDE (using Subversion). It is recommended that you first setup a F<.kdesvn-buildrc> file -in your home directory. Please refer to B help file +in your home directory. Please refer to the B help file in KDE help for information on how to write F<.kdesvn-buildrc>, or consult the sample file which should have been included with this program. If you don't setup a F<.kdesvn-buildrc>, a @@ -51,9 +51,9 @@ You can use this program to install KDE as well, if you are building KDE for a single user. Note that B will try to install the modules by default. -If you DO specify a package name, then your settings will still be -read, but the script will try to build / install the package -regardless of F<.kdesvn-buildrc> +If you DO specify module names on the command line, then your settings will +still be read from F<.kdesvn-buildrc>, but the script will try to build and +install the given modules in the order given on the command line. kdesvn-build reads options in the following order: @@ -153,25 +153,29 @@ Forces update to revision from Subversion. =item B<--refresh-build> Start the build from scratch. This means that the build directory for the -module B before make -f Makefile.cvs is run again. You can -use B<--recreate-configure> to do the same thing without deleting the module -build directory. +module B before make -f Makefile.cvs or cmake is run again. +You can use B<--recreate-configure> to do the same thing without deleting the +module build directory for KDE 3 modules. KDE 4 modules have no separate +configure command, use the B<--reconfigure> option to get the same effect. =item B<--reconfigure> -Run configure again, but don't clean the build directory or re-run -make -f Makefile.cvs. +Run configure again, but don't clean the build directory or recreate the +configure script. For KDE 4 modules, this option runs cmake again without +deleting the build directory. =item B<--recreate-configure> Run make -f Makefile.cvs again to redo the configure script. The build -directory is not deleted. +directory is not deleted. This command is ignored for KDE 4 modules, where +it is not applicable. =item B<--no-rebuild-on-fail> Do not try to rebuild a module from scratch if it failed building. Normally kdesvn-build will try progressively harder to build the module before giving -up. +up. This option is always enabled for KDE 4 modules, where the build system +is accurate enough that the rebuilding behavior is not necessary. =item B<--build-system-only> @@ -268,7 +272,7 @@ use constant { ERROR => 5, }; -my $versionNum = '1.4-rc1'; +my $versionNum = '1.4'; # Some global variables # Remember kids, global variables are evil! I only get to do this @@ -2665,11 +2669,6 @@ sub setup_module_environment # KDE from Subversion. Change this section if a dependency changes later. sub initialize_environment { -# With latest detect-autoconf.pl in /admin I don't *think* it's necessary -# to specify a specific automake any longer. -# $ENV{"WANT_AUTOMAKE"} = "1.7"; -# $ENV{"WANT_AUTOCONF_2_5"} = "1"; - if(-t STDOUT and get_option('global', 'colorful-output')) { $RED = "\e[31m"; @@ -2920,14 +2919,14 @@ if you\'re building KDE for a single user. Note that kdesvn-build will try by default to install the modules. Basic synopsis, after setting up .kdesvn-buildrc: -\$ kdesvn-build [package names] (Download, build, and install KDE) +\$ kdesvn-build [module names] (Download, build, and install KDE) -If you don\'t specify any particular package names, then your settings -in .kdesvn-buildrc will be used. If you DO specify a package name, then +If you don\'t specify any particular module names, then your settings +in .kdesvn-buildrc will be used. If you DO specify a module name, then your settings will still be read, but the script will try to build/install -the package regardless of .kdesvn-buildrc +the modules in the order given on the command line. -Copyright (c) 2003 - 2006 $author +Copyright (c) 2003 - 2007 $author The script is distributed under the terms of the GNU General Public License v2, and includes ABSOLUTELY NO WARRANTY!!! @@ -2990,8 +2989,10 @@ Options: --author Output the author(s)\'s name. --version Output the program version. -You can get more help by reading the included HTML documentation, or going -online to http://kdesvn-build.kde.org/ +You can get more help by going online to http://kdesvn-build.kde.org/ to view +the online documentation. The documentation is installed with the kdesdk +module, so you may be able to view the documentation using KHelpCenter or +Konqueror at help:/kdesvn-build DONE # We haven't done any locking... no need to finish() # Avoids log-dir errors due to having not performed. @@ -4791,6 +4792,9 @@ sub make_apidox_supported { my $module = shift; + # TODO: Implement APIDOX for CMake. + return 0 if module_uses_cmake($module); + return $module =~ /^(KDE\/)?(kde(base|games|graphics|libs|pim|velop)|koffice)$/; }