Git commit 5cffc45604ee1d07cc545220a99ab5443513f196 by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'.
doc: getting-started - separate docbook C +0 -676 doc/getting-started.docbook [from: doc/index.docbook - 051% similarity] M +2 -591 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/5cffc45604ee1d07cc545220a99ab5443513f196 diff --git a/doc/index.docbook b/doc/getting-started.docbook similarity index 51% copy from doc/index.docbook copy to doc/getting-started.docbook index 02ceb3ba..53d0d1b8 100644 --- a/doc/index.docbook +++ b/doc/getting-started.docbook @@ -1,234 +1,3 @@ -<?xml version="1.0" ?> -<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ - <!-- - Documentation for kdesrc-build. - Copyright (c) 2005-2008, 2010-2022 Michael Pyne <mp...@kde.org> - - Copyright (c) 2005 Carlos Leonhard Woelz <carloswo...@imap-mail.com> - Copyright (c) 2009 Burkhard Lück <lu...@hube-lueck.de> - Copyright (c) 2007, 2011 Federico Zenith <federico.zen...@members.fsf.org> - Copyright (c) 2009-2011 Yuri Chornoivan <yurc...@ukr.net> - ... and possibly others. Check the git source repository for specifics. - - Permission is granted to copy, distribute and/or modify this document under - the terms of the GNU Free Documentation License, Version 1.2 or any later - version published by the Free Software Foundation; with no Invariant - Sections, no Front-Cover Texts, and no Back-Cover Texts. - - A copy of the license is included in COPYING.DOC. The license will be - included in the generated documentation as well. - --> - <!ENTITY kappname "kdesrc-build"> - <!ENTITY package "kdesdk"> - <!ENTITY % addindex "IGNORE"> - <!ENTITY % English "INCLUDE"> <!-- Change language only here --> - <!ENTITY kdesrc-build "<application>kdesrc-build</application>"> - <!ENTITY BSD '<acronym>BSD</acronym>'> - <!ENTITY git '<application>Git</application>'> - <!ENTITY cmake '<application>CMake</application>'> - <!ENTITY make '<application>Make</application>'> - <!ENTITY ninja '<application>Ninja</application>'> - <!ENTITY ssh '<application>SSH</application>'> - <!ENTITY cron '<application>Cron</application>'> - <!ENTITY sudo '<application>Sudo</application>'> - <!ENTITY url '<acronym>URL</acronym>'> - - <!-- These define shortcut entities for some of the configuration options. - Just add them as necessary. - --> - - <!ENTITY configure-flags '<link linkend="conf-configure-flags">configure-flags</link>'> - <!ENTITY install-dir '<link linkend="conf-install-dir">install-dir</link>'> - <!ENTITY qtdir '<link linkend="conf-qtdir">qtdir</link>'> - <!ENTITY build-dir '<link linkend="conf-build-dir">build-dir</link>'> - <!ENTITY source-dir '<link linkend="conf-source-dir">source-dir</link>'> - <!ENTITY colorful-output '<link linkend="conf-colorful-output">colorful-output</link>'> - <!ENTITY tag '<link linkend="conf-tag">tag</link>'> - <!ENTITY branch '<link linkend="conf-branch">branch</link>'> - <!ENTITY do-not-compile '<link linkend="conf-do-not-compile">do-not-compile</link>'> - <!ENTITY repository '<link linkend="conf-repository">repository</link>'> - <!ENTITY make-install-prefix '<link linkend="conf-make-install-prefix">make-install-prefix</link>'> - <!ENTITY niceness '<link linkend="conf-niceness">niceness</link>'> - <!ENTITY set-env '<link linkend="conf-set-env">set-env</link>'> - <!ENTITY libname '<link linkend="conf-libname">libname</link>'> - <!ENTITY libpath '<link linkend="conf-libpath">libpath</link>'> - <!ENTITY binpath '<link linkend="conf-binpath">binpath</link>'> - - <!-- These define shortcut entities for some of the command line options. - Just add them as necessary. - --> - <!ENTITY cmd-nice '<link linkend="cmdline-nice">--nice</link>'> - <!ENTITY cmd-ignore-modules '<link linkend="cmdline-ignore-modules">--ignore-modules</link>'> - <!ENTITY cmd-resume-from '<link linkend="cmdline-resume-from">--resume-from</link>'> - <!ENTITY cmd-resume-after '<link linkend="cmdline-resume-after">--resume-after</link>'> - <!ENTITY cmd-reconfigure '<link linkend="cmdline-reconfigure">--reconfigure</link>'> - <!ENTITY cmd-refresh-build '<link linkend="cmdline-refresh-build">--refresh-build</link>'> - - <!-- These define docbook files to include. - Just add them as necessary. - --> - <!ENTITY advanced-features SYSTEM "advanced-features.docbook"> - <!ENTITY appendix-modules SYSTEM "appendix-modules.docbook"> - <!ENTITY appendix-profile SYSTEM "appendix-profile.docbook"> - <!ENTITY basic-features SYSTEM "basic-features.docbook"> - <!ENTITY building-and-troubleshooting SYSTEM "building-and-troubleshooting.docbook"> - <!ENTITY building-specific-modules SYSTEM "building-specific-modules.docbook"> - <!ENTITY cmdline SYSTEM "cmdline.docbook"> - <!ENTITY conf-options-table SYSTEM "conf-options-table.docbook"> - <!ENTITY configure-data SYSTEM "configure-data.docbook"> - <!ENTITY credits-and-license SYSTEM "credits-and-license.docbook"> - <!ENTITY developer-features SYSTEM "developer-features.docbook"> - <!ENTITY environment SYSTEM "environment.docbook"> - <!ENTITY features SYSTEM "features.docbook"> -]> - -<book id="kdesrc-build" lang="&language;"> - -<bookinfo> -<title>&kdesrc-build; Script Manual</title> - -<authorgroup id="authors"> - <author>&Michael.Pyne; &Michael.Pyne.mail;</author> - <author> - <personname><firstname>Carlos</firstname><surname>Woelz</surname></personname> - <email>carloswo...@imap-mail.com</email> - </author> - -<!-- TRANS:ROLES_OF_TRANSLATORS --> - -</authorgroup> - -<copyright> -<year>2006</year> -<year>2007</year> -<year>2008</year> -<year>2009</year> -<year>2010</year> -<year>2011</year> -<year>2012</year> -<year>2013</year> -<year>2014</year> -<year>2015</year> -<year>2016</year> -<year>2017</year> -<year>2018</year> -<year>2019</year> -<holder>Michael Pyne</holder> -</copyright> - -<copyright> -<year>2005</year> -<holder>Carlos Woelz</holder> -</copyright> - -<legalnotice>&FDLNotice;</legalnotice> - -<date>2018-01-20</date> -<releaseinfo>&kdesrc-build; 17.12</releaseinfo> - -<abstract> -<para>&kdesrc-build; is a script which builds and installs &kde; software -directly from the &kde; project's source code repositories.</para> -</abstract> - -<keywordset> -<keyword>KDE</keyword> -<keyword>kdesdk</keyword> -<keyword>git</keyword> -<keyword>KDE development</keyword> -</keywordset> - -</bookinfo> - -<chapter id="introduction"> -<title>Introduction</title> - -<sect1 id="brief-intro"> -<title>A brief introduction to &kdesrc-build;</title> - -<sect2 id="whatis-kdesrc-build"> -<title>What is &kdesrc-build;?</title> - -<para> -&kdesrc-build; is a script to help the &kde; community install <ulink -url="https://www.kde.org/";>&kde;</ulink> software from its <ulink -url="https://git-scm.com/";>&git;</ulink> 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. -</para> - -<para>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. -</para> - -<para>To get started, see <xref linkend="getting-started"/>, or continue reading for more -detail on how &kdesrc-build; works and what is covered in this documentation. -</para> -</sect2> - -<sect2 id="operation-in-a-nutshell"> -<title>&kdesrc-build; operation <quote>in a nutshell</quote></title> - -<para>&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: </para> - -<orderedlist> -<listitem><para>&kdesrc-build; reads in the <link linkend="cmdline">command -line</link> and <link linkend="configure-data">configuration file</link>, to -determine what to build, compile options to use, where to install, -&etc;</para></listitem> - -<listitem><para>&kdesrc-build; performs a source update for each <link -linkend="module-concept">module</link>. 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.</para></listitem> - -<listitem><para>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. -</para></listitem> -</orderedlist> - -<tip><para>A <emphasis>very good</emphasis> overview of how &kde; modules are -built, including informative diagrams, is provided on <ulink -url="https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for- -cats">an online article discussing &kde;'s &krita; application</ulink>. This -workflow is what &kdesrc-build; automates for all &kde; modules.</para> -</tip> - -</sect2> -</sect1> - -<sect1 id="intro-toc"> -<title>Documentation Overview</title> - -<para> -This guide is an overview to describe the following aspects of &kdesrc-build; -operation: -</para> - -<itemizedlist> -<listitem><para>An <link linkend="getting-started">overview</link> of the steps -required to get started.</para></listitem> -<listitem><para>Notable <link linkend="features">features</link>.</para></listitem> -<listitem><para>The <link linkend="configure-data">configuration file</link> syntax -and options.</para></listitem> -<listitem><para>The <link linkend="cmdline">command line options</link>.</para></listitem> -</itemizedlist> - -<para>Also documented are the steps which you should perform using -other tools (&ie; steps that are not automatically performed by &kdesrc-build;). -</para> - -</sect1> -</chapter> - <chapter id="getting-started"> <title>Getting Started</title> @@ -820,448 +589,3 @@ tool.</para> </sect1> </chapter> - -&features; - -<chapter id="kdesrc-buildrc"> -<title>Configuring &kdesrc-build;</title> - -<sect1 id="kdesrc-buildrc-overview"> -<title>Overview of &kdesrc-build; configuration</title> - -<para> -To use the script, you must have a file in your home directory called -<filename>.kdesrc-buildrc</filename>, which describes the modules you would -like to download and build, and any options or configuration parameters to -use for these modules. -</para> - -<sect2 id="kdesrc-buildrc-layout"> -<title>Layout of the configuration file</title> - -<sect3 id="kdesrc-buildrc-layout-global"> -<title>Global configuration</title> - -<para> -The configuration file starts with the global options, specified like the -following: -</para> - -<programlisting> -global -<replaceable>option-name option-value</replaceable> -<replaceable>[...]</replaceable> -end global -</programlisting> - -</sect3> -<sect3 id="kdesrc-buildrc-layout-modules"> -<title>Module configuration</title> - -<para> -It is then followed by one or more module sections, specified in one of the -following two forms: -</para> - -<itemizedlist> -<listitem> -<programlisting> -module <replaceable>module-name</replaceable> -<replaceable>option-name option-value</replaceable> -<replaceable>[...]</replaceable> -end module -</programlisting> -</listitem> - -<listitem> -<programlisting> -module-set <replaceable>module-set-name</replaceable> - repository <userinput>kde-projects</userinput> or <userinput><replaceable>git://host.org/path/to/repo.git</replaceable></userinput> - use-modules <replaceable>module-names</replaceable> - -# Other options may also be set -<replaceable>option-name option-value</replaceable> -<replaceable>[...]</replaceable> -end module-set -</programlisting> -</listitem> -</itemizedlist> - -<important><para>Note that the second form, module sets, <emphasis>only works -for Git-based modules</emphasis>.</para></important> - -<para> -For Git modules, <replaceable>module-name</replaceable> must be a module -from the &kde; &git; repository (for example, kdeartwork or -kde-wallpapers). -</para> - -<para> -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 <link linkend="conf-dest-dir">dest-dir</link> option. -</para> - -<para>However, for Git <emphasis>module sets</emphasis> the -<replaceable>module-names</replaceable> must correspond with actual git modules -in the chosen <option>repository</option>. See <link -linkend="conf-git-repository-base">git-repository-base</link> or <link -linkend="conf-use-modules">use-modules</link> for more information. -</para> - -</sect3> - -<sect3 id="kdesrc-buildrc-option-values"> -<title>Processing of option values</title> - -<para>In general, the entire line contents after the -<replaceable>option-name</replaceable> is used as the -<replaceable>option-value</replaceable>.</para> - -<para>One modification that &kdesrc-build; performs is that a sequence -<userinput>${<replaceable>name-of-option</replaceable>}</userinput> is replaced -with the value of that option from the global configuration. This allows you -to reference the value of existing options, including options already set by -&kdesrc-build;.</para> - -<para> -To see an example of this in use, see -<xref linkend="make-options-example"/>.</para> - -</sect3> - -<sect3 id="kdesrc-buildrc-options-groups"> -<title><quote>options</quote> modules</title> - -<para>There is a final type of configuration file entry, -<literal>options</literal> groups, which may be given wherever a -<literal>module</literal> or <literal>module-set</literal> may be used.</para> - -<programlisting> -options <replaceable>module-name</replaceable> -<replaceable>option-name option-value</replaceable> -<replaceable>[...]</replaceable> -end options -</programlisting> - -<para>An <literal>options</literal> group may have options set for it just like -a module declaration, and is associated with an existing module. Any options -set these way will be used to <emphasis>override</emphasis> options set for the -associated module.</para> - -<important><para>The associated module name <emphasis>must</emphasis> match the -name given in the <literal>options</literal> declaration. Be careful of -mis-typing the name.</para></important> - -<para>This is useful to allow for declaring an entire -<literal>module-set</literal> worth of modules, all using the same options, and -then using <literal>options</literal> groups to make individual changes.</para> - -<para><literal>options</literal> groups can also apply to named module sets. -This allows expert users to use a common configuration file (which includes -<literal>module-set</literal> declarations) as a baseline, and then make changes -to the options used by those module-sets in configuration files that -use the <literal><link -linkend="kdesrc-buildrc-including">include</link></literal> command to reference -the base configuration.</para> - -<example id="ex-options-group"> -<title>Example of using options</title> - -<para>In this example we choose to build all modules from the &kde; multimedia -software grouping. However we want to use a different version of the &kmix; -application (perhaps for testing a bug fix). It works as follows:</para> - -<programlisting> -module-set <replaceable>kde-multimedia-set</replaceable> - repository <userinput>kde-projects</userinput> - use-modules <replaceable>kde/kdemultimedia</replaceable> - branch <replaceable>master</replaceable> -end module-set - -# kmix is a part of kde/kdemultimedia group, even though we never named -# kmix earlier in this file, &kdesrc-build; will figure out the change. -options <replaceable>kmix</replaceable> - branch <replaceable>KDE/4.12</replaceable> -end options -</programlisting> - -<para>Now when you run &kdesrc-build;, all of the &kde; multimedia programs will -be built from the <quote>master</quote> branch of the source repository, but -&kmix; will be built from the older <quote>KDE/4.12</quote> branch. By using -<literal>options</literal> you didn't have to individually list all the -<emphasis>other</emphasis> &kde; multimedia programs to give them the right -branch option.</para> - -</example> - -<note> -<para>Note that this feature is only available in &kdesrc-build; from version -1.16, or using the development version of &kdesrc-build; after -2014-01-12.</para></note> - -</sect3> - -</sect2> - -<sect2 id="kdesrc-buildrc-including"> -<title>Including other configuration files</title> - -<para> -Within the configuration file, you may reference other files by using the -<literal>include</literal> keyword with a file, which will act as if the file -referenced had been inserted into the configuration file at that point. -</para> - -<informalexample><para>For example, you could have something like this:</para> -<programlisting> -global - include <replaceable>~/common-kdesrc-build-options</replaceable> - - # Insert specific options here. - -end global -</programlisting> -</informalexample> - -<note><para>If you don't specify the full path to the file to include, then -the file will be searched for starting from the directory containing the source -file. This works recursively as well.</para></note> - -</sect2> - -<sect2 id="kdesrc-buildrc-common"> -<title>Commonly used configuration options</title> - -<para> -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 -<xref linkend="conf-options-table"/>. -</para> - -<itemizedlist> -<listitem><para><link linkend="conf-cmake-options">cmake-options</link> to define what flags to configure a module with using &cmake;.</para></listitem> -<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of <literal>master</literal>.</para></listitem> -<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure &Qt; with.</para></listitem> -<listitem><para><link linkend="conf-install-dir">install-dir</link>, to set the directory to install &kde; to.</para></listitem> -<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program (such as number of CPUs to use).</para></listitem> -<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to &Qt;.</para></listitem> -<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem> -</itemizedlist> - -</sect2> -</sect1> -&conf-options-table; -</chapter> - -&cmdline; - -<chapter id="using-kdesrc-build"> -<title>Using &kdesrc-build;</title> - -<sect1 id="using-kdesrc-build-preface"> -<title>Preface</title> - -<para>Normally using &kdesrc-build; after you have gone through <xref linkend="getting-started" /> -is as easy as doing the following from a terminal prompt:</para> - -<screen> -<prompt>%</prompt> <command><userinput>kdesrc-build</userinput></command> -</screen> - -<para>&kdesrc-build; will then download the sources for &kde;, try to configure -and build them, and then install them.</para> - -<para>Read on to discover how &kdesrc-build; does this, and what else you can -do with this tool.</para> - -</sect1> - -&basic-features; - -&advanced-features; - -&developer-features; - -<sect1 id="other-features"> -<title>Other &kdesrc-build; features</title> - -<sect2 id="changing-verbosity"> -<title>Changing the amount of output from &kdesrc-build;</title> -<para>&kdesrc-build; has several options to control the amount of output the -script generates. In any case, errors will always be output.</para> - -<itemizedlist> -<listitem><para>The <option>--quiet</option> option (short form is -<option>-q</option>) causes &kdesrc-build; to be mostly silent. Only important -messages, warnings, or errors will be shown. When available, build progress -information is still shown.</para></listitem> - -<listitem><para>The <option>--really-quiet</option> option (no short form) -causes &kdesrc-build; to only display important warnings or errors while it is -running.</para></listitem> - -<listitem><para>The <option>--verbose</option> option (short form is -<option>-v</option>) causes &kdesrc-build; to be very detailed in its -output.</para></listitem> - -<listitem><para>The <option>--debug</option> option is for debugging purposes -only, it causes &kdesrc-build; to act as if <option>--verbose</option> was -turned on, causes commands to also output to the terminal, and will display -debugging information for many functions.</para></listitem> -</itemizedlist> - -</sect2> - -<sect2 id="kdesrc-build-color"> -<title>Color output</title> -<para>When being run from &konsole; or a different terminal, &kdesrc-build; -will normally display with colorized text.</para> - -<para>You can disable this by using the <option>--no-color</option> on the -command line, or by setting the &colorful-output; option in the <link linkend="configure-data">configuration file</link> to -<userinput>false</userinput>. -</para> - -<informalexample> -<para>Disabling color output in the configuration file:</para> -<screen> -global - colorful-output false -end global -</screen> -</informalexample> - -</sect2> - -<sect2 id="deleting-build-dir"> -<title>Removing unneeded directories after a build</title> -<para>Are you short on disk space but still want to run a bleeding-edge -&kde; checkout? &kdesrc-build; can help reduce your disk usage when building -&kde; from &git;.</para> - -<note><para>Be aware that building &kde; does take a lot of space. There are -several major space-using pieces when using &kdesrc-build;:</para></note> - -<orderedlist> -<listitem><para>The actual source checkout can take up a fair amount of space. -The default modules take up about 1.6 gigabytes of on-disk space. You can reduce -this amount by making sure that you are only building as many modules as you -actually want. &kdesrc-build; will not delete source code from disk even if you -delete the entry from the <link linkend="configure-data">configuration file</link>, so make sure that you go and delete unused -source checkouts from the source directory. Note that the source files are -downloaded from the Internet, you <emphasis>should not</emphasis> delete them -if you are actually using them, at least until you are done using -&kdesrc-build;.</para> - -<para>Also, if you already have a &Qt; installed by your distribution (and -the odds are good that you do), you probably do not need to install the -qt module. That will shave about 200 megabytes off of the on-disk source -size.</para> -</listitem> - -<listitem> -<para>&kdesrc-build; will create a separate build directory to build the source -code in. Sometimes &kdesrc-build; will have to copy a source directory to -create a fake build directory. When this happens, space-saving symlinks are -used, so this should not be a hassle on disk space. The build directory will -typically be much larger than the source directory for a module. For example, -the build directory for kdebase is about 1050 megabytes, whereas kdebase's -source is only around 550 megabytes.</para> - -<para>Luckily, the build directory is not required after a module has -successfully been built and installed. &kdesrc-build; can automatically -remove the build directory after installing a module, see the examples below -for more information. Note that taking this step will make it impossible -for &kdesrc-build; to perform the time-saving incremental builds.</para> -</listitem> - -<listitem><para> -Finally, there is disk space required for the actual installation of -&kde;, which does not run from the build directory. This typically takes less -space than the build directory. It is harder to get exact figures however. -</para></listitem> -</orderedlist> - -<para>How do you reduce the space requirements of &kde;? One way is to -use the proper compiler flags, to optimize for space reduction instead of -for speed. Another way, which can have a large effect, is to remove debugging -information from your &kde; build. -</para> - -<warning><para> -You should be very sure you know what you are doing before deciding to remove -debugging information. Running bleeding-edge software means you are running -software which is potentially much more likely to crash than a stable release. -If you are running software without debugging information, it can be very -hard to create a good bug report to get your bug resolved, and you will likely -have to re-enable debugging information for the affected application and -rebuild to help a developer fix the crash. So, remove debugging information -at your own risk! -</para></warning> - -<informalexample> -<para>Removing the build directory after installation of a module. The source -directory is still kept, and debugging is enabled:</para> - -<screen> -global - configure-flags --enable-debug - remove-after-install builddir # Remove build directory after install -end global -</screen> - -<para>Removing the build directory after installation, without debugging -information, with size optimization.</para> - -<screen> -global - cxxflags -Os # Optimize for size - configure-flags --disable-debug - remove-after-install builddir # Remove build directory after install -end global -</screen> -</informalexample> -</sect2> - -</sect1> - -</chapter> - -<chapter id="kde-cmake"> -<title>&cmake;, the &kde; build system</title> - -<sect1 id="kde-cmake-intro"> -<title>Introduction to &cmake;</title> - -<para>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; had used from the beginning.</para> - -<para>A introduction to &cmake; page is available on the <ulink -url="https://community.kde.org/Guidelines_HOWTOs/CMake";>&kde; Community Wiki</ulink>. -Basically, instead of running <userinput><command>make</command> <option>-f</option> -<filename>Makefile.cvs</filename></userinput>, then <command>configure</command>, -then &make;, we simply run &cmake; and then &make;. -</para> - -<para>&kdesrc-build; has support for &cmake;. A few features of &kdesrc-build; -were really features of the underlying buildsystem, including -<link linkend="conf-configure-flags">configure-flags</link> -and <link linkend="conf-do-not-compile">do-not-compile</link>. When equivalent -features are available, they are provided. For instance, the equivalent to the -configure-flags option is <link linkend="conf-cmake-options">cmake-options</link>, and the -<link linkend="conf-do-not-compile">do-not-compile</link> option is also supported for &cmake; -as of &kdesrc-build; version 1.6.3. -</para> - -</sect1> -</chapter> - -&credits-and-license; - -&appendix-modules; - -&appendix-profile; -</book> diff --git a/doc/index.docbook b/doc/index.docbook index 02ceb3ba..d506542a 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -80,6 +80,7 @@ <!ENTITY developer-features SYSTEM "developer-features.docbook"> <!ENTITY environment SYSTEM "environment.docbook"> <!ENTITY features SYSTEM "features.docbook"> + <!ENTITY getting-started SYSTEM "getting-started.docbook"> ]> <book id="kdesrc-build" lang="&language;"> @@ -229,597 +230,7 @@ other tools (&ie; steps that are not automatically performed by &kdesrc-build;). </sect1> </chapter> -<chapter id="getting-started"> -<title>Getting Started</title> - -<para> -In this chapter, we show how to use the &kdesrc-build; to checkout modules from -the &kde; repository and build them. We also provide a basic explanation of the -&kde; source code structure and the steps you have to perform before running -the script. -</para> - -<para> -All topics present in this chapter are covered with even more detail in the -<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source";> -Build from Source</ulink> article, at the -<ulink url="https://community.kde.org/";>&kde; Community Wiki</ulink>. -If you are compiling &kde; for the first time, it is a good idea to read -it, or consult it as a reference source. You will find detailed information -about packaging tools and requirements, common compilation pitfalls and -strategies and information about running your new &kde; installation. -</para> - -<sect1 id="before-building"> -<title>Preparing the System to Build &kde;</title> - -<sect2 id="before-building-users"> -<title>Setup a new user account</title> - -<para> -It is recommended that you use a different user account to build, install, -and run your &kde; software from, since less permissions are required, and -to avoid interfering with your distribution's packages. -If you already have &kde; packages installed, the best choice -would be to create a different (dedicated) user to build and run the new &kde;. -</para> - -<tip><para>Leaving your system &kde; untouched also allows you to have an -emergency fallback in case a coding mistake causes your latest software build -to be unusable. -</para></tip> - -<para> -You can do also setup to install to a system-wide directory (⪚ <filename -class="directory">/usr/src/local</filename>) if you wish. This document -does not cover this installation type, since we assume you know what you are doing. -</para> - -</sect2> -<sect2 id="before-building-preparation"> -<title>Ensure your system is ready to build &kde; software</title> - -<para>Before using the &kdesrc-build; script (or any other building -strategy) you must install the development tools and libraries needed for &kde;. -The nearly complete list of required tools can be found from -the <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_required_devel_packages";>&kde; -Community Wiki Build Requirements</ulink> page. -</para> - -<para>Here is a list of some of the things you will need:</para> -<itemizedlist> - -<listitem><para>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. -</para></listitem> - -<listitem><para>You must also install the source control clients needed to checkout -the &kde; source code. This means you need at least the following:</para> - -<itemizedlist> -<listitem><para>The <ulink url="https://git-scm.com/";>Git -source control manager</ulink>, which is used for all &kde; <ulink -url=" https://commits.kde.org/";>source code</ulink></para></listitem> - -<listitem><para>Although it is not required, the <ulink -url="http://bazaar.canonical.com/";>Bazaar</ulink> source control manager is -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.</para></listitem> -</itemizedlist></listitem> - -<listitem><para>The Perl scripting language is required for &kdesrc-build;, some &kde; -repositories, and &Qt; (if you build that from source).</para> - -<para>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):</para> - -<itemizedlist> - <listitem><para>IO::Socket::SSL</para></listitem> - <listitem><para>JSON::PP or JSON::XS</para></listitem> - <listitem><para>YAML::PP, YAML::XS, or YAML::Syck</para></listitem> -</itemizedlist> -</listitem> - -<listitem><para>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.</para> -<para>The GCC 4.8 or Clang 4 compilers are the minimum recommended. Many distributions support easily -installing these tools using a <quote>build-essentials</quote> package, an option to install -"build dependencies" with &Qt;, or similar features. The KDE Community Wiki has a page <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Install_the_dependencies";>tracking -recommended packages for major distributions</ulink>. -</para> -</listitem> - -<listitem><para>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 -<link linkend="conf-custom-build-command">custom-build-command</link> configuration file -option. -</para></listitem> - -<listitem><para>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 <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/OwnQt5";>self-building Qt 5</ulink>. -</para></listitem> -</itemizedlist> - -<note><para>Most operating system distributions include a method of easily -installing required development tools. Consult the Community Wiki page <ulink -url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_required_devel_packages"; ->Required devel packages</ulink> to see -if these instructions are already available.</para></note> - -<important><para> -Some of these packages are divided into libraries (or programs or utilities), -and development packages. You will need at least the program or library -<emphasis>and</emphasis> its development package. -</para></important> - -</sect2> - -<sect2 id="before-building-prepare-script"> -<title>Setup &kdesrc-build;</title> - -<sect3 id="get-kdesrc-build"> -<title>Install &kdesrc-build;</title> -<para> -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;</para> - -<para>Because of this, we recommend obtaining &kdesrc-build; directly from its -source repository and then periodically updating it.</para> - -<para>You can obtain &kdesrc-build; from its source repository by running:</para> -<programlisting> -<prompt>$ </prompt><userinput><command>git <option>clone</option> <option>https://invent.kde.org/sdk/kdesrc-build.git</option> <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput> -</programlisting> - -<para>Replace <option><replaceable>~/kdesrc-build</replaceable></option> with -the directory you would like to install to. -</para> - -<para>You can update &kdesrc-build; later by running:</para> -<programlisting> -<prompt>$ </prompt><userinput><command>cd <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput> -<prompt>$ </prompt><userinput><command>git <option>pull</option></command></userinput> -</programlisting> - -<tip><para>We recommend adding the &kdesrc-build; installation directory to -your <envar>PATH</envar> environment variable, so that you can run &kdesrc-build; -without having to fully specify its path every time.</para></tip> -</sect3> - -<sect3 id="setup-rcfile"> -<title>Prepare the configuration file</title> - -<para>&kdesrc-build; uses a <link linkend="configure-data">configuration file</link> -to control which modules are built, where they are installed to, etc. -This file is located at <filename>~/.config/kdesrc-buildrc</filename> -(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if -<envar>$XDG_CONFIG_HOME</envar> is set).</para> - -<para>You can use <application>kdesrc-build --generate-config</application> in order to prepare a simple -kdesrc-build configuration. You can then edit the -<filename>~/.config/kdesrc-buildrc</filename> configuration file to make -any changes you see fit.</para> - -<sect4 id="setup-rcfile-manually"> -<title>Manual setup of configuration file</title> - -<para>You can also setup your configuration file manually, by copying the -included sample configuration file <filename>kdesrc-buildrc-kf5-sample</filename> -to <filename>~/.config/kdesrc-buildrc</filename> and then editing the file. -<xref linkend="kdesrc-buildrc"/> will be a useful reference for this, especially -its <link linkend="conf-options-table">table of configuration options</link>. -</para> - -<para>&kdesrc-build; contains many recommended configuration files to support -&kde; Frameworks 5, &plasma; 5, and other &kde; applications. See -<xref linkend="kdesrc-buildrc-including"/> for information on how to use other -configuration files from your own <filename>kdesrc-buildrc</filename>. -</para> - -<para>You can find more information about the syntax of the <link -linkend="configure-data">configuration file</link> in <xref -linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />. -</para> -</sect4> -</sect3> -</sect2> -</sect1> - -&configure-data; - -&building-and-troubleshooting; - -&building-specific-modules; - -&environment; - -<sect1 id="kde-modules-and-selection"> -<title>Module Organization and selection</title> - -<sect2 id="kde-layers"> -<title>KDE Software Organization</title> - -<para> -&kde; software is split into different components, many of which can be built -by &kdesrc-build;. Understanding this organization will help you properly -select the software modules that you want built. -</para> - -<orderedlist> -<listitem><para>At the lowest level comes the &Qt; library, which is a -very powerful, cross-platform <quote>toolkit</quote> library. &kde; is based on -&Qt;, and some of the non-&kde; libraries required by &kde; are also based on -&Qt;. &kdesrc-build; can build &Qt;, or use the one already installed on your -system if it is a recent enough version.</para></listitem> - -<listitem><para>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 are collected under a <literal>kdesupport</literal> -module grouping but are not considered part of the <quote>Frameworks</quote> -libraries.</para> -</listitem> - -<listitem><para>On top of these essential libraries come the <ulink -url="https://community.kde.org/Frameworks";>&kde; Frameworks</ulink>, sometimes -abbreviated as KF5, which are essential libraries for the &kde; Plasma desktop, -&kde; Applications, and other third-party software. -</para> </listitem> - -<listitem><para>On top of the Frameworks, come several different things:</para> - <itemizedlist> - <listitem><para><quote>Third-party</quote> applications. These are - 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.</para></listitem> - - <listitem><para>Plasma, which is a full <quote>workspace</quote> desktop - environment. This is what users normally see when they <quote>log-in to - &kde;</quote>.</para></listitem> - - <listitem><para>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 - <application>KSudoku</application>, and productivity software released by &kde; - such as &kontact;.</para></listitem> - - <listitem><para>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; as part of Plasma or the Application suite. These - modules are known as <quote>Extragear</quote>. - </para></listitem> - </itemizedlist> -</listitem> -</orderedlist> -</sect2> - -<sect2 id="selecting-modules"> -<title>Selecting modules to build</title> - -<para>Selecting which of the possible modules to build is controlled by -<link linkend="kdesrc-buildrc">the configuration file</link>. -After the <literal>global</literal> section is a list of modules to build, -bracketed by module ... end module lines. An example entry for a module is -shown in <xref linkend="conf-module-example"/>.</para> - -<example id="conf-module-example"> -<title>Example module entry in the configuration file</title> -<programlisting> -module <replaceable>kdesrc-build-git</replaceable> - # Options for this module go here, example: - <link linkend="conf-repository">repository</link> kde:kdesrc-build - <link linkend="conf-make-options">make-options</link> -j4 # Run 4 compiles at a time -end module -</programlisting> -</example> - -<note><para>In practice, this module construct is not usually used directly. Instead -most modules are specified via module-sets as described below.</para></note> - -<para>When using only <literal>module</literal> 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. -</para> - -</sect2> - -<sect2 id="module-sets"> -<title>Module Sets</title> - -<para>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 <quote>module set</quote>. -</para> - -<sect3 id="module-set-concept"> -<title>The basic module set concept</title> - -<para>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 <link linkend="conf-repository">repository</link> option is -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.</para> - -<example id="example-using-module-sets"> -<title>Using module sets</title> -<programlisting> -global - <option><link linkend="conf-git-repository-base">git-repository-base</link></option> <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable> -end global - -module <replaceable>qt</replaceable> - # Options removed for brevity -end module - -module-set <replaceable>kde-support-libs</replaceable> - <option><link linkend="conf-repository">repository</link></option> <replaceable>kde-git</replaceable> - <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>automoc</replaceable> <replaceable>attica</replaceable> <replaceable>akonadi</replaceable> -end module-set - -# Other modules as necessary... -module <replaceable>kdesupport</replaceable> -end module -</programlisting> -</example> - -<para>In <xref linkend="example-using-module-sets"/> a brief module set is -shown. When &kdesrc-build; encounters this module set, it acts as if, for -every module given in <option>use-modules</option>, that an individual module -has been declared, with its <option>repository</option> equal to the -module-set's <option>repository</option> followed immediately by the given -module name.</para> - -<para>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, 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.</para> - -</sect3> -<sect3 id="module-sets-kde"> -<title>Special Support for KDE module sets</title> - -<para>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 <literal>kde-projects</literal> as the -<option>repository</option> for the module set. -</para> - -<para>&kdesrc-build; normally only builds the modules you have listed in your -configuration file, in the order you list them. But with a -<literal>kde-projects</literal> 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.</para> - -<example id="example-using-kde-module-sets"> -<title>Using kde-projects module sets</title> -<programlisting> -# Only adds a module for juk (the kde/kdemultimedia/juk repo) -module-set <replaceable>juk-set</replaceable> - <option>repository</option> kde-projects - <option>use-modules</option> <replaceable>juk</replaceable> -end module-set - -# Adds all modules that are in kde/multimedia/*, including juk, -# but no other dependencies -module-set <replaceable>multimedia-set</replaceable> - <option>repository</option> kde-projects - <option>use-modules</option> <replaceable>kde/multimedia</replaceable> -end module-set - -# Adds all modules that are in kde/multimedia/*, and all kde-projects -# dependencies from outside of kde/kdemultimedia -module-set <replaceable>multimedia-deps-set</replaceable> - <option>repository</option> kde-projects - <option>use-modules</option> <replaceable>kde/multimedia</replaceable> - <option>include-dependencies</option> <replaceable>true</replaceable> -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 -</programlisting> -</example> - -<tip><para>This <literal>kde-projects</literal> module set construct is the main method -of declaring which modules you want to build.</para></tip> - -<para>All module sets use the <link linkend="conf-repository">repository</link> -and <link linkend="conf-use-modules">use-modules</link> options. <link -linkend="kde-projects-module-sets"><literal>kde-projects</literal></link> module -sets have a predefined <option>repository</option> value, but other types of -module sets also will use the <link -linkend="conf-git-repository-base">git-repository-base</link> option. -</para> -</sect3> - -</sect2> - -<sect2 id="kde-projects-module-sets"> -<title>The official &kde; module database</title> - -<para>&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 <link -linkend="module-sets">module sets</link> with a <option>repository</option> -option set to <quote><literal>kde-projects</literal></quote>.</para> - -<para>&kdesrc-build; will recognize that the <literal>kde-projects</literal> -repository requires special handling, and adjust the build process -appropriately. Among other things, &kdesrc-build; will:</para> - -<itemizedlist> - -<listitem><para>Download the latest module database from the <ulink -url=" https://commits.kde.org/";>&kde; git archive</ulink>.</para></listitem> - -<listitem><para>Try to find a module with the name given in the module set's -<option>use-modules</option> setting in that database.</para></listitem> - -<listitem><para>For every module that is found, &kdesrc-build; will lookup the -appropriate repository in the database, based upon the <link -linkend="conf-branch-group">branch-group</link> 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. -</para></listitem> - -</itemizedlist> - -<note><para>In the current database, some module groups not only have a -collection of modules, but they <emphasis>also</emphasis> declare their own -&git; repository. In these situations &kdesrc-build; will currently prefer the -group's &git; repository instead of including the childrens' repositories. -</para></note> - -<para>The following example shows how to use the &kde; module database to -install the Phonon multimedia library.</para> - -<informalexample> -<programlisting> -module-set <replaceable>media-support</replaceable> - # This option must be kde-projects to use the module database. - <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal> - - # This option chooses what modules to look for in the database. - <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>phonon/phonon</replaceable> <replaceable>phonon-gstreamer</replaceable> <replaceable>phonon-vlc</replaceable> -end module-set -</programlisting> -</informalexample> - -<tip><para><literal>phonon/phonon</literal> is used since (with the current -project database) &kdesrc-build; would otherwise have to decide between the -group of projects called <quote>phonon</quote> or the individual project named -<quote>phonon</quote>. Currently &kdesrc-build; would pick the former, which -would build many more backends than needed.</para></tip> - -<para>The following example is perhaps more realistic, and shows a feature only -available with the &kde; module database: Building all of the &kde; graphics -applications with only a single declaration.</para> - -<informalexample> -<programlisting> -module-set <replaceable>kdegraphics</replaceable> - # This option must be kde-projects to use the module database. - <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal> - - # This option chooses what modules to look for in the database. - <option><link linkend="conf-use-modules">use-modules</link></option> <literal>kdegraphics/libs</literal> <literal>kdegraphics/*</literal> -end module-set -</programlisting> -</informalexample> - -<para>There are two important abilities demonstrated here:</para> - -<orderedlist> - -<listitem><para>&kdesrc-build; allows you to specify modules that are -descendents of a given module, without building the parent module, by using the -syntax <userinput><replaceable>module-name</replaceable>/*</userinput>. It is -actually required in this case since the base module, kdegraphics, is marked as -inactive so that it is not accidentally built along with its children modules. -Specifying the descendent modules allows &kdesrc-build; to skip around the -disabled module. -</para></listitem> - -<listitem><para>&kdesrc-build; will also not add a given module to the build -list more than once. This allows us to manually set -<literal>kdegraphics/libs</literal> to build first, before the rest of -<literal>kdegraphics</literal>, without trying to build -<literal>kdegraphics/libs</literal> 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. -</para></listitem> -</orderedlist> -</sect2> - -<sect2 id="ignoring-project-modules"> -<title>Filtering out &kde; project modules</title> - -<para>You might decide that you'd like to build all programs within a &kde; -module grouping <emphasis>except</emphasis> for a given program.</para> - -<para>For instance, the <literal>kdeutils</literal> group includes a program -named <application>kremotecontrol</application>. If your computer does not have -the proper hardware to receive the signals sent by remote controls then you may -decide that you'd rather not download, build, and install -<application>kremotecontrol</application> every time you update -<literal>kdeutils</literal>.</para> - -<para>You can achieve this by using the <link -linkend="conf-ignore-modules">ignore-modules</link> configuration option. -On the command line the -<link linkend="ignoring-modules">&cmd-ignore-modules; option</link> -does the same thing, but is more convenient for filtering out a module just once. -</para> - -<example id="example-ignoring-a-module"> -<title>Example for ignoring a kde-project module in a group</title> -<programlisting> -module-set <replaceable>utils</replaceable> - <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal> - - # This option chooses what modules to look for in the database. - <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>kdeutils</replaceable> - - # This option "subtracts out" modules from the modules chosen by use-modules, above. - <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>kremotecontrol</replaceable> -end module-set - -module-set <replaceable>graphics</replaceable> - <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal> - - # This option chooses what modules to look for in the database. - <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>extragear/graphics</replaceable> - - # This option "subtracts out" modules from the modules chosen by use-modules, above. - # In this case, *both* extragear/graphics/kipi-plugins and - # extragear/graphics/kipi-plugins/kipi-plugins-docs are ignored - <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>extragear/graphics/kipi-plugins</replaceable> -end module-set -</programlisting> -</example> - -</sect2> - -</sect1> - -<sect1 id="quick-start-conclusion"> -<title>Getting Started Conclusion</title> -<para>These are the major features and concepts needed to get started with -&kdesrc-build;</para> - -<para>For additional information, you could keep reading through this -documentation. In particular, the <link linkend="supported-cmdline-params">list -of command-line options</link> and the <link linkend="conf-options-table">table -of configuration file options</link> are useful references.</para> - -<para>The &kde; Community also maintains <ulink -url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source";>an -online Wiki reference for how to build the source code</ulink>, which refers to -&kdesrc-build; and includes tips and other guidelines on how to use the -tool.</para> - -</sect1> - -</chapter> +&getting-started; &features;
