From 2d0f0bf661aebb7f5ed487c7253fde1a38bc8790 Mon Sep 17 00:00:00 2001 From: Michael Pyne Date: Wed, 7 Sep 2011 22:14:44 -0400 Subject: [PATCH] doc: Improve rc-file layout documentation. Really this was mostly an excuse to document the new "include" feature. --- doc/index.docbook | 98 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 84 insertions(+), 14 deletions(-) diff --git a/doc/index.docbook b/doc/index.docbook index fd497e9..34bd54d 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -1238,8 +1238,15 @@ To use the script, you must have a file in your home directory called like to download and build. + +Layout of the configuration file + + +Global configuration + -It starts with the global options, specified like the following: +The configuration file starts with the global options, specified like the +following: @@ -1249,24 +1256,91 @@ global end global + + +Module configuration + -It is then followed by one or more module sections, specified like the -following: +It is then followed by one or more module sections, specified in one of the +following two forms: + + module module-name option-name option-value [...] end module + + + + +module-set module-set-name + repository kde-projects or git://host.org/path/to/repo.git + use-modules module-names + +# Other options may also be set +option-name option-value +[...] +end module-set + + + + +Note that the second form, module sets, only works +for Git-based modules. + + +For Subversion modules, module-name must be a module +from the &kde; &subversion; repository (for example, kdeartwork or +kde-wallpapers), although it is possible to get around this if you manually +specify the &subversion; URL. + -module-name must be a module from the &kde; &subversion; repository (for -example, kdelibs or kdebase). Some options override global options, some -add to global options, and some global options simply cannot be overridden. +For Git modules, the module name can be essentially whatever you'd like, as +long as it does not duplicate any other module name in the configuration. Keep +in mind the source and build directory layout will be based on the module name +if you do not use the dest-dir option. + + +However, for Git module sets the +module-names must correspond with actual git modules +in the chosen . See git-repository-base or use-modules for more information. + + + + +Including other configuration files + + +Within the configuration file, you may reference other files by using the +include keyword with a file, which will act as if the file +referenced had been inserted into the configuration file at that point. + + +For example, you could have something like this: + +global + include ~/common-kdesrc-build-options + + # Insert specific options here. + +end global + + + + + + +Commonly used configuration options + The following is a list of commonly-used options. Click on the option to find out more about it. To see the full list of options, see @@ -1274,20 +1348,16 @@ option to find out more about it. To see the full list of options, see -branch, to checkout from a branch instead of /trunk. -build-dir, to set the directory to build in. cmake-options to define what flags to configure a module with using &cmake;. -configure-flags to define what flags to configure a module with. -cxxflags to define the CXXFLAGS variable. +branch, to checkout from a branch instead of /trunk (for &subversion;) or master (for Git). +configure-flags to define what flags to configure &Qt; with. kdedir, to set the directory to install &kde; to. -kde-languages, to set the translation packages to download and install. -make-options, to pass options to the &make; program. +make-options, to pass options to the &make; program (such as number of CPUs to use). qtdir, to set the path to &Qt;. -set-env, to set an environment variable. source-dir, to change where to download the source code to. -svn-server, to change the server the sources are downloaded from. + Table of available configuration options