Git commit 4c8ef70683eb7eaa5890cfa4e7206dc401b42e57 by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'.
doc: other-features - separate docbook M +2 -142 doc/index.docbook A +142 -0 doc/other-features.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/4c8ef70683eb7eaa5890cfa4e7206dc401b42e57 diff --git a/doc/index.docbook b/doc/index.docbook index f8b1b1a7..7592879a 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -87,6 +87,7 @@ <!ENTITY kde-modules-and-selection SYSTEM "kde-modules-and-selection.docbook"> <!ENTITY kdesrc-build-logging SYSTEM "kdesrc-build-logging.docbook"> <!ENTITY kdesrc-buildrc SYSTEM "kdesrc-buildrc.docbook"> + <!ENTITY other-features SYSTEM "other-features.docbook"> ]> <book id="kdesrc-build" lang="&language;"> @@ -184,148 +185,7 @@ do with this tool.</para> &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> +&other-features; </chapter> diff --git a/doc/other-features.docbook b/doc/other-features.docbook new file mode 100644 index 00000000..96215a58 --- /dev/null +++ b/doc/other-features.docbook @@ -0,0 +1,142 @@ +<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>
