Getting Started/Build/kdesrc-build-config: Difference between revisions

From KDE TechBase
mNo edit summary
 
(16 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== kdesvn-buildrc ==
{{warning|This page is currently partly outdated. For more up to date instructions visit the [https://kdesrc-build.kde.org/documentation/ kdesrc-build Script Manual] and the Community Wiki: [http://community.kde.org/Frameworks/Building Building KDE Frameworks].}}
 
== kdesrc-buildrc ==
=== Introduction ===
This page introduces how to configure [[Getting Started/Build/kdesrc-build|kdesrc-build]]
 
The [[Getting_Started/Build/kdesvn-build|kdesvn-build]] program, which is used to download, build, and install [http://www.kde.org/ KDE] from the [http://websvn.kde.org/ KDE source repository], uses a file called {{path|kdesvn-buildrc}} in order to control what is downloaded and built, what options are used, and where KDE is installed to.
 
This is a description of how to use {{path|kdesvn-buildrc}}.
 
=== Creating your configuration ===
=== Creating your configuration ===


The kdesvn-build download will include a file called {{path|kdesvn-buildrc-sample}}, which is a sample configuration file suitable for building the KDE Software Compilation (SC).
The kdesrc-build download will include a file called {{path|kdesrc-buildrc-sample}}, which is a sample configuration file suitable for building the KDE Software Compilation (SC).


To create your configuration, it is recommended to use this file as a base since it includes the standard list of KDE modules to build, in the correct order.  (You can, of course, add or remove most modules if you like).
To create your configuration, it is recommended to use this file as a base since it includes the standard list of KDE modules to build, in the correct order.  (You can, of course, add or remove most modules if you like).


You can use any standard text editor to edit this file, such as KWrite, nano, vi, etc.
You can use any standard text editor to edit this file, such as KWrite, nano, vi, etc.
You can even use the convenient kdesrc-build-setup Script which asks some question and puts your answers into the configuration file.


==== Global configuration ====
==== Global configuration ====


Once you open the file, you will see that it starts with some comments (on lines beginning with #), and then the world "global".  This starts the global configuration for the kdesvn-buildrc, which is used to specify options which are common to all of the modules.
Once you open the file, you will see that it starts with some comments (on lines beginning with #), and then the world "global".  This starts the global configuration for the kdesrc-buildrc, which is used to specify options which are common to all of the modules.


Each option in the global section is specified in the following form:
Each option in the global section is specified in the following form:
Line 26: Line 23:
Here's a short listing of some of the important global options:
Here's a short listing of some of the important global options:


* source-dir: This option controls where kdesvn-build will download the sources to.  In addition, most other directories that kdesvn-build uses will be subdirectories of this directory by default, so it is a kind of "kdesvn-build prefix". The default value is {{path|~/kdesvn}}, which downloads the source in a subdirectory under your home directory.
* source-dir: This option controls where kdesrc-build will download the sources to.  In addition, most other directories that kdesrc-build uses will be subdirectories of this directory by default, so it is a kind of "kdesrc-build prefix". The default value is {{path|~/kdesrc}}, which downloads the source in a subdirectory under your home directory.
* build-dir: This controls where kdesvn-build actually builds the various modules.  Normally it is the directory {{path|build}} under your source directory.
* build-dir: This controls where kdesrc-build actually builds the various modules.  Normally it is the directory {{path|build}} under your source directory.
* kdedir: This controls where the KDE SC (and the various supporting modules such as kdesupport) get installed to. The default is {{path|~/kde}}, which installs to your home directory.
* kdedir: This controls where the KDE SC (and the various supporting modules such as kdesupport) get installed to. The default is {{path|~/kde}}, which installs to your home directory.


Line 51: Line 48:
==== Module configuration ====
==== Module configuration ====


After the global options are all done, you'll see the line "end global", which lets kdesvn-build know that all of the global options have been read.
After the global options are all done, you'll see the line "end global", which lets kdesrc-build know that all of the global options have been read.


Next in the kdesvn-buildrc are the module options.  First off, modules are listed in the file, in the order they are to be built and installed.  Each module is listed in the following format:
Next in the kdesrc-buildrc are the module options.  First off, modules are listed in the file, in the order they are to be built and installed.  Each module is listed in the following format:
:module ''module-name''
:module ''module-name''
::module-options
::module-options
:end module
:end module


The ''module-name'' is how kdesvn-build refers to the module. It should match the name of the module you are downloading from the source repository. Base KDE modules are listed [http://websvn.kde.org/trunk/KDE/ in WebSVN].  Other modules are also available [http://websvn.kde.org/trunk/ in WebSVN].
The ''module-name'' is how kdesrc-build refers to the module. It should match the name of the module you are downloading from the source repository. Base KDE modules are listed [http://websvn.kde.org/trunk/KDE/ in WebSVN].  Other modules are also available [http://websvn.kde.org/trunk/ in WebSVN].


One exception is that modules downloaded from git can have any module name you'd like that isn't already used, as kdesvn-build determines their download location using a specific ''repository'' option.
One exception is that modules downloaded from git can have any module name you'd like that isn't already used, as kdesrc-build determines their download location using a specific ''repository'' option.


For each module you can specify options, in the same fashion as for the global options. Most of the time, if you set an option for a module, it completely overrides the global option, if any.
For each module you can specify options, in the same fashion as for the global options. Most of the time, if you set an option for a module, it completely overrides the global option, if any.
Line 66: Line 63:
However, the cmake-options for a module is added to the global cmake-options, instead of replacing it, which allows you to avoid having to give the same cmake-options for all of your modules.
However, the cmake-options for a module is added to the global cmake-options, instead of replacing it, which allows you to avoid having to give the same cmake-options for all of your modules.


{{tip|If you need to disable a global cmake-option, you can specify it again for the module you need to disable it for, and give it the opposite value. For instance, if you were using CMAKE_BUILD_TYPE=debugfull globally but wanted Release mode for kdebindings, you could set cmake-options -DCMAKE_BUILD_TYPE=Release for kdebindings.}}
{{tip|If you need to disable a global cmake-option, you can specify it again for the module you need to disable it for, and give it the opposite value. For instance, if you were using }}-DCMAKE_BUILD_TYPE=debugfull globally but wanted Release mode for kdebindings, you could set cmake-options -DCMAKE_BUILD_TYPE=Release for kdebindings.


{{tip|If you get the warning from kdesvn-build that a certain module is not listed in the kdesvn-buildrc, make sure that you've added it to the kdesvn-buildrc, even if you have no options for it. If it's already in the kdesvn-buildrc, make sure you spelled the module name right on the command line.}}
{{tip|If you get the warning from kdesrc-build that a certain module is not listed in the kdesrc-buildrc, make sure that you've added it to the kdesrc-buildrc, even if you have no options for it. If it's already in the kdesrc-buildrc, make sure you spelled the module name right on the command line.}}


==== qt-copy ====
==== qt-copy ====


The qt-copy module is special in that it uses configure-options instead of cmake-options, and it never inherits compilation flags that are set globally, since Qt uses a different build system than KDE software does.  The sample kdesvn-buildrc contains a useful set of default configure flags, but if you aren't using qt-copy, you can simply comment the entire qt-copy module out.
The qt-copy module is special in that it uses configure-options instead of cmake-options, and it never inherits compilation flags that are set globally, since Qt uses a different build system than KDE software does.  The sample kdesrc-buildrc contains a useful set of default configure flags, but if you aren't using qt-copy, you can simply comment the entire qt-copy module out.


Since Nokia's Qt is developed using git instead of Subversion, you must specify the ''repository'' option for qt-copy to choose which version of Qt you will use:
Since Nokia's Qt is developed using git instead of Subversion, you must specify the ''repository'' option for qt-copy to choose which version of Qt you will use:
Line 88: Line 85:
Either way you should specify a ''branch'' of ''master'' to choose the default version.
Either way you should specify a ''branch'' of ''master'' to choose the default version.


If you choose kde-qt make sure to look at the README.kde-qt after kdesvn-build downloads the module for you as well!
If you choose kde-qt make sure to look at the README.kde-qt after kdesrc-build downloads the module for you as well!


=== Location ===
=== Location ===


kdesvn-build will search in several locations for your rc file.
kdesrc-build will search in several locations for your rc file.


# First, kdesvn-build will look for a file called {{path|kdesvn-buildrc}} in ''the current directory''.  Notice that in this situation there is no leading dot on the filename.  This allows you to control the build based on what directory you're in, which would be useful for maintaining two different Subversion installs.
# First, kdesrc-build will look for a file called {{path|kdesrc-buildrc}} in ''the current directory''.  Notice that in this situation there is no leading dot on the filename.  This allows you to control the build based on what directory you're in, which would be useful for maintaining two different Subversion installs.
# If no kdesvn-buildrc is found, kdesvn-build will look for a {{path|~/.kdesvn-buildrc}}.  Notice there '''is''' a leading dot on the filename in this situation.  This is the standard Linux/UNIX convention for configuration files stored in the home directory, and marks this as a hidden file.  So if you try to find the file in Dolphin or Konqueror, you may need to Show Hidden Files first.  This controls the default configuration kdesvn-build will use, no matter what directory you run kdesvn-build from.
# If no kdesrc-buildrc is found, kdesrc-build will look for a {{path|~/.kdesrc-buildrc}}.  Notice there '''is''' a leading dot on the filename in this situation.  This is the standard Linux/UNIX convention for configuration files stored in the home directory, and marks this as a hidden file.  So if you try to find the file in Dolphin or Konqueror, you may need to Show Hidden Files first.  This controls the default configuration kdesrc-build will use, no matter what directory you run kdesrc-build from.
# If you specify the --rc-file option to kdesvn-build, kdesvn-build will try to read the given kdesvn-buildrc file instead of the default ones.  This is also independent of what directory kdesvn-build is run in.  But, you must remember to pass this option every time, so it is only useful for testing or for a one-time-only run.
# If you specify the --rc-file option to kdesrc-build, kdesrc-build will try to read the given kdesrc-buildrc file instead of the default ones.  This is also independent of what directory kdesrc-build is run in.  But, you must remember to pass this option every time, so it is only useful for testing or for a one-time-only run.


=== Making changes ===
=== Making changes ===


When you make changes to values in your kdesvn-buildrc, they may not always be picked up immediately.  For example, if you change cmake-options but kdesvn-build has no reason to run CMake again, then you'll still be building with your old cmake-options.
When you make changes to values in your kdesrc-buildrc, they may not always be picked up immediately.  For example, if you change cmake-options but kdesrc-build has no reason to run CMake again, then you'll still be building with your old cmake-options.


{{note|This is only partially true -- kdesvn-build will be able to note that some values have changed and automatically re-run affected build portions as appropriate, but this advice still applies until this feature has been integrated for all options}}
{{note|This is only partially true -- kdesrc-build will be able to note that some values have changed and automatically re-run affected build portions as appropriate, but this advice still applies until this feature has been integrated for all options}}


The safest way to ensure that a change to your module's options is picked up is to use the --refresh-build option when rebuilding a module. This option causes kdesvn-build to completely rebuild the given module, which includes running cmake and clearing out the build directory.
The safest way to ensure that a change to your module's options is picked up is to use the --refresh-build option when rebuilding a module. This option causes kdesrc-build to completely rebuild the given module, which includes running cmake and clearing out the build directory.


Using --refresh-build takes the most time. Often, it is enough to use --reconfigure instead of --refresh-build, which runs CMake but does not clear out the build directory. But if --reconfigure doesn't work you'll end up doing --refresh-build anyways.
Using --refresh-build takes the most time. Often, it is enough to use --reconfigure instead of --refresh-build, which runs CMake but does not clear out the build directory. But if --reconfigure doesn't work you'll end up doing --refresh-build anyways.


On the other hand, if you change the svn-server option to move where kdesvn-build is downloading from, you need to run kdesvn-build one time with the --svn-only option, so that kdesvn-build can perform the correct "svn switch" command.
On the other hand, if you change the svn-server option to move where kdesrc-build is downloading from, you need to run kdesrc-build one time with the --svn-only option, so that kdesrc-build can perform the correct "svn switch" command.


=== Conclusion ===
=== Conclusion ===


The kdesvn-buildrc file is one of the major reasons to use kdesvn-build instead of building manually, as it will allow you to specify build settings to use all of the time instead of having to always remember to type in the correct command line settings and export the right environment variables. There are many more options than the ones covered here, which are mostly [http://kdesvn-build.kde.org/documentation/ detailed at the kdesvn-build documentation]. However, these options are enough to get you a working KDE installation.
The kdesrc-buildrc file is one of the major reasons to use kdesrc-build instead of building manually, as it will allow you to specify build settings to use all of the time instead of having to always remember to type in the correct command line settings and export the right environment variables. There are many more options than the ones covered here, which are mostly [http://kdesrc-build.kde.org/documentation/ detailed at the kdesrc-build documentation]. However, these options are enough to get you a working KDE installation.

Latest revision as of 20:54, 10 March 2016

Warning
This page is currently partly outdated. For more up to date instructions visit the kdesrc-build Script Manual and the Community Wiki: Building KDE Frameworks.

kdesrc-buildrc

This page introduces how to configure kdesrc-build

Creating your configuration

The kdesrc-build download will include a file called kdesrc-buildrc-sample, which is a sample configuration file suitable for building the KDE Software Compilation (SC).

To create your configuration, it is recommended to use this file as a base since it includes the standard list of KDE modules to build, in the correct order. (You can, of course, add or remove most modules if you like).

You can use any standard text editor to edit this file, such as KWrite, nano, vi, etc.

You can even use the convenient kdesrc-build-setup Script which asks some question and puts your answers into the configuration file.

Global configuration

Once you open the file, you will see that it starts with some comments (on lines beginning with #), and then the world "global". This starts the global configuration for the kdesrc-buildrc, which is used to specify options which are common to all of the modules.

Each option in the global section is specified in the following form:

option-name value

Many options are already listed, with default values, and comments about the option on top. Some options have more than one sample value listed. In this situation, all but one of these will have comments. If you want to use a different sample option, simply uncomment the line by deleting the '#' at the beginning, and commenting or deleting the other lines with the same option name.

Here's a short listing of some of the important global options:

  • source-dir: This option controls where kdesrc-build will download the sources to. In addition, most other directories that kdesrc-build uses will be subdirectories of this directory by default, so it is a kind of "kdesrc-build prefix". The default value is ~/kdesrc, which downloads the source in a subdirectory under your home directory.
  • build-dir: This controls where kdesrc-build actually builds the various modules. Normally it is the directory build under your source directory.
  • kdedir: This controls where the KDE SC (and the various supporting modules such as kdesupport) get installed to. The default is ~/kde, which installs to your home directory.
Note
As you can see, there are three different major directories, source, build, and install. The build directory is used to keep the source directory clean and to hold intermediate files that don't get installed


Tip
You can use ~/ in these options to represent your home directory


  • qtdir: This controls where Qt 4 is assumed to be. If you use the qt-copy module, it also controls where qt-copy is installed to. Default is ~/qt4, which installs qt-copy to your home directory.
Tip
qt-copy is a module specifically for building Nokia's Qt toolkit. See #qt-copy below for information about what is special.


  • cmake-options: This controls what options are passed to CMake for every KDE module. For instance, if you want to enable full debugging information, you could set:
cmake-options -DCMAKE_BUILD_TYPE=debugfull
  • make-options: This is used to pass command line options to the make command, which is what actually performs the build. The most likely option is -jN, where N is the number of jobs to perform at once. If you have a system with more than one CPU, it is recommended to use N = number_of_CPUs + 1. For instance, -j3 on a dual core machine or -j5 on a quad-core. You can lower this number if your system is sluggish during the build, but raising it won't buy you much in build speed.
  • make-install-prefix: This is used to allow a program to run make install on your behalf. Normally with would be the sudo program, which is used to perform actions with administrator permissions. You only need this for the following:
  1. You want to install KDE to the system and not your home directory.
  2. Some installed files require elevated permissions to work properly (this is true for kdebase, and some files in kdelibs).

If this is the case for you, you can use this option (either globally, or for each module) to run make install using sudo, or su, etc.

Module configuration

After the global options are all done, you'll see the line "end global", which lets kdesrc-build know that all of the global options have been read.

Next in the kdesrc-buildrc are the module options. First off, modules are listed in the file, in the order they are to be built and installed. Each module is listed in the following format:

module module-name
module-options
end module

The module-name is how kdesrc-build refers to the module. It should match the name of the module you are downloading from the source repository. Base KDE modules are listed in WebSVN. Other modules are also available in WebSVN.

One exception is that modules downloaded from git can have any module name you'd like that isn't already used, as kdesrc-build determines their download location using a specific repository option.

For each module you can specify options, in the same fashion as for the global options. Most of the time, if you set an option for a module, it completely overrides the global option, if any.

However, the cmake-options for a module is added to the global cmake-options, instead of replacing it, which allows you to avoid having to give the same cmake-options for all of your modules.

Tip
If you need to disable a global cmake-option, you can specify it again for the module you need to disable it for, and give it the opposite value. For instance, if you were using

-DCMAKE_BUILD_TYPE=debugfull globally but wanted Release mode for kdebindings, you could set cmake-options -DCMAKE_BUILD_TYPE=Release for kdebindings.

Tip
If you get the warning from kdesrc-build that a certain module is not listed in the kdesrc-buildrc, make sure that you've added it to the kdesrc-buildrc, even if you have no options for it. If it's already in the kdesrc-buildrc, make sure you spelled the module name right on the command line.


qt-copy

The qt-copy module is special in that it uses configure-options instead of cmake-options, and it never inherits compilation flags that are set globally, since Qt uses a different build system than KDE software does. The sample kdesrc-buildrc contains a useful set of default configure flags, but if you aren't using qt-copy, you can simply comment the entire qt-copy module out.

Since Nokia's Qt is developed using git instead of Subversion, you must specify the repository option for qt-copy to choose which version of Qt you will use:

Qt Variants
Edition to build Repository to use
Official Nokia Qt git://gitorious.org/qt/qt.git
Slightly modified Qt with KDE-specific patches and bugfixes (recommended if you're going to the trouble anyways) git://gitorious.org/+kde-developers/qt/kde-qt.git

Either way you should specify a branch of master to choose the default version.

If you choose kde-qt make sure to look at the README.kde-qt after kdesrc-build downloads the module for you as well!

Location

kdesrc-build will search in several locations for your rc file.

  1. First, kdesrc-build will look for a file called kdesrc-buildrc in the current directory. Notice that in this situation there is no leading dot on the filename. This allows you to control the build based on what directory you're in, which would be useful for maintaining two different Subversion installs.
  2. If no kdesrc-buildrc is found, kdesrc-build will look for a ~/.kdesrc-buildrc. Notice there is a leading dot on the filename in this situation. This is the standard Linux/UNIX convention for configuration files stored in the home directory, and marks this as a hidden file. So if you try to find the file in Dolphin or Konqueror, you may need to Show Hidden Files first. This controls the default configuration kdesrc-build will use, no matter what directory you run kdesrc-build from.
  3. If you specify the --rc-file option to kdesrc-build, kdesrc-build will try to read the given kdesrc-buildrc file instead of the default ones. This is also independent of what directory kdesrc-build is run in. But, you must remember to pass this option every time, so it is only useful for testing or for a one-time-only run.

Making changes

When you make changes to values in your kdesrc-buildrc, they may not always be picked up immediately. For example, if you change cmake-options but kdesrc-build has no reason to run CMake again, then you'll still be building with your old cmake-options.

Note
This is only partially true -- kdesrc-build will be able to note that some values have changed and automatically re-run affected build portions as appropriate, but this advice still applies until this feature has been integrated for all options


The safest way to ensure that a change to your module's options is picked up is to use the --refresh-build option when rebuilding a module. This option causes kdesrc-build to completely rebuild the given module, which includes running cmake and clearing out the build directory.

Using --refresh-build takes the most time. Often, it is enough to use --reconfigure instead of --refresh-build, which runs CMake but does not clear out the build directory. But if --reconfigure doesn't work you'll end up doing --refresh-build anyways.

On the other hand, if you change the svn-server option to move where kdesrc-build is downloading from, you need to run kdesrc-build one time with the --svn-only option, so that kdesrc-build can perform the correct "svn switch" command.

Conclusion

The kdesrc-buildrc file is one of the major reasons to use kdesrc-build instead of building manually, as it will allow you to specify build settings to use all of the time instead of having to always remember to type in the correct command line settings and export the right environment variables. There are many more options than the ones covered here, which are mostly detailed at the kdesrc-build documentation. However, these options are enough to get you a working KDE installation.