Git commit a26d6653d49bb5284edf92a74569bca09f0c681e by Andrew Shark. Committed on 05/01/2024 at 19:56. Pushed by ashark into branch 'master'.
doc: advanced-features - separate docbook A +420 -0 doc/advanced-features.docbook M +6 -420 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/a26d6653d49bb5284edf92a74569bca09f0c681e diff --git a/doc/advanced-features.docbook b/doc/advanced-features.docbook new file mode 100644 index 00000000..edb19da7 --- /dev/null +++ b/doc/advanced-features.docbook @@ -0,0 +1,420 @@ +<sect1 id="advanced-features"> +<title>Advanced features</title> + +<sect2 id="partial-builds"> +<title>Partially building a module</title> +<para>It is possible to build only pieces from a single &kde; module. For +example, you may want to compile only one program from a module. &kdesrc-build; +has features to make this easy. There are several complementing ways to +do this. +</para> + +<sect3 id="not-compiling"> +<title>Removing directories from a build</title> +<para>It is possible to download an entire repository +but have the build system leave out a few directories when it does +the build. This requires that the module uses &cmake; and that the +module's build system allows the directory to remove to be +optional. +</para> + +<para>This is controlled with the &do-not-compile; option.</para> + +<important><para> +This option requires at least that the +build system for the module is reconfigured after changing +it. This is done using the <userinput><command>kdesrc-build</command> +<option>&cmd-reconfigure;</option> +<option><replaceable>module</replaceable></option></userinput> command. +</para></important> + +<informalexample> +<para>To remove the <filename class="directory">python</filename> directory +from the kdebindings build process:</para> + +<screen> +module <replaceable>kdebindings</replaceable> + &do-not-compile; <replaceable>python</replaceable> +end module +</screen> + +</informalexample> + +<note><para>This function depends on some standard conventions used in most +&kde; modules. Therefore it may not work for all programs.</para></note> + +</sect3> + +</sect2> + +<sect2 id="using-branches"> +<title>Branching and tagging support for &kdesrc-build;</title> + +<sect3 id="branches-and-tags"> +<title>What are branches and tags?</title> + +<para>&git; supports managing the history of the &kde; source code. &kde; +uses this support to create branches for development, and to tag the repository +every so often with a new version release. +</para> + +<para>For example, the &kmail; developers may be working on a new feature in +a different branch in order to avoid breaking the version being used by most +developers. This branch has development ongoing inside it, even while the +main branch (called master) may have development going on inside of it. +</para> + +<para>A tag, on the other hand, is a specified point in the source code repository +at a position in time. This is used by the &kde; administration team to mark +off a version of code suitable for release and still allow the developers to +work on the code. +</para> + +</sect3> + +<sect3 id="branch-support"> +<title>How to use branches and tags</title> + +<para>Support for branches and tags is handled by a set of options, which +range from a generic request for a version, to a specific &url; to download +for advanced users. +</para> + +<para>The easiest method is to use the &branch; and &tag; options. You simply +use the option along with the name of the desired branch or tag for a module, +and &kdesrc-build; will try to determine the appropriate location within the +&kde; repository to download from. For most &kde; modules this works very +well.</para> + +<informalexample> +<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch): +</para> + +<screen> +module kdelibs + branch <replaceable>4.6</replaceable> + # other options... +end module +</screen> + +<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para> + +<screen> +module kdemultimedia + tag <replaceable>4.6.1</replaceable> + # other options... +end module +</screen> + +</informalexample> + +<tip><para>You can specify a global branch value. But if you do so, do not forget +to specify a different branch for modules that should not use the global branch! +</para></tip> +</sect3> + +</sect2> + +<sect2 id="stopping-the-build-early"> +<title>Stopping the build early</title> + +<sect3 id="the-build-continues"> +<title>The build normally continues even if failures occur</title> + +<para>&kdesrc-build; normally will update, build and install all modules +in the specified list of modules to build, even if a module fails to build. +This is usually a convenience to allow you to update software packages even +if a simple mistake is made in one of the source repositories during +development that causes the build to break. +</para> + +<para> +However you may wish for &kdesrc-build; to stop what it is doing once a +module fails to build and install. This can help save you time that will be +wasted trying to make progress when modules remaining in the build list will +not be able to successfully build either, especially if you have not ever +successfully built the modules in the list. +</para> + +</sect3> + +<sect3 id="stop-on-failure-stops-early"> +<title>Not stopping early with --no-stop-on-failure</title> + +<para> +The primary method to do this is to use the +<link linkend="cmdline-stop-on-failure">--no-stop-on-failure</link> +command line option when you run &kdesrc-build;. +</para> + +<para>This option can also be set in the +<link linkend="conf-stop-on-failure">configuration file</link> to make +it the normal mode of operation. +</para> + +<para>It is also possible to tell &kdesrc-build; at runtime to stop building +<emphasis>after</emphasis> completing the current module it is working on. +This is as opposed to interrupting &kdesrc-build; using a command like +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, which interrupts +&kdesrc-build; immediately, losing the progress of the current module. +</para> + +<important><para>Interrupting &kdesrc-build; during a module install when +the <link linkend="conf-use-clean-install">use-clean-install</link> option +is enabled will mean that the interrupted module will be unavailable until +&kdesrc-build; is able to successfully build the module!</para> + +<para>If you need to interrupt &kdesrc-build; without permitting a graceful shutdown +in this situation, at least try to avoid doing this while &kdesrc-build; is +installing a module.</para> +</important> + +</sect3> + +<sect3 id="stopping-early-without-stop-on-failure"> +<title>Stopping &kdesrc-build; gracefully when stop-on-failure is false</title> + +<para>As mentioned above, it is possible to cause &kdesrc-build; to gracefully +shutdown early once it has completed the module it is currently working on. +To do this, you need to send the POSIX <literal>HUP</literal> signal to &kdesrc-build; +</para> + +<para>You can do this with a command such as <command>pkill</command> (on &Linux; systems) as follows:</para> + +<programlisting> +<prompt>$ </prompt><userinput><command>pkill <option>-HUP</option> kdesrc-build</command></userinput> +</programlisting> + +<para>If done successfully, you will see a message in the &kdesrc-build; output similar +to:</para> + +<programlisting> +[ build ] recv SIGHUP, will end after this module +</programlisting> + +<note> +<para>&kdesrc-build; may show this message multiple times depending on the +number of individual &kdesrc-build; processes that are active. This is +normal and not an indication of an error.</para> +</note> + +<para> +Once &kdesrc-build; has acknowledged the signal, it will stop processing +after the current module is built and installed. If &kdesrc-build; is still +updating source code when the request is received, &kdesrc-build; will stop +after the module source code update is complete. Once both the update and build +processes have stopped early, &kdesrc-build; will print its partial results +and exit. +</para> + +</sect3> + +</sect2> + +<sect2 id="building-successfully"> +<title>How &kdesrc-build; tries to ensure a successful build</title> + +<sect3 id="automatic-rebuilds"> +<title>Automatic rebuilds</title> + +<para>&kdesrc-build; used to include features to automatically attempt to +rebuild the module after a failure (as sometimes this re-attempt would work, +due to bugs in the build system at that time). Thanks to switching to &cmake; +the build system no longer suffers from these bugs, and so &kdesrc-build; will +not try to build a module more than once. There are situations where +&kdesrc-build; will automatically take action though:</para> + +<itemizedlist> + +<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link> +or <link linkend="conf-cmake-options">cmake-options</link> for a module, then +&kdesrc-build; will detect that and automatically re-run configure or cmake +for that module.</para></listitem> + +<listitem><para>If the buildsystem does not exist (even if &kdesrc-build; did +not delete it) then &kdesrc-build; will automatically re-create it. This is +useful to allow for performing a full <link +linkend="cmdline-refresh-build">--refresh-build</link> for a specific module +without having that performed on other modules.</para></listitem> + +</itemizedlist> + +</sect3> + +<sect3 id="manual-rebuilds"> +<title>Manually rebuilding a module</title> +<para>If you make a change to a module's option settings, or the module's +source code changes in a way &kdesrc-build; does not recognize, you may need to +manually rebuild the module.</para> + +<para>You can do this by simply running <userinput><command>kdesrc-build</command> + <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>. +</para> + +<para>If you would like to have &kdesrc-build; automatically rebuild the module +during the next normal build update instead, you can create a special file. +Every module has a build directory. If you create a file called <filename>.refresh-me</filename> +in the build directory for a module, &kdesrc-build; will rebuild the module +next time the build process occurs, even if it would normally perform the +faster incremental build.</para> + +<tip> +<para>By default, the build directory is <filename class="directory">~/kde/build/<replaceable>module</replaceable>/</filename>. +If you change the setting of the &build-dir; option, then use that instead of +<filename class="directory">~/kde/build</filename>.</para> +</tip> + +<informalexample> +<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para> +<screen> +<prompt>%</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput> +<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput> +</screen> +</informalexample> +</sect3> + +</sect2> + +<sect2 id="changing-environment"> +<title>Changing environment variable settings</title> +<para>Normally &kdesrc-build; uses the environment that is present when +starting up when running programs to perform updates and builds. This is useful +for when you are running &kdesrc-build; from the command line.</para> + +<para>However, you may want to change the setting for environment variables +that &kdesrc-build; does not provide an option for directly. (For instance, +to setup any required environment variables when running &kdesrc-build; on +a timer such as &cron;) This is possible with the &set-env; option.</para> + +<para>Unlike most options, it can be set more than once, and it accepts two +entries, separated by a space. The first one is the name of the environment +variable to set, and the remainder of the line is the value.</para> + +<informalexample> +<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput> +for all modules:</para> +<screen> +global + set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable> +end global +</screen> +</informalexample> + +</sect2> + +<sect2 id="resuming"> +<title>Resuming builds</title> + +<sect3 id="resuming-failed"> +<title>Resuming a failed or canceled build</title> + +<para>You can tell &kdesrc-build; to start building from a different module +than it normally would. This can be useful when a set of modules failed, or +if you canceled a build run in the middle. You can control this using the +&cmd-resume-from; option and the &cmd-resume-after; option.</para> + +<note><para>Older versions of &kdesrc-build; would skip the source update when +resuming a build. This is no longer done by default, but you can always use +the <option>--no-src</option> command line option +to skip the source update.</para></note> + +<informalexample> +<para>Resuming the build starting from kdebase:</para> + +<screen> +<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput> +</screen> +</informalexample> + +<informalexample> +<para>Resuming the build starting after kdebase (in case you manually fixed +the issue and installed the module yourself):</para> + +<screen> +<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput> +</screen> +</informalexample> + +<para>If the last &kdesrc-build; build ended with a build failure, you can also +use the <link linkend="cmdline-resume">--resume</link> command line option, +which resumes the last build starting at the module that failed. The source and +metadata updates are skipped as well (but if you need these, it's generally +better to use <link linkend="cmdline-resume-from">--resume-from</link> +instead).</para> + + +</sect3> + +<sect3 id="ignoring-modules"> +<title>Ignoring modules in a build</title> + +<para>Similar to the way you can <link linkend="resuming-failed">resume the +build from a module</link>, you can instead choose to update and build everything +normally, but ignore a set of modules.</para> + +<para>You can do this using the &cmd-ignore-modules; option. This option tells +&kdesrc-build; to ignore all the modules on the command line when +performing the update and build.</para> + +<informalexample> +<para>Ignoring extragear/multimedia and kdereview during a full run:</para> +<screen> +<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput> +</screen> +</informalexample> + +</sect3> +</sect2> + +<sect2 id="changing-env-from-cmd-line"> +<title>Changing options from the command line</title> + +<sect3 id="changing-global-opts"> +<title>Changing global options</title> +<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> directly +from the command line. This change will override the configuration file +setting, but is only temporary. It only takes effect as long as it is still +present on the command line.</para> + +<para>&kdesrc-build; allows you to change options named like <replaceable>option-name</replaceable> +by passing an argument on the command line in the form <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>. +&kdesrc-build; will recognize whether it does not know what the option is, and search +for the name in its list of option names. If it does not recognize the name, it +will warn you, otherwise it will remember the value you set it to and override +any setting from the configuration file.</para> + +<informalexample> +<para>Setting the &source-dir; option to <filename>/dev/null</filename> for +testing:</para> + +<screen> +<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput> +</screen> + +</informalexample> + +</sect3> + +<sect3 id="changing-module-opts"> +<title>Changing module options</title> +<para>It is also possible to change options only for a specific module. The +syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>. +</para> + +<para>This change overrides any duplicate setting for the module found in the +<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para> + +<informalexample> +<para>Using a different build directory for the kdeedu module:</para> + +<screen> +<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput> +</screen> + +</informalexample> + +</sect3> + +</sect2> + +</sect1> diff --git a/doc/index.docbook b/doc/index.docbook index 55e0c874..228b67bb 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -63,6 +63,11 @@ <!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"> ]> <book id="kdesrc-build" lang="&language;"> @@ -4164,426 +4169,7 @@ build a module. </sect1> -<sect1 id="advanced-features"> -<title>Advanced features</title> - -<sect2 id="partial-builds"> -<title>Partially building a module</title> -<para>It is possible to build only pieces from a single &kde; module. For -example, you may want to compile only one program from a module. &kdesrc-build; -has features to make this easy. There are several complementing ways to -do this. -</para> - -<sect3 id="not-compiling"> -<title>Removing directories from a build</title> -<para>It is possible to download an entire repository -but have the build system leave out a few directories when it does -the build. This requires that the module uses &cmake; and that the -module's build system allows the directory to remove to be -optional. -</para> - -<para>This is controlled with the &do-not-compile; option.</para> - -<important><para> -This option requires at least that the -build system for the module is reconfigured after changing -it. This is done using the <userinput><command>kdesrc-build</command> -<option>&cmd-reconfigure;</option> -<option><replaceable>module</replaceable></option></userinput> command. -</para></important> - -<informalexample> -<para>To remove the <filename class="directory">python</filename> directory -from the kdebindings build process:</para> - -<screen> -module <replaceable>kdebindings</replaceable> - &do-not-compile; <replaceable>python</replaceable> -end module -</screen> - -</informalexample> - -<note><para>This function depends on some standard conventions used in most -&kde; modules. Therefore it may not work for all programs.</para></note> - -</sect3> - -</sect2> - -<sect2 id="using-branches"> -<title>Branching and tagging support for &kdesrc-build;</title> - -<sect3 id="branches-and-tags"> -<title>What are branches and tags?</title> - -<para>&git; supports managing the history of the &kde; source code. &kde; -uses this support to create branches for development, and to tag the repository -every so often with a new version release. -</para> - -<para>For example, the &kmail; developers may be working on a new feature in -a different branch in order to avoid breaking the version being used by most -developers. This branch has development ongoing inside it, even while the -main branch (called master) may have development going on inside of it. -</para> - -<para>A tag, on the other hand, is a specified point in the source code repository -at a position in time. This is used by the &kde; administration team to mark -off a version of code suitable for release and still allow the developers to -work on the code. -</para> - -</sect3> - -<sect3 id="branch-support"> -<title>How to use branches and tags</title> - -<para>Support for branches and tags is handled by a set of options, which -range from a generic request for a version, to a specific &url; to download -for advanced users. -</para> - -<para>The easiest method is to use the &branch; and &tag; options. You simply -use the option along with the name of the desired branch or tag for a module, -and &kdesrc-build; will try to determine the appropriate location within the -&kde; repository to download from. For most &kde; modules this works very -well.</para> - -<informalexample> -<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch): -</para> - -<screen> -module kdelibs - branch <replaceable>4.6</replaceable> - # other options... -end module -</screen> - -<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para> - -<screen> -module kdemultimedia - tag <replaceable>4.6.1</replaceable> - # other options... -end module -</screen> - -</informalexample> - -<tip><para>You can specify a global branch value. But if you do so, do not forget -to specify a different branch for modules that should not use the global branch! -</para></tip> -</sect3> - -</sect2> - -<sect2 id="stopping-the-build-early"> -<title>Stopping the build early</title> - -<sect3 id="the-build-continues"> -<title>The build normally continues even if failures occur</title> - -<para>&kdesrc-build; normally will update, build and install all modules -in the specified list of modules to build, even if a module fails to build. -This is usually a convenience to allow you to update software packages even -if a simple mistake is made in one of the source repositories during -development that causes the build to break. -</para> - -<para> -However you may wish for &kdesrc-build; to stop what it is doing once a -module fails to build and install. This can help save you time that will be -wasted trying to make progress when modules remaining in the build list will -not be able to successfully build either, especially if you have not ever -successfully built the modules in the list. -</para> - -</sect3> - -<sect3 id="stop-on-failure-stops-early"> -<title>Not stopping early with --no-stop-on-failure</title> - -<para> -The primary method to do this is to use the -<link linkend="cmdline-stop-on-failure">--no-stop-on-failure</link> -command line option when you run &kdesrc-build;. -</para> - -<para>This option can also be set in the -<link linkend="conf-stop-on-failure">configuration file</link> to make -it the normal mode of operation. -</para> - -<para>It is also possible to tell &kdesrc-build; at runtime to stop building -<emphasis>after</emphasis> completing the current module it is working on. -This is as opposed to interrupting &kdesrc-build; using a command like -<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, which interrupts -&kdesrc-build; immediately, losing the progress of the current module. -</para> - -<important><para>Interrupting &kdesrc-build; during a module install when -the <link linkend="conf-use-clean-install">use-clean-install</link> option -is enabled will mean that the interrupted module will be unavailable until -&kdesrc-build; is able to successfully build the module!</para> - -<para>If you need to interrupt &kdesrc-build; without permitting a graceful shutdown -in this situation, at least try to avoid doing this while &kdesrc-build; is -installing a module.</para> -</important> - -</sect3> - -<sect3 id="stopping-early-without-stop-on-failure"> -<title>Stopping &kdesrc-build; gracefully when stop-on-failure is false</title> - -<para>As mentioned above, it is possible to cause &kdesrc-build; to gracefully -shutdown early once it has completed the module it is currently working on. -To do this, you need to send the POSIX <literal>HUP</literal> signal to &kdesrc-build; -</para> - -<para>You can do this with a command such as <command>pkill</command> (on &Linux; systems) as follows:</para> - -<programlisting> -<prompt>$ </prompt><userinput><command>pkill <option>-HUP</option> kdesrc-build</command></userinput> -</programlisting> - -<para>If done successfully, you will see a message in the &kdesrc-build; output similar -to:</para> - -<programlisting> -[ build ] recv SIGHUP, will end after this module -</programlisting> - -<note> -<para>&kdesrc-build; may show this message multiple times depending on the -number of individual &kdesrc-build; processes that are active. This is -normal and not an indication of an error.</para> -</note> - -<para> -Once &kdesrc-build; has acknowledged the signal, it will stop processing -after the current module is built and installed. If &kdesrc-build; is still -updating source code when the request is received, &kdesrc-build; will stop -after the module source code update is complete. Once both the update and build -processes have stopped early, &kdesrc-build; will print its partial results -and exit. -</para> - -</sect3> - -</sect2> - -<sect2 id="building-successfully"> -<title>How &kdesrc-build; tries to ensure a successful build</title> - -<sect3 id="automatic-rebuilds"> -<title>Automatic rebuilds</title> - -<para>&kdesrc-build; used to include features to automatically attempt to -rebuild the module after a failure (as sometimes this re-attempt would work, -due to bugs in the build system at that time). Thanks to switching to &cmake; -the build system no longer suffers from these bugs, and so &kdesrc-build; will -not try to build a module more than once. There are situations where -&kdesrc-build; will automatically take action though:</para> - -<itemizedlist> - -<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link> -or <link linkend="conf-cmake-options">cmake-options</link> for a module, then -&kdesrc-build; will detect that and automatically re-run configure or cmake -for that module.</para></listitem> - -<listitem><para>If the buildsystem does not exist (even if &kdesrc-build; did -not delete it) then &kdesrc-build; will automatically re-create it. This is -useful to allow for performing a full <link -linkend="cmdline-refresh-build">--refresh-build</link> for a specific module -without having that performed on other modules.</para></listitem> - -</itemizedlist> - -</sect3> - -<sect3 id="manual-rebuilds"> -<title>Manually rebuilding a module</title> -<para>If you make a change to a module's option settings, or the module's -source code changes in a way &kdesrc-build; does not recognize, you may need to -manually rebuild the module.</para> - -<para>You can do this by simply running <userinput><command>kdesrc-build</command> - <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>. -</para> - -<para>If you would like to have &kdesrc-build; automatically rebuild the module -during the next normal build update instead, you can create a special file. -Every module has a build directory. If you create a file called <filename>.refresh-me</filename> -in the build directory for a module, &kdesrc-build; will rebuild the module -next time the build process occurs, even if it would normally perform the -faster incremental build.</para> - -<tip> -<para>By default, the build directory is <filename class="directory">~/kde/build/<replaceable>module</replaceable>/</filename>. -If you change the setting of the &build-dir; option, then use that instead of -<filename class="directory">~/kde/build</filename>.</para> -</tip> - -<informalexample> -<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para> -<screen> -<prompt>%</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput> -<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput> -</screen> -</informalexample> -</sect3> - -</sect2> - -<sect2 id="changing-environment"> -<title>Changing environment variable settings</title> -<para>Normally &kdesrc-build; uses the environment that is present when -starting up when running programs to perform updates and builds. This is useful -for when you are running &kdesrc-build; from the command line.</para> - -<para>However, you may want to change the setting for environment variables -that &kdesrc-build; does not provide an option for directly. (For instance, -to setup any required environment variables when running &kdesrc-build; on -a timer such as &cron;) This is possible with the &set-env; option.</para> - -<para>Unlike most options, it can be set more than once, and it accepts two -entries, separated by a space. The first one is the name of the environment -variable to set, and the remainder of the line is the value.</para> - -<informalexample> -<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput> -for all modules:</para> -<screen> -global - set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable> -end global -</screen> -</informalexample> - -</sect2> - -<sect2 id="resuming"> -<title>Resuming builds</title> - -<sect3 id="resuming-failed"> -<title>Resuming a failed or canceled build</title> - -<para>You can tell &kdesrc-build; to start building from a different module -than it normally would. This can be useful when a set of modules failed, or -if you canceled a build run in the middle. You can control this using the -&cmd-resume-from; option and the &cmd-resume-after; option.</para> - -<note><para>Older versions of &kdesrc-build; would skip the source update when -resuming a build. This is no longer done by default, but you can always use -the <option>--no-src</option> command line option -to skip the source update.</para></note> - -<informalexample> -<para>Resuming the build starting from kdebase:</para> - -<screen> -<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput> -</screen> -</informalexample> - -<informalexample> -<para>Resuming the build starting after kdebase (in case you manually fixed -the issue and installed the module yourself):</para> - -<screen> -<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput> -</screen> -</informalexample> - -<para>If the last &kdesrc-build; build ended with a build failure, you can also -use the <link linkend="cmdline-resume">--resume</link> command line option, -which resumes the last build starting at the module that failed. The source and -metadata updates are skipped as well (but if you need these, it's generally -better to use <link linkend="cmdline-resume-from">--resume-from</link> -instead).</para> - - -</sect3> - -<sect3 id="ignoring-modules"> -<title>Ignoring modules in a build</title> - -<para>Similar to the way you can <link linkend="resuming-failed">resume the -build from a module</link>, you can instead choose to update and build everything -normally, but ignore a set of modules.</para> - -<para>You can do this using the &cmd-ignore-modules; option. This option tells -&kdesrc-build; to ignore all the modules on the command line when -performing the update and build.</para> - -<informalexample> -<para>Ignoring extragear/multimedia and kdereview during a full run:</para> -<screen> -<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput> -</screen> -</informalexample> - -</sect3> -</sect2> - -<sect2 id="changing-env-from-cmd-line"> -<title>Changing options from the command line</title> - -<sect3 id="changing-global-opts"> -<title>Changing global options</title> -<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> directly -from the command line. This change will override the configuration file -setting, but is only temporary. It only takes effect as long as it is still -present on the command line.</para> - -<para>&kdesrc-build; allows you to change options named like <replaceable>option-name</replaceable> -by passing an argument on the command line in the form <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>. -&kdesrc-build; will recognize whether it does not know what the option is, and search -for the name in its list of option names. If it does not recognize the name, it -will warn you, otherwise it will remember the value you set it to and override -any setting from the configuration file.</para> - -<informalexample> -<para>Setting the &source-dir; option to <filename>/dev/null</filename> for -testing:</para> - -<screen> -<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput> -</screen> - -</informalexample> - -</sect3> - -<sect3 id="changing-module-opts"> -<title>Changing module options</title> -<para>It is also possible to change options only for a specific module. The -syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>. -</para> - -<para>This change overrides any duplicate setting for the module found in the -<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para> - -<informalexample> -<para>Using a different build directory for the kdeedu module:</para> - -<screen> -<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput> -</screen> - -</informalexample> - -</sect3> - -</sect2> - -</sect1> +&advanced-features; <sect1 id="developer-features"> <title>Features for &kde; developers</title>