Git commit 7f814fbe007722d5c63c4b5ad011dbe85ba90765 by Andrew Shark. Committed on 05/01/2024 at 20:00. Pushed by ashark into branch 'master'.
doc: kdesrc-buildrc - separate docbook M +2 -231 doc/index.docbook A +231 -0 doc/kdesrc-buildrc.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/7f814fbe007722d5c63c4b5ad011dbe85ba90765 diff --git a/doc/index.docbook b/doc/index.docbook index 78e55044..f8b1b1a7 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -86,6 +86,7 @@ <!ENTITY kde-cmake SYSTEM "kde-cmake.docbook"> <!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"> ]> <book id="kdesrc-build" lang="&language;"> @@ -152,237 +153,7 @@ directly from the &kde; project's source code repositories.</para> &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> +&kdesrc-buildrc; &cmdline; diff --git a/doc/kdesrc-buildrc.docbook b/doc/kdesrc-buildrc.docbook new file mode 100644 index 00000000..53396e46 --- /dev/null +++ b/doc/kdesrc-buildrc.docbook @@ -0,0 +1,231 @@ +<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>
