Git commit 17357b81a15786f0066759f9433819912678f87b by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'.
doc: features - separate docbook A +262 -0 doc/features.docbook M +2 -262 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/17357b81a15786f0066759f9433819912678f87b diff --git a/doc/features.docbook b/doc/features.docbook new file mode 100644 index 00000000..2a911dc3 --- /dev/null +++ b/doc/features.docbook @@ -0,0 +1,262 @@ +<chapter id="features"> +<title>Script Features</title> + +<sect1 id="features-overview"> +<title>Feature Overview</title> + +<para> +&kdesrc-build; features include: +</para> + +<itemizedlist> + +<listitem><para> +You can <quote>pretend</quote> to do the operations. If you pass +<option>--pretend</option> or <option>-p</option> on the +command line, the script will give a verbose description of the commands +it is about to execute, without actually executing it. However if you've never +run &kdesrc-build;, you would want to run the <command>kdesrc-build +<option><link +linkend="cmdline-metadata-only">--metadata-only</link></option></command> +command first in order for <option>--pretend</option> to work. + +<tip><para>For an even more verbose description of what &kdesrc-build; is +doing, try using the <option>--debug</option> option. +</para></tip> + +</para></listitem> + +<listitem><para> +&kdesrc-build; allows you to checkout modules quickly. If the module you are checking out +has already been checked out previously, then &kdesrc-build; will download only commits +that are not yet on your computer. +</para> + +<tip><para>There is generally no need for any special preparation to perform +the initial checkout of a Git module, as the entire Git repository must be +downloaded anyways, so it is easy for the server to determine what to +send.</para></tip> + +<para>This is faster for you, and helps to ease the load on the kde.org +anonymous &git; servers.</para> +</listitem> + +<listitem><para> +Another speedup is provided by starting the build process for a module as soon +as the source code for that module has been downloaded. (Available since +version 1.6) +</para></listitem> + +<listitem><para> +Excellent support for building the &Qt; library (in case the &kde; software you +are trying to build depends on a recent &Qt; not available in your +distribution). +</para></listitem> + +<listitem><para> +&kdesrc-build; does not require a <acronym>GUI</acronym> present to operate. So, +you can build &kde; software without needing a graphical environment. +</para></listitem> + +<listitem><para> +Supports setting default options for all modules (such as the compilation +settings or the configuration options). Such options can normally be changed +for specific modules as well.</para> + +<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add +standard flags</link> as appropriate to save you the trouble and possible +errors from typing them yourself. Nota Bene: this does not apply when a (custom) +toolchain is configured through e.g.: +<link linkend="conf-cmake-toolchain">cmake-toolchain</link> +</para></listitem> + +<listitem><para> +&kdesrc-build; can checkout a specific <link linkend="using-branches">branch +or tag</link> of a module. You can also ensure that a specific <link +linkend="conf-revision">revision</link> is checked out of a module. +</para></listitem> + +<listitem><para> +&kdesrc-build; can automatically switch a source directory to checkout from +a different repository, branch, or tag. This happens automatically when you +change an option that changes what the repository &url; should be, but you must +use the <link linkend="cmdline-src-only">--src-only</link> option to let +&kdesrc-build; know that it is acceptable to perform the switch. +</para></listitem> + +<listitem><para> +&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a +module</link>, for those situations where you only need one program from a +large module. +</para></listitem> + +<listitem><para> +For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind +you</link> if you use git+ssh:// but <application>ssh-agent</application> is +not running, as this will lead to repeated password requests from +&ssh;. +</para></listitem> + +<listitem><para> +Can <link linkend="deleting-build-dir">delete the build directory</link> of a +module after its installation to save space at the expense of future compilation +time. +</para></listitem> + +<listitem><para> +The locations for the directories used by &kdesrc-build; are configurable (even +per module). +</para></listitem> + +<listitem><para> +Can use &sudo;, or a different user-specified command +to <link linkend="root-installation">install modules</link> so that +&kdesrc-build; does not need to be run as the super user. +</para></listitem> + +<listitem><para> +&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link> +by default to allow you to still use your computer while &kdesrc-build; is +working. +</para></listitem> + +<listitem><para> +Has support for using &kde;'s <link linkend="using-branches">tags and +branches</link>. +</para></listitem> + +<listitem><para> +There is support for <link linkend="resuming">resuming a build</link> from a +given module. You can even <link linkend="ignoring-modules">ignore some +modules</link> temporarily for a given build. +</para></listitem> + +<listitem><para> +&kdesrc-build; will show the <link linkend="build-progress">progress of your +build</link> when using &cmake;, and will always time the build +process so you know after the fact how long it took. +</para></listitem> + +<listitem><para> +Comes built-in with a sane set of default options appropriate for building +a base &kde; single-user installation from the anonymous source repositories. +</para></listitem> + +<listitem><para> +Tilde-expansion for your configuration options. For example, you can +specify: +<programlisting>qtdir ~/kdesrc/build/qt</programlisting> +</para></listitem> + +<listitem><para> +Automatically sets up a build system, with the source directory not the +same as the build directory, in order to keep the source directory +pristine. +</para></listitem> + +<listitem><para> +You can specify global options to apply to every module to check out, and +you can specify options to apply to individual modules as well. +</para></listitem> + +<listitem><para> +Forced full rebuilds, by running +&kdesrc-build; with the <option>--refresh-build</option> option. +</para></listitem> + +<listitem><para> +You can specify various environment values to be used during the build, +including <envar>QTDIR</envar>, <envar>DO_NOT_COMPILE</envar>, +and <envar>CXXFLAGS</envar>. +</para></listitem> + +<listitem><para> +Command logging. Logs are dated and numbered so that you always have a +log of a script run. Also, a special symlink called latest is created to +always point to the most recent log entry in the log directory. +</para></listitem> + +</itemizedlist> + +</sect1> + +<sect1 id="kdesrc-build-logging"> +<title>&kdesrc-build;'s build logging</title> + +<sect2 id="logging-overview"> +<title>Logging overview</title> + +<para>Logging is a &kdesrc-build; feature whereby the output from every command +that &kdesrc-build; runs is saved to a file for examination later, if +necessary. This is done because it is often necessary to have the output of +these programs when there is a build failure, because there are so many +reasons why a build can fail in the first place.</para> + +<sect3 id="log-directory-layout"> +<title>Logging directory layout</title> + +<para>The logs are always stored under the log directory. The destination of +the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link> +option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where +<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link> +option. The in rest of this section, this value will be referred to as +<symbol>${log-dir}</symbol>).</para> + +<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every +time that &kdesrc-build; was run. Each directory is named with the date, and +the run number. For instance, the second time that &kdesrc-build; is run on +May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>, +where the 2004-05-26 is for the date, and the -02 is the run number.</para> + +<para>For your convenience, &kdesrc-build; will also create a link to the +logs for your latest run, called <filename class="directory">latest</filename>. So the logs for +the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>. +</para> + +<para>Now, each directory for a &kdesrc-build; run will itself contain a set of +directories, one for every &kde; module that &kdesrc-build; tries to build. Also, +a file called <filename>build-status</filename> will be contained in the directory, +which will allow you to determine which modules built and which failed.</para> + +<note><para> +If a module itself has a submodule (such as extragear/multimedia, +playground/utils, or KDE/kdelibs), then there would actually be a matching +layout in the log directory. For example, the logs for KDE/kdelibs after the +last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>, +and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>. +</para></note> + +<para>In each module log directory, you will find a set of files for each +operation that &kdesrc-build; performs. If &kdesrc-build; updates a module, +you may see filenames such as <filename>git-checkout-update.log</filename> (for a +module checkout or when updating a module +that has already been checked out). If the <command>configure</command> +command was run, then you would expect to see a <filename>configure.log</filename> +in that directory.</para> + +<para>If an error occurred, you should be able to see an explanation of why in +one of the files. To help you determine which file contains the error, +&kdesrc-build; will create a link from the file containing the error (such as +<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para> + +<para>The upshot to all of this is that to see why a module failed to build +after your last &kdesrc-build;, the file you should look at first is +<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>. +</para> + +<tip><para>If the file <filename>error.log</filename> is empty (especially after +an installation), then perhaps there was no error. Some of the tools used by +the &kde; build system will sometimes mistakenly report an error when there was +none.</para> + +<para>Also, some commands will evade &kdesrc-build;'s output redirection and +bypass the log file in certain circumstances (normally when performing the +first &git; checkout), and the error output in that case is not in the log file +but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para> +</tip> + +</sect3> +</sect2> +</sect1> + +</chapter> diff --git a/doc/index.docbook b/doc/index.docbook index e4f365d5..02ceb3ba 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -79,6 +79,7 @@ <!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;"> @@ -820,268 +821,7 @@ tool.</para> </chapter> -<chapter id="features"> -<title>Script Features</title> - -<sect1 id="features-overview"> -<title>Feature Overview</title> - -<para> -&kdesrc-build; features include: -</para> - -<itemizedlist> - -<listitem><para> -You can <quote>pretend</quote> to do the operations. If you pass -<option>--pretend</option> or <option>-p</option> on the -command line, the script will give a verbose description of the commands -it is about to execute, without actually executing it. However if you've never -run &kdesrc-build;, you would want to run the <command>kdesrc-build -<option><link -linkend="cmdline-metadata-only">--metadata-only</link></option></command> -command first in order for <option>--pretend</option> to work. - -<tip><para>For an even more verbose description of what &kdesrc-build; is -doing, try using the <option>--debug</option> option. -</para></tip> - -</para></listitem> - -<listitem><para> -&kdesrc-build; allows you to checkout modules quickly. If the module you are checking out -has already been checked out previously, then &kdesrc-build; will download only commits -that are not yet on your computer. -</para> - -<tip><para>There is generally no need for any special preparation to perform -the initial checkout of a Git module, as the entire Git repository must be -downloaded anyways, so it is easy for the server to determine what to -send.</para></tip> - -<para>This is faster for you, and helps to ease the load on the kde.org -anonymous &git; servers.</para> -</listitem> - -<listitem><para> -Another speedup is provided by starting the build process for a module as soon -as the source code for that module has been downloaded. (Available since -version 1.6) -</para></listitem> - -<listitem><para> -Excellent support for building the &Qt; library (in case the &kde; software you -are trying to build depends on a recent &Qt; not available in your -distribution). -</para></listitem> - -<listitem><para> -&kdesrc-build; does not require a <acronym>GUI</acronym> present to operate. So, -you can build &kde; software without needing a graphical environment. -</para></listitem> - -<listitem><para> -Supports setting default options for all modules (such as the compilation -settings or the configuration options). Such options can normally be changed -for specific modules as well.</para> - -<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add -standard flags</link> as appropriate to save you the trouble and possible -errors from typing them yourself. Nota Bene: this does not apply when a (custom) -toolchain is configured through e.g.: -<link linkend="conf-cmake-toolchain">cmake-toolchain</link> -</para></listitem> - -<listitem><para> -&kdesrc-build; can checkout a specific <link linkend="using-branches">branch -or tag</link> of a module. You can also ensure that a specific <link -linkend="conf-revision">revision</link> is checked out of a module. -</para></listitem> - -<listitem><para> -&kdesrc-build; can automatically switch a source directory to checkout from -a different repository, branch, or tag. This happens automatically when you -change an option that changes what the repository &url; should be, but you must -use the <link linkend="cmdline-src-only">--src-only</link> option to let -&kdesrc-build; know that it is acceptable to perform the switch. -</para></listitem> - -<listitem><para> -&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a -module</link>, for those situations where you only need one program from a -large module. -</para></listitem> - -<listitem><para> -For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind -you</link> if you use git+ssh:// but <application>ssh-agent</application> is -not running, as this will lead to repeated password requests from -&ssh;. -</para></listitem> - -<listitem><para> -Can <link linkend="deleting-build-dir">delete the build directory</link> of a -module after its installation to save space at the expense of future compilation -time. -</para></listitem> - -<listitem><para> -The locations for the directories used by &kdesrc-build; are configurable (even -per module). -</para></listitem> - -<listitem><para> -Can use &sudo;, or a different user-specified command -to <link linkend="root-installation">install modules</link> so that -&kdesrc-build; does not need to be run as the super user. -</para></listitem> - -<listitem><para> -&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link> -by default to allow you to still use your computer while &kdesrc-build; is -working. -</para></listitem> - -<listitem><para> -Has support for using &kde;'s <link linkend="using-branches">tags and -branches</link>. -</para></listitem> - -<listitem><para> -There is support for <link linkend="resuming">resuming a build</link> from a -given module. You can even <link linkend="ignoring-modules">ignore some -modules</link> temporarily for a given build. -</para></listitem> - -<listitem><para> -&kdesrc-build; will show the <link linkend="build-progress">progress of your -build</link> when using &cmake;, and will always time the build -process so you know after the fact how long it took. -</para></listitem> - -<listitem><para> -Comes built-in with a sane set of default options appropriate for building -a base &kde; single-user installation from the anonymous source repositories. -</para></listitem> - -<listitem><para> -Tilde-expansion for your configuration options. For example, you can -specify: -<programlisting>qtdir ~/kdesrc/build/qt</programlisting> -</para></listitem> - -<listitem><para> -Automatically sets up a build system, with the source directory not the -same as the build directory, in order to keep the source directory -pristine. -</para></listitem> - -<listitem><para> -You can specify global options to apply to every module to check out, and -you can specify options to apply to individual modules as well. -</para></listitem> - -<listitem><para> -Forced full rebuilds, by running -&kdesrc-build; with the <option>--refresh-build</option> option. -</para></listitem> - -<listitem><para> -You can specify various environment values to be used during the build, -including <envar>QTDIR</envar>, <envar>DO_NOT_COMPILE</envar>, -and <envar>CXXFLAGS</envar>. -</para></listitem> - -<listitem><para> -Command logging. Logs are dated and numbered so that you always have a -log of a script run. Also, a special symlink called latest is created to -always point to the most recent log entry in the log directory. -</para></listitem> - -</itemizedlist> - -</sect1> - -<sect1 id="kdesrc-build-logging"> -<title>&kdesrc-build;'s build logging</title> - -<sect2 id="logging-overview"> -<title>Logging overview</title> - -<para>Logging is a &kdesrc-build; feature whereby the output from every command -that &kdesrc-build; runs is saved to a file for examination later, if -necessary. This is done because it is often necessary to have the output of -these programs when there is a build failure, because there are so many -reasons why a build can fail in the first place.</para> - -<sect3 id="log-directory-layout"> -<title>Logging directory layout</title> - -<para>The logs are always stored under the log directory. The destination of -the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link> -option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where -<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link> -option. The in rest of this section, this value will be referred to as -<symbol>${log-dir}</symbol>).</para> - -<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every -time that &kdesrc-build; was run. Each directory is named with the date, and -the run number. For instance, the second time that &kdesrc-build; is run on -May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>, -where the 2004-05-26 is for the date, and the -02 is the run number.</para> - -<para>For your convenience, &kdesrc-build; will also create a link to the -logs for your latest run, called <filename class="directory">latest</filename>. So the logs for -the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>. -</para> - -<para>Now, each directory for a &kdesrc-build; run will itself contain a set of -directories, one for every &kde; module that &kdesrc-build; tries to build. Also, -a file called <filename>build-status</filename> will be contained in the directory, -which will allow you to determine which modules built and which failed.</para> - -<note><para> -If a module itself has a submodule (such as extragear/multimedia, -playground/utils, or KDE/kdelibs), then there would actually be a matching -layout in the log directory. For example, the logs for KDE/kdelibs after the -last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>, -and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>. -</para></note> - -<para>In each module log directory, you will find a set of files for each -operation that &kdesrc-build; performs. If &kdesrc-build; updates a module, -you may see filenames such as <filename>git-checkout-update.log</filename> (for a -module checkout or when updating a module -that has already been checked out). If the <command>configure</command> -command was run, then you would expect to see a <filename>configure.log</filename> -in that directory.</para> - -<para>If an error occurred, you should be able to see an explanation of why in -one of the files. To help you determine which file contains the error, -&kdesrc-build; will create a link from the file containing the error (such as -<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para> - -<para>The upshot to all of this is that to see why a module failed to build -after your last &kdesrc-build;, the file you should look at first is -<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>. -</para> - -<tip><para>If the file <filename>error.log</filename> is empty (especially after -an installation), then perhaps there was no error. Some of the tools used by -the &kde; build system will sometimes mistakenly report an error when there was -none.</para> - -<para>Also, some commands will evade &kdesrc-build;'s output redirection and -bypass the log file in certain circumstances (normally when performing the -first &git; checkout), and the error output in that case is not in the log file -but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para> -</tip> - -</sect3> -</sect2> -</sect1> - -</chapter> +&features; <chapter id="kdesrc-buildrc"> <title>Configuring &kdesrc-build;</title>
