kdecvs-build Documentation

kdecvs-build Reference

You should always be able to find the latest version of this file at http://grammarian.homelinux.net/kdecvs-build/

Introduction
Features
Configuration File
Configuration File Options
Command-line Options
Environment Variables Used

Introduction

kdecvs-build is a Perl script to help users install KDE from CVS. Unlike the two scripts available at http://developer.kde.org/build/compile_cvs.html, this script neither requires nor uses CVSup, for those who either can't or don't feel like installing it.

It is authored by Michael Pyne (mpyne (AT) grammarian (DOT) homelinux (DOT) net), and is one of several build scripts for this purpose.

2004-Jun-17: v$VERSION
New features:

The script now will report how long each module spent building, both in the output and in the build-status log file.
Someone had requested an option for having separate compilation and link cycles while building a program. Unfortunately, that doesn't appear to be supported by unsermake, and I don't think it makes sense anyways, as some programs in a module be depend on a shared or convienience lib that must be linked first. So this option isn't coming. :-(
Other than that, everything I wanted to accomplish for v$VERSION should be in.

2004-Jun-15: v0.73-pre1
Bugfixes:

The no-rebuild-on-fail configuration file option didn't actually work in prior versions.
Fix an infinite loop exposed when you disable auto-install.
The log file for a build now has a number appended, since multiple build attempts can occur during a single script run.
A few unlikely errors now have explicit checks in place.
More debugging output when --debug is activated.
Perl exception handling has been added to the main execution loop, so you should never again have one of my bugs crash the script and then force you to manually remove the lockfile.
Fix a bug with use-qt-builddir-hack where having the option set would cause the build system setup to fail on modules other than qt-copy. At least I've been testing. :-D
Don't add global to the log directory path if we're grabbing the global log directory.

Features:

Based on a suggestion by mornfall, the autorebuilding process doesn't clean out the build directory for a module when trying to rebuild. In addition, on a failure, make will be run again since sometimes that's all it takes to make it work. If the build process still fails, the build system will be recreated, but the build directory won't be cleaned. This is a big time saver, and should give the same results. Using the --refresh-build option will still cause the build directory to be cleaned at this point.
Added new option, make-install-prefix, which is a space-separated command (and options) to prefix the make command with when installing modules. This is useful for using sudo to automatically install packages with root privileges, but be careful! If you don't run this script from a terminal and you have this option set, you will have no way to enter a password if you need to.
Added new command line options, --resume, and --resume-from, which allows you to start the build process from a specific module. This option implies --no-cvs.
The build process outputs to a file called build-status in the global log directory, which lets you tell at a glance what modules built during the run of the script.
The script tells you the log directory to examine after running.

2004-Jun-13: v0.72 -- This Should Work Edition™
Bugfixes:

qt-copy bugfix #6564: There's no reason to try to download the admir dir for qt-copy, so let's not bother trying.
The workaround in 0.70 and 0.71 for the autorebuilding bug caused a bug of its own (no, I don't work for Microsoft), for which I apologize. Both bugs should now be fixed.
kde-common is no longer required to support checkout-only, and will therefore no longer be automatically downloaded. It will still be downloaded if you place it in your .kdecvs-buildrc.
qt-copy bugfix #2312: Although the last attempt to reconfigure qt-copy only when needed was inspired, it was ultimately flawed due to programmer incompetence. ;-)
Rearrange command-line options a little bit so that you can pass the --help and --version options to the script without having to have a configuration file installed.
Although not related to the end-user experience of the script per se, my packing script for kdecvs-build has been updated in the downtime while testing the script, and now keeps me from doing stupid stuff like forgetting to upgrade the version number in the script, forgetting to commit my changes to my CVS repository, and forgetting to actually install the script to test.

2004-Jun-12: v0.71
This release is dedicated to the heavy testing given the script by berkus and mornfall. Thanks guys!

Bugfixes:

Make script header documentation better.
Force configure to run if qt-copy hasn't been configured. If you had interrupted the build process for qt-copy before the configure script had run, it wouldn't build right after that.

New features:

If the admin directory does not exist for some reason, kick CVS in the head repeatedly until it checks it out. (I'm not responsible if CVS ends up in a coma).
Accept GPL license by default for qt-copy. If you happen to have a commerical license or some such for qt-copy, patches are accepted. :-)
Debug mode additions.
Experimental mode to simulate builddir != srcdir mode for qt-copy, as requested by berkus. This needs more testing, but it seems to Work For Me™. The appropriate configuration file option is use-qt-builddir-hack.
The script now creates a symlink to the latest log directory called latest. So you can always review the log of the last day the script ran in by browsing $(cvs-root)/log/latest.

I recommend that you set up a separate user account if you decide to run KDE from CVS. I didn't at first, and I won't repeat that mistake for KDE 3.3 ;-). I would also recommend that you add this script to your crontab so that you don't have to worry about manually running the build process. The script employs locking to prevent parallel execution. You also need to follow the instructions on http://developer.kde.org/source/anoncvs.html to set up your .cvsrc and .cvspass. You should also follow the instructions on that page regarding setting up your own repository, especially if you intend to use qt-copy. Make sure that qt-copy, arts, kdelibs, and kdebase are listed in that order in your configuration file. If you perform a single-user install of kdecvs-build, all you have to do to download, build, and install KDE from CVS (assuming no build errors) is to run the script.

$ kdecvs-build

If you perform a system-wide installation, you can run the entire script as root, although I would recommend using your distribution's packages or Konstruct to install a stable KDE.

Features

Features that I can think of off the top of my head:

Automatically checks out modules from CVS or updates from CVS, as appropriate.
Support for checking out specific branches of CVS modules.
Times the build process for modules.
Will automatically try to rebuild modules that were using incremental make, which is prone to failure after certain kinds of CVS commits.
Can resume a previous script, or start the build process from a particular module.
Much better support for qt-copy than 0.4x.
Can create a .cvsrc automatically if you forget to. .cvspass still isn't automatically created.
Unsermake support.
Tilde-expansion for your configuration options. For example, you can specify:
```
qtdir ~/kdecvs/qt-copy
```
Configurable build 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 CVS download directory pristine. The exception is qt-copy, which isn't designed to be built like that (unless you'd like to test use-qt-builddir-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 CVS 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 kdecvs-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.
Includes CVS over SSH support. The script CANNOT access your private key if it is password protected, so using ssh-agent is recommended.
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're 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't 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 check out only a portion of a KDE CVS module. For example, you could check out only taglib from kdesupport, or only K3B from kdeextragear-1. 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.
Can log output of all commands to a file in $KDECVSDIR/log.

Things that kdecvs-build does NOT do:

Find the fastest KDE CVS mirror. There isn't even a list shipped with the script at this point.
Brush your teeth. You should remember to do that yourself.
The script probably isn't bug-free. Sorry.

Format of .kdecvs-buildrc

To use the script, you must have a file in your home directory called .kdecvs-buildrc, which describes the modules you'd 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 CVS 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 me using the address you can find above.

apply-qt-patches
binpath
build-system-only
checkout-only
configure-flags
cvs-root
cvs-server
cxxflags
debug
disable-build-list
do-not-compile
install-after-build
kdedir
libpath
lockfile
make-install-prefix
make-options
manual-build
no-cvs
no-rebuild-on-fail
pretend
qtdir
reconfigure
recreate-configure
refresh-build
release-tag
stop-on-failure
use-qt-builddir-hack
use-unsermake

Configuration file Options

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
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.
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 empty, which is likely not what you want. 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. On my system, the setting binpath /bin:/usr/bin:/usr/X11R6/bin is the minimally sufficient setting.
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 CVS source directory ($KDECVS). 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 directory. 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/mpyne/builddir on my system. Perhaps surprisingly, this option can be changed per module.
build-system-only	Overrides global	Set this option to only create the build system for this module. What that means is that the `make -f Makefile.cvs` command will be run, and the configure script will be created (but not run), and make will not be run. This option is exactly equivalent to the --build-system-only command line option. This command is useful for checking what configure-flags each module supports so you can change your ~/.kdecvs-buildrc.
checkout-only	Overrides global	Set this option to checkout CVS 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 prepended, as it is required by the KDE build system. When checking out piece by piece, the admin directory will be pulled in from kde-common, which is where it exists on the CVS 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.
cvs-root	Can't be overridden	This option is used to set the directory on your computer to store the KDE CVS sources at. If you don't specify this value, the default is ~/kdecvs. If you do specify this value, use an absolute path name. Note that this setting has nothing to do with the CVSROOT environment variable. For that, see cvs-server.
cvs-server	Can't be overridden	This option is used to set the server used to check out from CVS. As an example, you could try :pserver:anonymous@bluemchen.kde.org:/home/kde Please see http://developer.kde.org/source/anoncvs.html for a list of CVS mirrors. It also has links to other CVS build scripts that you can try.
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.
debug	Can't be overridden	This option enables the script's debug mode. At this point, all this switch does is disable logging to files, instead dumping all output to stdout.
disable-build-list	Can't be overridden	Normally kdecvs-build will write out the list of modules that were successfully built to a file under the KDE CVS source directory called 'successfully-built'. If you set this option to 0, kdecvs-build will skip writing out the file.
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.
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	Set this option to set the environment variable KDEDIR while building. This is useful for one-user installations of KDE. See http://developer.kde.org/build/build2ver.html. You can't override this setting in a module option. If you don't specify this option, it defaults to absolutely nothing, which will mess up the configure script. You may use a tilde (~) to represent your home directory.
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.
lockfile	Can't be overridden	The path of a file to use for script locking, to prevent parallel execution. If you don't specify this value, the default is ~/.kdecvs-lock If the script is unable to create this file, it will abort.
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.
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 2 CPUs total, so it would be -j4 in my case.
make-output-file	Overrides global	DEPRECATED. As of version 0.6, this option is no longer used. Now all commands are logged, including the make process. You can use the log-dir option to change the logging directory, however.
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 CVS. This option is exactly equivalent to the --no-build command line option.
no-cvs	Overrides global	Set this option value to 'true' to prevent CVS updates for the module. This option is exactly equivalent to the --no-cvs command line option.
no-rebuild-on-fail	Overrides global	Set this option value to 'true' to always prevent kdecvs-build from trying to rebuild this module if it should fail an incremental build. Normally kdecvs-build will try to rebuild the module from scratch to counteract the effect of a stray CVS update messing up the build system.
pretend	Can't be overridden	Set the option value to 'true' in order to "fake" the update/build or install process. This setting results in verbose output, and is exactly equivalent to the --pretend command line option.
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 absolutely nothing, which will mess up the configure script. You may use a tilde (~) to represent your home directory.
recreate-configure	Overrides global	Use this option to re-run make -f Makefile.cvs and then reconfigure the module before building. Note that setting this option in the configuration file isn't a great idea, use --recreate-configure on the command line instead.
release-tag	Overrides global	Use this option to force checkout from a specific KDE CVS branch. For example, setting this to KDE_3_2_BRANCH allows you to keep up-to-date with the current stable KDE release, including bugfixes. You can use KDE's WebCVS page to find out what branches exist for each CVS module.
reconfigure	Overrides global	Use this option to reconfigure the module before building. Note that setting this option in the configuration file isn't a great idea, use --reconfigure on the command line instead.
refresh-build	Overrides global	Set this option value to 'true' to cause the build system for this module to start from scratch every time the script is run. This option is exactly equivalent to the --refresh-build command line option.
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.
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, kdecvs-build will copy the qt-copy CVS 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.
use-unsermake	Overrides global	Set this option to a non-zero value 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.

Command-line options

The script accepts the following command-line options:

--help, which displays simple help on this script.
--version, display the program version.
--author, display contact information for the author.
--pretend (or -p), don't actually DO anything, but act like you did.
--no-cvs, Skip contacting the CVS 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 instead of logged in the log directory like normal.
--no-rebuild-on-fail, Don't try and rebuild modules that have failed building from scratch. kdecvs-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-cvs. 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-cvs. You should not specify other module names on the command line.
--build-system-only, Stop after runnning make -f Makefile.cvs. The configure script will still need to be run, which kdecvs-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. Note that after v0.60, modules are automatically installed if they build successfully.

Environment Variables

The script no longer uses any environment variables. Please try to set at least binpath, qtdir, and kdedir in your .kdecvs-buildrc. See the .kdecvs-buildrc options.