Supported command-line parameters

The script accepts the following command-line options:

--async

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.

--color

Enable colorful output. (This is the default for interactive terminals).

--nice=value

This value adjusts the computer CPU priority requested by kdesrc-build, and should be in the range of 0-20. 0 is highest priority (because it is the least nice), 20 is lowest priority. kdesrc-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. This option will slow down the overall process, but if you encounter IPC errors while running kdesrc-build try using this option, and submitting a bug report.

--no-color

Disable colorful output.

--pretend (or -p)

kdesrc-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).

Important

This option requires that some needed metadata is available, which is normally automatically downloaded, but downloads are disabled in pretend mode. If you've never run kdesrc-build (and therefore, don't have this metadata), you should run kdesrc-build --metadata-only to download the required metadata first.

--quiet (or -q)

Do not be as noisy with the output. With this switch only the basics are output.

--really-quiet

Only output warnings and errors.

--verbose (or -v)

Be very descriptive about what is going on, and what kdesrc-build is doing.

--src-only (or --svn-only)

Only perform the source update. (The --svn-only is only supported for compatibility with older scripts).

--build-only

Only perform the build process.

--install-only

Only perform the install process.

--metadata-only

Only perform the metadata download process. kdesrc-build normally handles this automatically, but you might manually use this to allow the --pretend command line option to work.

--rebuild-failures

Use this option to build only those modules which failed to build on a previous kdesrc-build run. This is useful if a significant number of failures occurred mixed with successful builds. After fixing the issue causing the build failures you can then easily build only the modules that failed previously.

Note

Note that the list of previously-failed modules is reset every time a kdesrc-build run finishes with some module failures. However it is not reset by a completely successful build, so you can successfully rebuild a module or two and this flag will still work.

This option was added for kdesrc-build 15.09.

--ignore-modules

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. (The --no-svn parameter is only supported for compatibility with older versions of the script).

--no-build

Skip the build process.

--no-metadata

Do not automatically download the extra metadata needed for KDE git modules. The source updates for the modules themselves will still occur unless you pass --no-src as well.

This can be useful if you are frequently re-running kdesrc-build since the metadata does not change very often. But note that many other features require the metadata to be available. You might want to consider running kdesrc-build with the --metadata-only option one time and then using this option for subsequent runs.

--no-install

Do not automatically install packages after they are built.

--no-build-when-unchanged, --force-build

This option explicitly disables skipping the build process (an optimization controlled by the build-when-unchanged option). This is useful for making kdesrc-build run the build when you have changed something that kdesrc-build cannot check.

--force-build performs the exact same function, and is perhaps easier to remember.

--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.

--query=mode

This command causes kdesrc-build to query a parameter of the modules in the build list (either passed on the command line or read in from the configuration file), outputting the result to screen (one module per line).

This option must be provided with a query mode, which should be one of the following:

  • source-dir, which causes kdesrc-build to output the full path to where the module's source code is stored.

  • build-dir, which causes kdesrc-build to output the full path to where the module build process occurs.

  • install-dir, which causes kdesrc-build to output the full path to where the module will be installed.

  • project-path, which causes kdesrc-build to output the location of the module within the hierarchy of KDE source code repositories. See the section called “The official KDE module database” for more information on this hierarchy.

  • branch, which causes kdesrc-build to output the resolved git branch that will be used for each module, based on the tag, branch and branch-group settings in effect.

  • Otherwise, option names that are valid for modules in the configuration file can be used, the resolved value of which will be listed for each module.

If a single module is passed on the command line, then the output is simply the value of the parameter being queried. If multiple (or no) modules are passed on the command line, then each line is prefixed by the name of the module. Either way, kdesrc-build stops running once each value is output.

This option was added with kdesrc-build 16.05.

For example, the command kdesrc-build --query branch kactivities kdepim might end up with output like:

kactivities: master
kdepim: master
--no-rebuild-on-fail

Do not try to rebuild modules that have failed building from scratch. kdesrc-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 cmake (for KDE modules) or configure (for Qt™) again, without cleaning the build directory. You should not normally have to specify this, as kdesrc-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. You should not specify other module names on the command line.

Note

This option formerly added --no-src, but does not any longer (since kdesrc-build 1.13). If you want to avoid source updates when resuming, simply pass --no-src in addition to the other options.

See also: --resume-after and the section called “Resuming a failed or canceled build”. You would prefer to use this command line option if you have fixed the build error and want kdesrc-build to complete the build.

--resume-after

This option is used to resume the build starting after the given module, which should be the next option on the command line. You should not specify other module names on the command line.

Note

This option formerly added --no-src, but does not any longer (since kdesrc-build 1.13). If you want to avoid source updates when resuming, simply pass --no-src in addition to the other options.

See also: --resume-from and the section called “Resuming a failed or canceled build”. You would prefer to use this command line option if you have fixed the build error and have also built and installed the module yourself, and want kdesrc-build to start again with the next module.

--resume

This option can be used to run kdesrc-build after it has had a build failure.

It resumes the build from the module that failed, using the list of modules that were waiting to be built before, and disables source and metadata updates as well. The use case is when a simple mistake or missing dependency causes the build failure. Once you correct the error you can quickly get back into building the modules you were building before, without fiddling with --resume-from and --stop-before.

This is even handier with the --stop-on-failure command line argument, especially if you're initially setting up your development environment.

This option was added with kdesrc-build 1.16.

--stop-before

This command line option is used to stop the normal build process just before a module would ordinarily be built.

For example, if the normal build list was moduleA, moduleB, moduleC, then --stop-before=moduleB would cause kdesrc-build to only build moduleA.

This command line option was added with kdesrc-build 1.16.

--stop-after

This command line option is used to stop the normal build process just after a module would ordinarily be built.

For example, if the normal build list was moduleA, moduleB, moduleC, then --stop-after=moduleB would cause kdesrc-build to build moduleA and moduleB.

This command line option was added with kdesrc-build 1.16.

--stop-on-failure

This option causes the build to abort as soon as a failure occurs. Useful when you're setting up your initial development environment. Without this flag, kdesrc-build will try to press on with the rest of the modules in the build to avoid wasting time in case the problem is with a single module.

This option was added with kdesrc-build 1.16. See also the stop-on-failure option.

--rc-file

This interprets the next command line parameter as the file to read the configuration options from. The default value for this parameter is kdesrc-buildrc (checked in the current directory) if it is present, or ~/.kdesrc-buildrc otherwise. See also Chapter 4, Configuring kdesrc-build.

--print-modules

Takes all actions up to and including dependency reordering of the modules specified on the command line (or configuration file), prints the modules that would be processed one per line, and then exits without further action.

The kde-project metadata is downloaded first (though, see --pretend or --no-src).

The output is not fully compatible with usage by scripts as other output messages may be generated until the module list is shown.

This is mostly just useful for quickly determining what kdesrc-build understands a module's dependencies to be, which means it's only useful for kde-projects modules. This option is also compatible with --resume-from, --resume-after, --stop-before, --stop-after.

--run

This option interprets the next item on the command line as a program to run, and kdesrc-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 kdesrc-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.

Tip

If you want to see the environment used by kdesrc-build, you can run the printenv command:

$ kdesrc-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 option causes kdesrc-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

This option causes kdesrc-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 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).

--no-snapshots

Supplying this option causes kdesrc-build to always perform a normal initial checkout of a module instead of using a quick-start snapshot (only available for Git modules from the kde-projects repository). Note that this option should only be used if there is a failure using snapshots, as the quick-start snapshot reduces load on the KDE source repositories.

Note

Module snapshots are real checkouts. You should not need to specify this option, it is only a troubleshooting aid.

--delete-my-patches

This option is used to let kdesrc-build delete source directories that may contain user data, so that the module can be re-downloaded. This would normally only be useful for KDE developers (who might have local changes that would be deleted).

This is currently only used to checkout modules that have been converted from Subversion to Git. You should not use this option normally, kdesrc-build will prompt to be re-run with it if it is needed.

--delete-my-settings

This option is used to let kdesrc-build overwrite existing files which may contain user data.

This is currently only used for xsession setup for the login manager. You should not use this option normally, kdesrc-build will prompt to be re-run with it if it is needed.

--<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.

Note

This feature can only be used for option names already recognized by kdesrc-build, that are not already supported by relevant command line options. For example the async configuration file option has specific --async and --no-async command line options that are preferred by kdesrc-build.

--set-module-option-value=<module-name>,<option-name>,<option-value>

You can use this option to override an option in your configuration file for a specific module.

Any other command-line options are assumed to be modules to update and build. Please, do not mix building with installing.