diff --git a/doc/index.docbook b/doc/index.docbook index 918b5f6..4199841 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -141,30 +141,31 @@ directly from the &kde; project's source code repositories. What is &kdesrc-build;? -&kdesrc-build; is a script to help users install &kde; software from its &subversion; and &git; source repositories. - +url="https://git-scm.com/">&git; and &subversion; source repositories, +and continue to update that software afterwards. +It is particularly intended to support those who need to supporting testing and +development of &kde; software, including users testing bugfixes and developers +working on new features. -In addition to simply installing &kde; software, the script can also be -used to update the installed &kde; software after it is installed. This allows -you to keep up-to-date with &kde; development. +The &kdesrc-build; script can be configured to maintain a single individual +module, a full &plasma; desktop with &kde; application set, or somewhere in between. -The &kdesrc-build; script can be used to maintain a single individual -module or an entire &kde; desktop depending on how it is configured. +To get started, see , or continue reading for more +detail on how &kdesrc-build; works and what is covered in this documentation. &kdesrc-build; operation <quote>in a nutshell</quote> -&kdesrc-build; intentionally works by using the same tools available to -the user at the command-line. When &kdesrc-build; is run, the following -sequence is followed: - +&kdesrc-build; works by using the tools available to the user at the +command-line, using the same interfaces available to the user. When +&kdesrc-build; is run, the following sequence is followed: &kdesrc-build; reads in the command @@ -177,8 +178,22 @@ linkend="module-concept">module. The update continues until all modules have been updated. Modules that fail to update normally do not stop the build – you will be notified at the end which modules did not update. + +Modules that were successfully updated are built, have their +test suite run, and are then installed. To reduce the overall time spent, +&kdesrc-build; will by default start building the code as soon as the first +module has completed updating, and allow the remaining updates to continue +behind the scenes. + +A very good overview of how &kde; modules are +built, including informative diagrams, is provided on an online article discussing &kde;'s &krita; application. This +workflow is what &kdesrc-build; automates for all &kde; modules. + + @@ -200,8 +215,7 @@ and options. Also documented are the steps which you should perform using -other tools, (in other words, steps that are not automatically performed by -&kdesrc-build;). +other tools (&ie; steps that are not automatically performed by &kdesrc-build;). @@ -243,15 +257,14 @@ would be to create a different (dedicated) user to build and run the new &kde;. Leaving your system &kde; untouched also allows you to have an -emergency fallback in case a compiled &kde; is unstable for whatever reason. +emergency fallback in case a coding mistake causes your latest software build +to be unusable. -Later, you can do a system installation if you wish. This document -does not cover a system installation. If you are performing a system -wide install, you should already know what you are doing. If not, then you -may want to consult the documentation, or help sites, for your distribution -in order to prepare and use the system installation correctly. +You can do also setup to install to a system-wide directory (⪚ /usr/src/local) if you wish. This document +does not cover this installation type, since we assume you know what you are doing. @@ -268,26 +281,21 @@ Community Wiki Build Requirements page. Here is a list of some of the things you will need: -You will need &cmake;. The required version will vary -depending on what version of &kde; 4 you are building, see TechBase for -specifics, however a good bet is to have the most recent available version. -&cmake; is the program used by &kdesrc-build; to handle the actual -configuration and build steps for the vast majority of &kde; software. +You will need &cmake;, this software is what &kde; uses to handle +build-time configuration of the source code and generation of the specific build +commands for your system. The required version will vary +depending on what versions of &kde; software you are building (see TechBase for +specifics), but with modern distributions the &cmake; included with your distribution +should be quite sufficient. -You must also install the client software used to checkout +You must also install the source control clients needed to checkout the &kde; source code. This means you need at least the following: -&subversion;, which used to be the only source code manager in use, and is still -used for some modules with large data files. You can check -if you have it by running svn -. - -You will need the Git -source control manager installed as well, for &kde;'s git-based projects. - +The Git +source control manager, which is used for all &kde; source code Although it is not required, the Bazaar source control manager is @@ -295,18 +303,45 @@ used for a single module (libdbusmenu-qt) that is required for the &kde; libraries. Most users can install this library through their distribution packages but &kdesrc-build; supports building it as well if you desire. But to build libdbusmenu-qt, you must have Bazaar installed. - -You will need a full C++ development environment. GCC 4.6 or -later is recommended. +The Perl scripting language is required for &kdesrc-build;, some &kde; +repositories, and &Qt; (if you build that from source). + +The Perl that comes with your distribution should be suitable (it needs to be at +least Perl 5.14), but you will also need some additional modules (&kdesrc-build; +will warn if they are not present): -Finally, you will need a make tool. GNU Make is -recommended and should be available through your package manager. After -cmake has been run by &kdesrc-build;, -make handles actually running the build process, which is -why it is required. + + IO::Socket::SSL + JSON::PP or JSON::XS + YAML::PP, YAML::XS, or YAML::Syck + + + +You will need a full C++ development environment (compiler, standard library, runtime, +and any required development packages). The minimum required versions vary based on the &kde; module: +the &kde; Frameworks 5 collection supports the oldest compilers, while &kde; Plasma 5 and &kde; Applications +tend to require more recent compilers. +The GCC 4.8 or Clang 4 compilers are the minimum recommended. Many distributions support easily +installing these tools using a build-essentials package, an option to install +"build dependencies" with &Qt;, or similar features. The KDE Community Wiki has a page tracking +recommended packages for major distributions. + + + +You will need a build tool that actually performs the +compilation steps (as generated by &cmake;). GNU Make is recommended and should +be available through your package manager. &cmake; does support others options, such +as the "ninja" build tool, which can be used by &kdesrc-build; using the +custom-build-command configuration file +option. + +Finally, you will need the appropriate &Qt; libraries (including development packages) +for the version of &kde; software you are building. &kdesrc-build; does not officially support building &Qt; 5 (the current major version), so it is recommended to use your distribution's development packages or to +see the KDE Community wiki page on self-building Qt 5. + Most operating system distributions include a method of easily @@ -315,46 +350,10 @@ url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_r >Required devel packages to see if these instructions are already available. -One exception to the required libraries is the &Qt; library. -&kdesrc-build; will normally install a copy of &Qt; whether you have it -installed or not, so it is not necessary for you to have it. If you do not want -to use the &Qt; copy, you need to do these things: - - - - Make sure to remove the qt module from your configuration file, as you will not need it, - and having it would add extra time to your build. - - - - Change the setting of the qtdir - option in your configuration file to - point to your system &Qt;. The location of your system &Qt; can be found - by running qmake - . - - The qmake command might be called - qmake4 or qmake-qt4 on your - distribution. - - - - If you do not already have &Qt; installed, install it, including any - relevant -dev or -devel packages. You will need at least - &Qt; 4.7 if you are building &kde; 4. - - - Some of these packages are divided into libraries (or programs or utilities), and development packages. You will need at least the program or library -and its development package. The libraries you need will -change depending on the modules you intend to build, as each module has its own -requirements. The &kde; -Community wiki has more details about the specific tools and techniques used -to install and find the required software. +and its development package. @@ -365,41 +364,32 @@ to install and find the required software. Install &kdesrc-build; -You probably already have a version of the &kdesrc-build; script installed -in your system. However, if you do not, you can download it from -&kdesrc-build; home page, -or you can find it from its home in the &kde; source repository. +The &kde; developers make frequent changes to &kdesrc-build; to keep it in +sync with advances in &kde; development, including improvements to the +recommended &kdesrc-build; configuration, added modules, improving &cmake; +flags, &etc; -If you use a more recent &kdesrc-build; by downloading from its -website, you should remember to run the &kdesrc-build; script you downloaded. -You can use the option to &kdesrc-build; as a quick -way to verify this. +Because of this, we recommend obtaining &kdesrc-build; directly from its +source repository and then periodically updating it. - -To download &kdesrc-build; from its home page, simply go to the -&kdesrc-build; home page and download the latest appropriate release. The release is -packaged as a compressed tarball archive, which you can extract using &ark; or -tar. The contents of the archive include the actual -&kdesrc-build; script, a sample configuration file -(kdesrc-buildrc-sample), and a quick-setup -program. - -Or, you can obtain &kdesrc-build; from its source repository, -by running: +You can obtain &kdesrc-build; from its source repository by running: $ git Replace with the directory you would like to install to. - - + + +You can update &kdesrc-build; later by running: + +$ cd +$ git + -No matter which technique you use, you need to make sure that the -kdesrc-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, or you may run a previously-installed version by mistake. +We recommend adding the &kdesrc-build; installation directory to +your PATH environment variable, so that you can run &kdesrc-build; +without having to fully specify its path every time. @@ -419,12 +409,26 @@ fit. (instead of using a graphical interface), just like &kdesrc-build;, so you can use it even if you have no graphical interface available yet. -You can use the included kdesrc-buildrc-sample -sample configuration to get explanations as to the various options available. - + +Manual setup of configuration file + +You can also setup your configuration file manually, by copying the +included sample configuration file +kdesrc-buildrc-kf5-sample to +~/.kdesrc-buildrc and then editing the file. will be a useful reference for this, especially its +table of configuration options. + + -You can find more information about the syntax of the configuration file -in and in . +&kdesrc-build; contains many recommended configuration files to support +&kde; Frameworks 5, &plasma; 5, and other &kde; applications. The kdesrc-build-setup refers to these files in the configuration file it generates, but you can also use them +yourself. See for information on how +to use other configuration files from your own ~/.kdesrc-buildrc. + +You can find more information about the syntax of the configuration file in and in . @@ -447,51 +451,422 @@ configuration is stored in ~/.kdesrc-buildrc. The easiest way to proceed is to use the -kdesrc-buildrc-sample file as a template, changing global +kdesrc-buildrc-kf5-sample file as a template, changing global options to match your wants, and also change the list of modules you want to build. -The default settings should actually already be appropriate to perform a +The default settings should be appropriate to perform a &kde; build. Some settings that you may wish to alter include: + -use-stable-kde to -change the default version of &kde; modules to build. By default &kdesrc-build; -will build the trunk version of &kde;. If you want to build -the latest stable release of &kde; instead of using your distribution packages -you would set this option to true. +kdedir, which changes the +destination directory that your &kde; software is installed to. This defaults to +~/kde, which is a single-user +installation. + +branch-group, which can +be +used to choose the appropriate branch of development for the &kde; modules as a +whole. There are many supported build configurations but you will likely want to +choose so that &kdesrc-build; downloads the latest code +based on &Qt; 5 and &kde; Frameworks 5. + +&kdesrc-build; will use a default branch group if you do not choose +one, but this default will change over time, so it's better to choose one so +that the branch group does not change unexpectedly. + + +source-dir, to control the directory +&kdesrc-build; uses for downloading the source code, running the build process, and saving +logs. +This defaults to ~/kdesrc. + +cmake-options, which +sets the options to pass to the &cmake; command when building each module. +Typically this is used to set between debug or +release builds, to enable (or disable) optional features, or to +pass information to the build process about the location of required libraries. + + +make-options, which +sets the options used when actually running the make +command to build each module (once &cmake; has established the build system). -Note that this option relies on information available from the -&kde; project database, so this feature only works for these modules. -See also . - - +The most typical option is , +where N should be replaced with the maximum number of +compile jobs you wish to allow. A higher number (up to the number of logical CPUs +your system has available) leads to quicker builds, but requires more system resources. + -kdedir, which changes the -destination directory that &kde; is installed to. This defaults to -~/kde, which is a single-user installation. + +Configuring Make for 4 compiles at once, with exceptions + +global + make-options -j4 + … +end global -qtdir, which controls the -path to the installation of &Qt; to use. The default is to use a &Qt; compiled -by &kdesrc-build;, using the special qt module and the latest available -source code. -(~/kdesrc/build/qt). +… -This also controls where to install qt. - +module-set big-module-set + repository kde-projects + use-modules calligra + make-options -j2 # Reduced number of build jobs for just these modules +end module-set + + -svn-server, which -selects what &url; to download the sources from. This is useful if you are a -developer with a &kde; -contributor account. +Some very large Git repositories may swamp your system if you try to +compile with a too many build jobs at one time, especially repositories like the +&Qt; WebKit and &Qt; WebEngine repositories. To maintain system interactivity +you may have to reduce the number of build jobs for specific modules. + gives an example of how to do +this. + -You will probably want to select different modules to build, which -is described in . + + +You may want to select different modules to build, +which is described in . + + + + +Using the &kdesrc-build; script +With the configuration data established, now you are ready to run the +script. Even if you still have some tweaking or other reading you wish to do, +it is a good idea to at least load the &kde; project metadata. + + +Loading project metadata + + +From a terminal window, log in to the user you are using to compile &kde; and +execute the script: + + + % kdesrc-build + + +This command will setup the source directory and connect to the KDE &git; +repositories to download the database of &kde; git repositories, and the +database of dependency metadata, without making any further changes. It is +useful to run this separately as this metadata is useful for other +&kdesrc-build; commands. + + + + +Previewing what will happen when kdesrc-build runs + +With the project metadata installed, it is possible to preview what +&kdesrc-build; will do when launched. This can be done with the command line option. + + + % ./kdesrc-build + + +You should see a message saying that some packages were successfully built (although + nothing was actually built). If there were no significant problems shown, you can proceed + to actually running the script. + + + + + % kdesrc-build + + +This command will download the appropriate source code, and build and install each module in order, but will stop if a module fails to build (due to the option). Afterwards, you should see output similar to that in : + + +Example output of a kdesrc-build run + +% kdesrc-build +Updating kde-build-metadata (to branch master) +Updating sysadmin-repo-metadata (to branch master) + +Building libdbusmenu-qt (1/200) + No changes to libdbusmenu-qt source, proceeding to build. + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + +Building taglib (2/200) + Updating taglib (to branch master) + Source update complete for taglib: 68 files affected. + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + +Building extra-cmake-modules from <module-set at line 32> (3/200) + Updating extra-cmake-modules (to branch master) + Source update complete for extra-cmake-modules: 2 files affected. + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + + ... + +Building kdevelop from kdev (200/200) + Updating kdevelop (to branch master) + Source update complete for kdevelop: 29 files affected. + Compiling... succeeded (after 1 minute, and 34 seconds) + Installing.. succeeded (after 2 seconds) + +<<< PACKAGES SUCCESSFULLY BUILT >>> +Built 200 modules + +Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07 + + + + +Resolving build failures + + +Depending on how many modules you are downloading, it is possible that +&kdesrc-build; will not succeed the first time you compile &kde;. Do not +despair! + + +&kdesrc-build; logs the output of every command it runs. By default, +the log files are kept in ~/kdesrc/log. To see what +the caused an error for a module in the last &kdesrc-build; command, usually +it is sufficient to look at ~/kdesrc/log/latest/module-name/error.log. + +Perhaps the easiest way to find out what error caused a module to +fail to build is to search backward with a case-insensitive search, starting +from the end of the file looking for the word error. Once +that is found, scroll up to make sure there are no other error messages nearby. +The first error message in a group is usually the underlying +problem. + +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 are missing some +packages, try installing the package (including any appropriate -dev packages) +before trying to build that module again. Make sure that when you run +&kdesrc-build; again to pass the --reconfigure option so that +&kdesrc-build; forces the module to check for the missing packages +again. + +Or, if the error appears to be a build error (such as a syntax error, +incorrect prototype, unknown type, or similar) +then it is probably an error with the &kde; source, which will hopefully be +resolved within a few days. If it is not resolved within that time, feel free +to mail the kde-devel@kde.org mailing list (subscription may be +required first) in order to report the build failure. + +You can find more common examples of things that can go wrong and their +solutions, as well as general tips and strategies to build &kde; in the + +Build from Source. + + + + +On the other hand, assuming everything went well, you should have a new +&kde; install on your computer, and now it is simply a matter of running +it, described next in . + +For more information about &kdesrc-build;'s logging features, +please see . + + + + +Building specific modules + +Rather than building every module all the time, you may only want to build a single + module, or other small subset. Rather than editing your configuration file, you can simply + pass the names of modules or module sets to build to the command line. + + +Example output of a kdesrc-build specific module build + + % kdesrc-build dolphin +Updating kde-build-metadata (to branch master) +Updating sysadmin-repo-metadata (to branch master) + +Building extra-cmake-modules from frameworks-set (1/79) + Updating extra-cmake-modules (to branch master) + No changes to extra-cmake-modules source, proceeding to build. + Running cmake... + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + +Building phonon from phonon (2/79) + Updating phonon (to branch master) + No changes to phonon source, proceeding to build. + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + +Building attica from frameworks-set (3/79) + Updating attica (to branch master) + No changes to attica source, proceeding to build. + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + + ... + +Building dolphin from base-apps (79/79) + Updating dolphin (to branch master) + No changes to dolphin source, proceeding to build. + Compiling... succeeded (after 0 seconds) + Installing.. succeeded (after 0 seconds) + +<<< PACKAGES SUCCESSFULLY BUILT >>> +Built 79 modules + +Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07 + + + +In this case, although only the dolphin +application was specified, the flag +caused &kdesrc-build; to include the dependencies listed for +dolphin (by setting the include-dependencies option). + + +The dependency resolution worked in this case only becase +dolphin happened to be specified in a +kde-projects-based module set (in this example, named +base-apps). See . + + + + + +Setting the Environment to Run Your &kde; &plasma; Desktop + + +Assuming you are using a dedicated user to build &kde;, and you already have an +installed &kde; version, running your new &kde; may be a bit tricky, as the new +&kde; has to take precedence over the old. You must change the environment +variables of your login scripts to make sure the newly-built desktop is used. + + +Automatically installing a login driver + +Starting from version 1.16, &kdesrc-build; will try to install an +appropriate login driver, that will allow you to login to your +&kdesrc-build;-built &kde; desktop from your login manager. This can be +disabled by using the +configuration file option. + +Session setup does not occur while &kdesrc-build; is running +in pretend mode. + +This driver works by setting up a custom xsession +session type. This type of session should work by default with the &kdm; login +manager (where it appears as a Custom session), but other login +managers (such as LightDM and +gdm) may require additional files installed to +enable xsession support. + + +Adding xsession support for distributions + +The default login managers for some distributions may require additional +packages to be installed in order to support xsession logins. + + +The Fedora +&Linux; distribution requires the xorg-x11-xinit-session +package to be installed for custom xsession login +support. + +Debian and +Debian-derived &Linux; distributions should support custom +xsession logins, but require the + option to be set in +/etc/X11/Xsession.options. See also the Debian documentation +on customizing the X session. + +For other distributions, go to . + + + + + +Manually adding support for xsession + +If there were no distribution-specific directions for your distribution +in , you can manually add a +Custom xsession login entry to your distribution's list of +session types as follows: + + +Adding an .xsession login session type. + +This procedure will likely require administrative privileges to +complete. + + + +Create the file +/usr/share/xsessions/kdesrc-build.desktop. + + + +Ensure the file just created has the following text: + +Type=XSession +Exec=$HOME/.xsession +Name=KDE Plasma Desktop (unstable; kdesrc-build) + + + + +The $HOME entry must be replaced by the full path to +your home directory (example, /home/user). The +desktop entry specification does not allow for user-generic files. + + + + + +When the login manager is restarted, it +should show a new session type, KDE Plasma Desktop (unstable; +kdesrc-build) in its list of sessions, which should try to run the +.xsession file installed by &kdesrc-build; if it is +selected when you login. + +It may be easiest to restart the computer to restart the login +manager, if the login manager does not track updates to the /usr/share/xsessions directory. + + + + + + + + + + +Setting up the environment manually +This documentation used to include instruction on which environment +variables to set in order to load up the newly-built desktop. These +instructions have been moved to an appendix (). + +If you intend to setup your own login support you can consult that +appendix or view the sample-kde-env-master.sh file +included with the &kdesrc-build; source. + + + @@ -516,53 +891,40 @@ system if it is a recent enough version. On top of &Qt; are required libraries that are necessary for &kde; software to work. Some of these libraries are not considered part of &kde; itself due to their generic nature, but are still essential to the &kde; -Platform. These libraries tended to get combined into a single -kdesupport module. - -As of &kde; Platform 4.6, many of the libraries in the kdesupport -module are being migrated over to the &kde; git archive, although they are still not -considered part of the Platform. +Platform. These libraries are collected under a kdesupport +module grouping but are not considered part of the Frameworks +libraries. -On top of these essential libraries comes the &kde; Platform. -These are the libraries that are required for &kde; applications to work. A -full desktop environment is not provided by the Platform however. - - -For &kdesrc-build;, the Platform layer consists of the kdelibs, -kdepimlibs, and kde-runtime modules. - +On top of these essential libraries come the &kde; Frameworks, sometimes +abbreviated as KF5, which are essential libraries for the &kde; Plasma desktop, +&kde; Applications, and other third-party software. + -On top of the Platform, come several different things: +On top of the Frameworks, come several different things: Third-party applications. These are - applications that use the &kde; Platform but are not authored by or in - association with the &kde; project. - - A full workspace desktop environment. - This is what users normally see when they log-in to - &kde;. This is provided by the &plasma; Desktop, mostly in - kde-workspace. - - The &kde; Software Compilation. This is a collection of - useful software included with the Platform and &plasma; Desktop, - grouped into individual modules. These are the modules that have names - starting with kde. For example, - kdepim is a component of the Software Compilation - that contains email, news-reading, calendar/organizational software, - &etc;, while kdegames contains a collection of - high-quality games to while away the time. + applications that use the &kde; Frameworks or are designed to run under + &kde; Plasma but are not authored by or in association with the &kde; + project. + + Plasma, which is a full workspace desktop + environment. This is what users normally see when they log-in to + &kde;. + + The &kde; Application suite. This is a collection of + useful software included with the Platform and &plasma; Desktop, grouped into + individual modules, including utilities like &dolphin;, games like + KSudoku, and productivity software released by &kde; + such as &kontact;. Finally, there is a collection of software (also collected in modules) whose development is supported by &kde; resources (such as translation, source control, bug tracking, &etc;) but is not - released by &kde; or considered part of the Software Compilation. These - modules are known as Extragear, and have module names - such as extragear/network. As with - kdesupport, some of these Extragear applications are - migrating to the &kde; git archive. + released by &kde; as part of Plasma or the Application suite. These + modules are known as Extragear. + @@ -580,52 +942,40 @@ shown in . Example module entry in the configuration file -module module-name +module kdesrc-build-git # Options for this module go here, example: + repository kde:kdesrc-build make-options -j4 # Run 4 compiles at a time end module -It is possible to declare a module with no options. In fact, most of -your modules will likely be declared this way. - -&kdesrc-build; only builds the modules you have listed in your configuration -file. In addition, the modules are built in the order specified in the configuration -file. For this reason you should ensure that the order of modules in your -configuration file is consistent with the organization given in -. - -There is a sample file that comes with &kdesrc-build; called -kdesrc-buildrc-sample. It is recommended to copy this file -to a file called ~/.kdesrc-buildrc (Note the -leading period in front of kdesrc-buildrc!). Afterwards, edit the -new file to adjust the default options to your liking. (Each option is described -in more detail in ). The default modules -should be enough to ensure a fairly complete &kde; installation, however you -can remove many of the modules that show up after kdebase -if you'd like to save disk space or build time. +In practice, this module construct is not usually used directly. Instead +most modules are specified via module-sets as described below. + +When using only module entries, &kdesrc-build; builds them in the order +you list, and does not attempt to download any other repositories other than what you specify +directly. + Module Sets -&kdesrc-build; is usually able to guess where to download the source code -for a given module quite easily, by using your setting for svn-server and the module name for each module -to create a single Subversion URL, which describes exactly where to download -the source code from. +The &kde; source code is decomposed into a great number of relatively +small Git-based repositories. To make it easier to manage the large number of +repositories involved in any useful &kde;-based install, &kdesrc-build; supports +grouping multiple modules and treating the group as a module set. + -With the move to Git, many larger Subversion modules were further -sub-divided in the process, and there was no guarantee of where to find a -module based just on the module name. Because of this, a concept called -module sets was developed for &kdesrc-build; 1.12.1. + +The basic module set concept By using a module set, you can quickly declare many Git modules to be downloaded and built, as if you'd typed out a separate module declaration for each one. The repository option is -handled specially to setup where each module is downloaded from, which every +handled specially to setup where each module is downloaded from, and every other option contained in the module set is copied to every module generated in this fashion. @@ -661,45 +1011,78 @@ module name. In addition, other options can be passed in a module set, which are copied to every new module that is created this way. By using module-set it is possible to quickly declare many Git modules that are all based on the same -repository URL. In addition, since &kdesrc-build; 1.13, it is possible to -give module-sets a name (as shown in the example), which allows you to quickly -refer to the entire group of modules from the command line. +repository URL. In addition, it is possible to give module-sets a name (as shown +in the example), which allows you to quickly refer to the entire group of +modules from the command line. -Module sets are used in supporting module downloads from -the &kde; &kde; git archive -module database. See also . - + + +Special Support for KDE module sets + +The module set support described so far is general to any Git-based +modules. For the &kde; Git repositories, &kdesrc-build; includes additional +features to make things easier for users and developers. This support is +enabled by specifying kde-projects as the + for the module set. + + +&kdesrc-build; normally only builds the modules you have listed in your +configuration file, in the order you list them. But with a +kde-projects module set, &kdesrc-build; can do dependency +resolution of &kde;-specific modules, and in addition automatically include +modules into the build even if only indirectly specified. + + +Using kde-projects module sets + +# Only adds a module for juk (the kde/kdemultimedia/juk repo) +module-set juk-set + kde-projects + juk +end module-set + +# Adds all modules that are in kde/multimedia/*, including juk, +# but no other dependencies +module-set multimedia-set + kde-projects + kde/multimedia +end module-set + +# Adds all modules that are in kde/multimedia/*, and all kde-projects +# dependencies from outside of kde/kdemultimedia +module-set multimedia-deps-set + kde-projects + kde/multimedia + true +end module-set + +# All modules created out of these three module sets are automatically put in +# proper dependency order, regardless of the setting for include-dependencies + + + +This kde-projects module set construct is the main method +of declaring which modules you want to build. + + +All module sets use the repository +and use-modules options. kde-projects module +sets have a predefined value, but other types of +module sets also will use the git-repository-base option. + -Module sets use the options git-repository-base -use-modules -Automatically finding modules from the official &kde; module -database - -With the migration of &kde; source code to be hosted on git.kde.org, -there has been an explosive growth in the number of modules (for instance, -a single Subversion module called kdegraphics becomes -16 different Git modules). - -This was done mostly because each Git module contains the entire project -history (this is actually less wasteful of disk space than it sounds for the -vast majority of &kde; repositories as &git; is highly efficient at storing -repositories). - -&kde; allows for grouping Git repositories into collections -of related modules (e.g. kdegraphics). These modules can themselves be grouped -(e.g. &kde; Software Compilation). Git doesn't recognize these groupings, but -&kdesrc-build; can be configured to handle these groups. - -The way this is done is by using module -sets. Instead of using a specific git:// repository, -or a repository name created by git-repository-base, a special -repository name, kde-projects is used. +The official &kde; module database + +&kde;'s Git repositories allow for grouping related Git modules into +collections of related modules (e.g. kdegraphics). Git doesn't recognize these +groupings, but &kdesrc-build; can understand these groups, using module sets with a +option set to kde-projects. &kdesrc-build; will recognize that the kde-projects repository requires special handling, and adjust the build process @@ -707,18 +1090,18 @@ appropriately. Among other things, &kdesrc-build; will: -Download the latest module database from Download the latest module database from the &kde; git archive. Try to find a module with the name given in the module set's - setting. + setting in that database. -For every module that is found, &kdesrc-build; will see if a -repository setting exists for that module in the database. If there is a -repository, &kdesrc-build; will automatically use that to download or update -the source code. If there is no repository, &kdesrc-build; treats that module -like a group, and tries to include all &git; source repositories that it finds -in that group. +For every module that is found, &kdesrc-build; will lookup the +appropriate repository in the database, based upon the branch-group setting in effect. If a +repository exists and is active for the branch group, &kdesrc-build; will +automatically use that to download or update the source code. + @@ -782,16 +1165,11 @@ disabled module. list more than once. This allows us to manually set kdegraphics/libs to build first, before the rest of kdegraphics, without trying to build -kdegraphics/libs twice. +kdegraphics/libs twice. This used to be required for proper +dependency handling, and today remains a fallback option in case the &kde; +project database is missing dependency metadata. - -It is worth noting that &kdesrc-build; will try to build modules -in the right order, such as if only kdegraphics/* had been -listed above, but this depends on other databases being kept up-to-date. You -can manually list modules in the proper order if necessary by using the -technique described above. - @@ -807,7 +1185,7 @@ decide that you'd rather not download, build, and install kremotecontrol every time you update kdeutils. -As of &kdesrc-build; 1.16, you can achieve this by using the You can achieve this by using the ignore-modules configuration option. @@ -841,221 +1219,21 @@ end module-set - -Using the &kdesrc-build; script - - -Now you are ready to run the script. From a terminal window, -log in to the user you are using to compile &kde; and execute -the script: - -% kdesrc-build - - - -Afterwards, you should see output similar to that in : - - -Example output of building a single module - -% kdesrc-build -Script started processing at Wed Dec 22 13:21:45 2010 -<<< Build Process >>> -Building kdelibs (1/1) - Waiting for source code update. - Source update complete for kdelibs: 48 files affected. - Checking for source conflicts... - Compiling... - Build succeeded after 13 minutes, and 6 seconds. - Installing kdelibs. - Overall time for kdelibs was 13 minutes, and 53 seconds. - -<<< Build Done >>> - -<<< PACKAGES SUCCESSFULLY BUILT >>> -kdelibs - -Script finished processing at Wed Dec 22 13:35:38 2010 -Your logs are saved in /home/kde-src/log-kdesrc-build/2010-12-22-01 - - - - -At this point, &kdesrc-build; should start downloading the sources and -compiling them. Depending on how many modules you are downloading, it is -possible that &kdesrc-build; will not succeed the first time you compile &kde;. -Do not despair! - - -&kdesrc-build; logs the output of every command it runs. By default, -the log files are kept in ~/kdesrc/log. To see what -the caused an error for a module in the last &kdesrc-build; command, usually -it is sufficient to look at ~/kdesrc/log/latest/module-name/error.log. - -Perhaps the easiest way to find out what error caused a module to -fail to build is to search backward with a case-insensitive search, starting -from the end of the file looking for the word error. Once -that is found, scroll up to make sure there are no other error messages nearby. -The first error message in a group is usually the underlying -problem. - -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 are missing some -packages, try installing the package (including any appropriate -dev packages) -before trying to build that module again. Make sure that when you run -&kdesrc-build; again to pass the --reconfigure option so that -&kdesrc-build; forces the module to check for the missing packages -again. - -Or, if the error appears to be a build error (such as a syntax error, -incorrect prototype, unknown type, or similar) -then it is probably an error with the &kde; source, which will hopefully be -resolved within a few days. If it is not resolved within that time, feel free -to mail the kde-devel@kde.org mailing list (subscription may be -required first) in order to report the build failure. - -You can find more common examples of things that can go wrong and their -solutions, as well as general tips and strategies to build &kde; in the - -Build from Source. - - -On the other hand, assuming everything went well, you should have a new -&kde; install on your computer, and now it is simply a matter of running -it, described next in . - -For more information about &kdesrc-build;'s logging features, -please see . - - - - -Setting the Environment to Run Your &kde; &plasma; Desktop - - -Assuming you are using a dedicated user to build &kde;, and you already have an -installed &kde; version, running your new &kde; may be a bit tricky, as the new -&kde; has to take precedence over the old. You must change the environment -variables of your login scripts to make sure the newly-built desktop is used. - - - -Automatically installing a login driver - -Starting from version 1.16, &kdesrc-build; will try to install an -appropriate login driver, that will allow you to login to your -&kdesrc-build;-built &kde; desktop from your login manager. This can be -disabled by using the -configuration file option. - -Session setup does not occur while &kdesrc-build; is running -in pretend mode. - -This driver works by setting up a custom xsession -session type. This type of session should work by default with the &kdm; login -manager (where it appears as a Custom session), but other login -managers (such as LightDM and -gdm) may require additional files installed to -enable xsession support. - - -Adding xsession support for distributions - -The default login managers for some distributions may require additional -packages to be installed in order to support xsession logins. - - -The Fedora -&Linux; distribution requires the xorg-x11-xinit-session -package to be installed for custom xsession login -support. - -Debian and -Debian-derived &Linux; distributions should support custom -xsession logins, but require the - option to be set in -/etc/X11/Xsession.options. See also the Debian documentation -on customizing the X session. - -For other distributions, go to . - - - + +Getting Started Conclusion +These are the major features and concepts needed to get started with +&kdesrc-build; - -Manually adding support for xsession +For additional information, you could keep reading through this +documentation. In particular, the list +of command-line options and the table +of configuration file options are useful references. -If there were no distribution-specific directions for your distribution -in , you can manually add a -Custom xsession login entry to your distribution's list of -session types as follows: - - -Adding an .xsession login session type. - -This procedure will likely require administrative privileges to -complete. - - - -Create the file -/usr/share/xsessions/kdesrc-build.desktop. - - - -Ensure the file just created has the following text: - -Type=XSession -Exec=$HOME/.xsession -Name=KDE Plasma Desktop (unstable; kdesrc-build) - - - - -The $HOME entry must be replaced by the full path to -your home directory (example, /home/user). The -desktop entry specification does not allow for user-generic files. - - - - - -When the login manager is restarted, it -should show a new session type, KDE Plasma Desktop (unstable; -kdesrc-build) in its list of sessions, which should try to run the -.xsession file installed by &kdesrc-build; if it is -selected when you login. - -It may be easiest to restart the computer to restart the login -manager, if the login manager does not track updates to the /usr/share/xsessions directory. - - - - - - - - - - -Setting up the environment manually -This documentation used to include instruction on which environment -variables to set in order to load up the newly-built desktop. These -instructions have been moved to an appendix (). - -If you intend to setup your own login support you can consult that -appendix or view the sample-kde-env-master.sh file -included with the &kdesrc-build; source. - - +The &kde; Community also maintains an +online Wiki reference for how to build the source code, which refers to +&kdesrc-build; and includes tips and other guidelines on how to use the +tool. @@ -1579,9 +1757,9 @@ option. apidox This option was used to allow for building KDE module API documentation. -It was removed in &kdesrc-build; 1.6.3 due to it not being supported in KDE 4. Online +It was removed in &kdesrc-build; 1.6.3 due to lack of support. Online API documentation is available from kde.org. -In addition it is possible to build KDE 4's API documentation using the +In addition it is possible to build KDE API documentation using the kdedoxygen.sh script included in the kde-dev-scripts module. See KDE TechBase for more details. @@ -1813,7 +1991,7 @@ 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. This option only works for qt. -To change configuration settings for KDE 4 modules, see +To change configuration settings for KDE modules, see cmake-options. @@ -4289,14 +4467,14 @@ end global -&cmake;, the &kde; 4 build system +&cmake;, the &kde; build system Introduction to &cmake; In March 2006, the &cmake; program beat out several competitors and was selected to be the build system for &kde; 4, replacing the -autotools-based system that &kde; has used from the beginning. +autotools-based system that &kde; had used from the beginning. A introduction to &cmake; page is available on the &kde; Community Wiki.