Git commit 7007b74dca24ce9aa44ee2d545ff1d3d92e59f34 by Michael Pyne. Committed on 08/09/2011 at 02:15. Pushed by ashark into branch 'docbook_historied_per_file'.
doc: Improve rc-file layout documentation. Really this was mostly an excuse to document the new "include" feature. Original commit: 2d0f0bf6 https://invent.kde.org/sdk/kdesrc-build/-/commit/2d0f0bf661aebb7f5ed487c7253fde1a38bc8790 M +84 -14 doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/7007b74dca24ce9aa44ee2d545ff1d3d92e59f34 diff --git a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook index 33fe1c66..8db8c20f 100644 --- a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook +++ b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook @@ -7,8 +7,15 @@ To use the script, you must have a file in your home directory called like to download and build. </para> +<sect2 id="kdesrc-buildrc-layout"> +<title>Layout of the configuration file</title> + +<sect3 id="kdesrc-buildrc-layout-global"> +<title>Global configuration</title> + <para> -It starts with the global options, specified like the following: +The configuration file starts with the global options, specified like the +following: </para> <programlisting> @@ -18,24 +25,91 @@ global 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 like the -following: +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 Subversion modules, <replaceable>module-name</replaceable> must be a module +from the &kde; &subversion; repository (for example, kdeartwork or +kde-wallpapers), although it is possible to get around this if you manually +specify the &subversion; URL. +</para> <para> -<replaceable>module-name</replaceable> must be a module from the &kde; &subversion; repository (for -example, kdelibs or kdebase). Some options override global options, some -add to global options, and some global options simply cannot be overridden. +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> +</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> + +</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 @@ -43,18 +117,14 @@ option to find out more about it. To see the full list of options, see </para> <itemizedlist> -<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk.</para></listitem> -<listitem><para><link linkend="conf-build-dir">build-dir</link>, to set the directory to build in.</para></listitem> <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-configure-flags">configure-flags</link> to define what flags to configure a module with.</para></listitem> -<listitem><para><link linkend="conf-cxxflags">cxxflags</link> to define the <envar>CXXFLAGS</envar> variable.</para></listitem> +<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk (for &subversion;) or <literal>master</literal> (for Git).</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-kdedir">kdedir</link>, to set the directory to install &kde; to.</para></listitem> -<listitem><para><link linkend="conf-kde-languages">kde-languages</link>, to set the translation packages to download and install.</para></listitem> -<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program.</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-set-env">set-env</link>, to set an environment variable.</para></listitem> <listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem> -<listitem><para><link linkend="conf-svn-server">svn-server</link>, to change the server the sources are downloaded from.</para></listitem> </itemizedlist> +</sect2> </sect1>
