Git commit 1b492e677631307a633f825399c80711da4191c2 by Michael Pyne. Committed on 02/05/2007 at 02:55. Pushed by ashark into branch 'docbook_historied_per_file'.
Revise and modernize the documentation/help text for kdesvn-build a bit. Unless something breaks for someone overnight this will be kdesvn-build 1.4 tomorrow. svn path=/trunk/KDE/kdesdk/doc/scripts/kdesvn-build/; revision=660238 Original commit: 2da73860 https://invent.kde.org/sdk/kdesrc-build/-/commit/2da73860ea586c164617dacdc319cb8bb658ac41 M +30 -44 doc/features/features-overview.docbook M +18 -8 doc/getting-started/before-building.docbook M +7 -3 doc/getting-started/building-and-troubleshooting.docbook M +14 -1 doc/getting-started/configure-data.docbook M +3 -2 doc/index.docbook M +53 -36 doc/kdesvn-buildrc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/1b492e677631307a633f825399c80711da4191c2 diff --git a/doc/features/features-overview.docbook b/doc/features/features-overview.docbook index 469ace2c..29cdf83a 100644 --- a/doc/features/features-overview.docbook +++ b/doc/features/features-overview.docbook @@ -9,7 +9,8 @@ <listitem><para> For developers: Supports <link linkend="building-apidox">building the API -documentation</link> for a module. +documentation</link> for a module. Note that this only works for KDE 3 +modules when not using the unsermake script. </para></listitem> <listitem><para> @@ -18,10 +19,12 @@ ranging from being very quiet to a full debug level. </para></listitem> <listitem><para> -&kdesvn-build; can, with the assistance of the <ulink url="http://kdesvn-build.kde.org/";>kdesvn-build website</ulink>, -allow for speedy checkouts of some modules. If the module you are checking out -has already been packaged at the website, then kdesvn-build will download the -snapshot and prepare it for use on your computer. +&kdesvn-build; can, with the assistance of the <ulink +url="http://kdesvn-build.kde.org/";>kdesvn-build website</ulink> and the +KDE FTP server (FTP since &kdesvn-build; 1.4), allow for speedy checkouts of +some modules. If the module you are checking out has already been packaged at +the website, then kdesvn-build will download the snapshot and prepare it for +use on your computer. </para> <para>This is faster for you, and helps to ease the load on the kde.org @@ -53,6 +56,20 @@ standard flags</link> as appropriate to save you the trouble and possible errors from typing them yourself. </para></listitem> +<listitem><para> +&kdesvn-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> +&kdesvn-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-svn-only">--svn-only</link> option to let +&kdesvn-build; know that it is acceptable to perform the switch. +</para></listitem> + <listitem><para> &kdesvn-build; can <link linkend="partial-builds">checkout only portions of a module</link>, for those situations where you only need one program from a @@ -60,9 +77,9 @@ large module. </para></listitem> <listitem><para> -For developers: Will <link linkend="ssh-agent-reminder">remind you</link> if -you use svn+ssh:// but <application>ssh-agent</application> is not running, as -this will lead to repeated password requests from +For developers: &kdesvn-build; will <link linkend="ssh-agent-reminder">remind +you</link> if you use svn+ssh:// but <application>ssh-agent</application> is +not running, as this will lead to repeated password requests from <application>ssh</application>. </para></listitem> @@ -109,16 +126,6 @@ given module. You can even <link linkend="ignoring-modules">ignore some modules</link> temporarily for a given build. </para></listitem> -<listitem><para> -&kdesvn-build; also supports using the ~/ sequence to stand for your home -directory in the &rcfile;. -</para></listitem> - -<listitem><para> -Automatically checks out or updates modules from &svn;, as -appropriate. -</para></listitem> - <listitem><para> &kdesvn-build; can quickly perform a <link linkend="partial-builds">partial build</link> of a module directly from the command line, when you only need @@ -128,13 +135,14 @@ to update part of a module. <listitem><para> &kdesvn-build; will automatically download and create the required <filename>/admin</filename> directory for a module if it isn't downloaded from &svn; the first time for -some reason. +some reason. This only applies to KDE 3 modules, as /admin is not required +for qt-copy or KDE 4 modules. </para></listitem> <listitem><para> &kdesvn-build; will show the <link linkend="build-progress">progress of your -build</link> when using &unsermake;, and will always time the build process so -you know after the fact how long it took. +build</link> when using &unsermake; and CMake, and will always time the build +process so you know after the fact how long it took. </para></listitem> <listitem><para> @@ -142,10 +150,6 @@ Automatically tries to rebuild modules that were using incremental make, which is prone to failure after certain kinds of commits. </para></listitem> -<listitem><para> -Can resume a build from a particular module. -</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 &svn; repository. @@ -161,16 +165,10 @@ specify: <programlisting>qtdir ~/kdesvn/build/qt-copy</programlisting> </para></listitem> -<listitem><para> -Configurable build, source, and logging directories -</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. The exception is <application>qt-copy</application>, which is not designed to be built like -that (unless you would like to test the -<link linkend="conf-use-qt-builddir-hack"><quote>qt with a separate build directory hack</quote></link>). +pristine. </para></listitem> <listitem><para> @@ -210,11 +208,6 @@ prefix the make install command line with a separate command, which is useful for sudo. </para></listitem> -<listitem><para> -You can use the <link linkend="conf-apidox">apidox</link> option to automatically -build and install the API documentation for some modules. -</para></listitem> - <listitem><para> You can check out only a portion of a &kde; &svn; module. For example, you could check out only the <application>taglib</application> from @@ -230,13 +223,6 @@ command line, the script will give a very verbose description of the commands it is about to execute, without actually executing it. </para></listitem> -<listitem><para> -Support for checking out specific branches of &svn; -modules. This work still needs to be completed, but you already select the branch you -want to build using the <link linkend="conf-module-base-path">module-base-path -configuration option</link>. -</para></listitem> - </itemizedlist> </sect1> diff --git a/doc/getting-started/before-building.docbook b/doc/getting-started/before-building.docbook index 8e189be7..81c6acb7 100644 --- a/doc/getting-started/before-building.docbook +++ b/doc/getting-started/before-building.docbook @@ -40,10 +40,8 @@ Requirements</ulink> page. <listitem><para>Autoconf version 2.57, or higher. (KDE 3 only)</para></listitem> <listitem><para><ulink -url="http://www.cmake.org/";><application>CMake</application></ulink> 2.4.0, or -higher. Some version 2.3 snapshots may compile KDE 4 as well, please see the -<ulink url="http://wiki.kde.org/tiki-index.php?page=KDECMakeIntro";>CMake Introduction Wiki</ulink> page. (KDE 4 -only)</para></listitem> +url="http://www.cmake.org/";><application>CMake</application></ulink> 2.4.5, or +higher.</para></listitem> <listitem><para>The &svn; client program, including support for Secure HTTP (https). To ensure needed support, you can run @@ -51,8 +49,8 @@ HTTP (https). To ensure needed support, you can run If the ra_dav module says that it handles the https scheme then you should be set to go.</para></listitem> -<listitem><para>The gcc compiler, with support for C++. Version 3.3 or 3.4 works -the best at this point.</para></listitem> +<listitem><para>The gcc compiler, with support for C++. Versions 3.3 or higher +are the best supported.</para></listitem> <listitem><para>Be sure to check the <ulink url="http://www.kde.org/info/requirements/3.5.php";>&kde; Compilation @@ -81,7 +79,13 @@ to have it. If you don't want to use the &Qt; copy, you need to do these things <listitem> <para>If you don't already have &Qt; installed, install it, including any relevant -dev or -devel packages. You'll need at least &Qt; 3.3 if you're - building &kde; 3.5, or &Qt; 4.0 if you're building &kde; 4.</para> + building &kde; 3.5, or &Qt; 4.3 if you're building &kde; 4.</para> + + <note><para>If you are building &kde; 4 it is highly recommended to use the + qt-copy version of &Qt;, making sure to apply recommended patches (this is + the default setting, controlled by the <link + linkend="conf-apply-qt-patches">apply-qt-patches + option</link>).</para></note> </listitem> </itemizedlist> @@ -110,6 +114,12 @@ in your system. However, if you don't, you can download it from &homepage;, or you can find it from its home in the &kde; source repository.</para> +<note><para>&kdesvn-build; is included with the kdesdk module, and the module +is often installed by distributions already. If you have downloaded +&kdesvn-build; ensure that you are using the version you downloaded. You can +use the --version option to be sure you are running the version you think +you are.</para></note> + <orderedlist> <listitem><para>To download &kdesvn-build; from its &homepage;, simply go to the &homepage; and download the latest appropriate release. The release is @@ -131,7 +141,7 @@ if you need to.</para></listitem> <filename>kdesvn-build</filename> file is executable. For convenience you should make sure it is in a directory contained in the <envar>PATH</envar> environment variable, otherwise you may get messages saying that the command -was not found.</para> +was not found, or you may run a previously-installed version by mistake.</para> </sect3> <sect3 id="setup-rcfile"> diff --git a/doc/getting-started/building-and-troubleshooting.docbook b/doc/getting-started/building-and-troubleshooting.docbook index 6472d0bc..a79b34d0 100644 --- a/doc/getting-started/building-and-troubleshooting.docbook +++ b/doc/getting-started/building-and-troubleshooting.docbook @@ -23,9 +23,13 @@ the caused an error for a module in the last &kdesvn-build; command, usually it is sufficient to look at <filename>~/kdesvn/log/latest/<replaceable>module-name</replaceable>/error.log</filename>.</para> <para>In that file, you will see the error that caused the build to fail for -that module. If the file says (at the bottom) that you're missing some packages, -try installing the package (including any appropriate -dev packages) before -trying to build that module. Or, if the error appears to be a build error +that module. If the file says (at the bottom) that you're missing some +packages, try installing the package (including any appropriate -dev packages) +before trying to build that module, and pass the <link +linkend="cmdline-reconfigure">--reconfigure</link> option after install the +missing packages.</para> + +<para>Or, if the error appears to be a build error then it is probably an error with the &kde; source, which will hopefully be resolved within a few days. If it isn't resolved within that time, feel free to mail the <email>[email protected]</email> (subscription may be required first) diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook index 3d3f92bc..5784f6e2 100644 --- a/doc/getting-started/configure-data.docbook +++ b/doc/getting-started/configure-data.docbook @@ -27,12 +27,25 @@ The default settings should actually already be appropriate to perform a <listitem><para><link linkend="conf-binpath">binpath</link>, to change the list of directories that will be searched for commands. This is exactly the same as the <envar>PATH</envar> variable in the shell.</para></listitem> + +<listitem><para><link linkend="conf-use-stable-kde">use-stable-kde</link> to +change the default version to build of KDE modules. By default &kdesvn-build; +will build the trunk version of KDE (currently KDE 4). If you want to build +the latest stable release of KDE instead of using your distribution packages +(right now the KDE 3.5 branch is stable) you would set this option to true. +</para></listitem> + <listitem><para><link linkend="conf-kdedir">kdedir</link>, which changes the destination directory that &kde; is installed to. This defaults to <filename>~/kde</filename>, which is a single-user installation.</para></listitem> + <listitem><para><link linkend="conf-qtdir">qtdir</link>, which controls the path to the installation of &Qt; to use. The defaults to using the qt-copy -module from the &kde; &svn; repository. (<filename>~/kdesvn/build/qt-copy</filename>)</para></listitem> +module from the &kde; &svn; repository. (<filename>~/kdesvn/build/qt-copy</filename>)</para> + +<para>For Qt versions that support installation, this also controls where to +install qt-copy.</para></listitem> + <listitem><para><link linkend="conf-svn-server">svn-server</link>, which selects what URL to download the sources from. This is useful if you are a developer with a <ulink url="http://developer.kde.org/documentation/misc/firststepsaccount.php";>&kde; diff --git a/doc/index.docbook b/doc/index.docbook index 55c30164..87877841 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -98,6 +98,7 @@ <copyright> <year>2006</year> +<year>2007</year> <holder>Michael Pyne</holder> </copyright> @@ -109,8 +110,8 @@ <legalnotice>&FDLNotice;</legalnotice> -<date>2006-03-28</date> -<releaseinfo>1.1</releaseinfo> +<date>2007-05-01</date> +<releaseinfo>1.4</releaseinfo> <abstract> <para>&kdesvn-build; is a script which builds and installs &kde; directly from the sources found in the &kde; &svn; repository.</para> diff --git a/doc/kdesvn-buildrc/index.docbook b/doc/kdesvn-buildrc/index.docbook index 496e1774..72b354c0 100644 --- a/doc/kdesvn-buildrc/index.docbook +++ b/doc/kdesvn-buildrc/index.docbook @@ -107,7 +107,9 @@ process. This only works for modules where <command>make apidox</command> does including kdelibs, kdebase, and koffice, among others. </para> <para>This option does not work for modules using &unsermake; support, due to -deficiencies in the unsermake build system. +deficiencies in the &unsermake; build system. This option does not work for +KDE 4 modules because the required build system support has been migrated to +a different program which &kdesvn-build; has not been corrected to use yet. </para> </entry> </row> @@ -144,7 +146,7 @@ default of "trunk", where &kde; development occurs. For instance, to checkout <para>Note that some modules use a different branch name. Notably, the required arts module doesn't go by &kde; version numbers. The arts that accompanied &kde; 3.4 was version 1.4.</para> -<para>If kdesvn-build fails to properly download a branch with this option, you +<para>If &kdesvn-build; fails to properly download a branch with this option, you may have to manually specify the URL to download from using the <link linkend="conf-override-url">override-url</link> option.</para> </entry> @@ -265,7 +267,7 @@ extragear-network using this option. <entry>disable-agent-check</entry> <entry>Can't be overridden</entry> <entry>Normally if you're using SSH to download the Subversion sources (such as -if you're using the svn+ssh protocol), kdesvn-build will try and make sure that +if you're using the svn+ssh protocol), &kdesvn-build; will try and make sure that if you're using ssh-agent, it is actually managing some SSH identities. This is to try and prevent SSH from asking for your pass phrase for every module. You can disable this check by setting disable-agent-check to true. @@ -286,7 +288,7 @@ the <link linkend="conf-checkout-only">checkout-only</link> directive to choose directories that you want to check out.</para> <important><para>This option does not yet work with modules built using -&cmake;</para></important> +&cmake;.</para></important> </entry> </row> @@ -294,7 +296,7 @@ directive to choose directories that you want to check out.</para> <entry>email-address</entry> <entry>Can't be overridden</entry> <entry> -<para>Set this option to the e-mail address kdesvn-build should send from should +<para>Set this option to the e-mail address &kdesvn-build; should send from should it ever need to send e-mail. You do not need to worry about this if you don't use any feature which send e-mail. (They are all disabled by default). </para> @@ -310,13 +312,13 @@ needs this option. <entry>Can't be overridden</entry> <entry> <para>You can set this option to the email address to send a report to when a -module fails to build. kdesvn-build will wait until all the modules are done +module fails to build. &kdesvn-build; will wait until all the modules are done and collate all of the results in the report. The report is only sent if a module fails to build. </para> <para>Please see the <link linkend="conf-email-address">email-address</link> -option to set the address kdesvn-build should send from, since the default +option to set the address &kdesvn-build; should send from, since the default is usually not what you want. </para> </entry> @@ -422,12 +424,9 @@ please be careful while dealing with root privileges.</entry> <entry>Overrides global</entry> <entry>Set this variable in order to pass command line options to the make command. This is useful for programs such as <ulink -url="http://distcc.samba.org/";><application>distcc</application></ulink>. -<application>distcc</application> allows you to share your -compilation work among more than one computer. To use it, you must use the -<option>-j</option> option to make. Now you can. According to the docs, 2 * -number_of_network_cpus is recommended. I have 1 CPU total, so it would be -<option>-j2</option> in my case.</entry> +url="http://distcc.samba.org/";><application>distcc</application></ulink> or +systems with more than one processor core. +</entry> </row> <row id="conf-manual-build"> @@ -462,6 +461,9 @@ following template: </para> <para>The default value is either <quote>trunk</quote> or <quote>trunk/KDE</quote>, depending on the module name.</para> +<tip><para>Use the <link linkend="conf-branch">branch</link> or <link +linkend="conf-tag">tag</link> options instead whenever they are applicable. +</para></tip> </entry> </row> @@ -485,9 +487,9 @@ effect of a stray &svn; update messing up the build system.</entry> <row id="conf-override-url"> <entry>override-url</entry> <entry>Overrides global</entry> -<entry>If you set this option, kdesvn-build will use its value as the URL +<entry>If you set this option, &kdesvn-build; will use its value as the URL to pass to &svn; <emphasis>completely unchanged</emphasis>. You should -generally use this if you want to download a specific release but kdesvn-build +generally use this if you want to download a specific release but &kdesvn-build; can't figure out what you mean using <link linkend="conf-branch">branch</link>. </entry> </row> @@ -522,10 +524,21 @@ installed. <para>Note that using this option can have a significant detrimental impact on both your bandwidth usage (if you use 'all') and the time taken to compile &kde;, -since kdesvn-build will be unable to perform incremental builds.</para> +since &kdesvn-build; will be unable to perform incremental builds.</para> </entry> </row> +<row id="conf-revision"> +<entry>revision</entry> +<entry>Overrides global</entry> +<entry>If this option is set to a value other than 0 (zero), &kdesvn-build; +will force the Subversion update to bring the module to the exact revision +given, even if options like <link linkend="conf-branch">branch</link> are in +effect. If the module is already at the given revision then it will not be +updated further unless this option is changed or removed from the +configuration.</entry> +</row> + <row id="conf-set-env"> <entry>set-env</entry> <entry>Overrides global</entry> @@ -551,13 +564,6 @@ you do specify this value, use an absolute path name. </entry> </row> -<row id="conf-svn-server"> -<entry>svn-server</entry> -<entry>Overrides global</entry> -<entry>This option is used to set the server used to check out from &svn;. -The default is the anonymous &svn; repository, <emphasis>svn://anonsvn.kde.org/</emphasis></entry> -</row> - <row id="conf-stop-on-failure"> <entry>stop-on-failure</entry> <entry>Overrides global</entry> @@ -567,6 +573,13 @@ by default. </entry> </row> +<row id="conf-svn-server"> +<entry>svn-server</entry> +<entry>Overrides global</entry> +<entry>This option is used to set the server used to check out from &svn;. +The default is the anonymous &svn; repository, <emphasis>svn://anonsvn.kde.org/</emphasis></entry> +</row> + <row id="conf-tag"> <entry>tag</entry> <entry>Overrides global</entry> @@ -575,23 +588,27 @@ by default. to use this option. &kde; releases are available in tarball form from <ulink url="ftp://ftp.kde.org/";>The &kde; FTP site</ulink> or one of <ulink url="http://download.kde.org/download.php";>its mirrors</ulink>.</para> -<para>If you are using kdesvn-build because you have having trouble getting +<para>If you are using &kdesvn-build; because you have having trouble getting a &kde; release to build on your distribution, consider using the <ulink url="http://developer.kde.org/build/konstruct/";>Konstruct build tool</ulink> instead, which works from the release tarballs.</para> </entry> </row> +<row id="conf-unsermake-options"> +<entry>unsermake-options</entry> +<entry>Overrides global</entry> +<entry>This option is just like <link linkend="conf-make-options">make-options</link> +but for &unsermake;, which accepts some options that <command>make</command> +cannot understand. +</entry> +</row> + <row id="conf-use-cmake"> <entry>use-cmake</entry> <entry>Overrides global</entry> -<entry> -<para>This option allows you to force &kdesvn-build; to try (or not try) to use -CMake with a given module. Normally &kdesvn-build; will always try to use CMake -if it is present in the module, as this will be required to build KDE 4. This -option is available to ease the transition from unsermake to CMake. This option -will be removed once all KDE 4 modules require CMake. -</para> +<entry>This option was removed in &kdesvn-build; 1.4 as all KDE 4 modules +require CMake, and CMake use is not permitted on any other modules. </entry> </row> @@ -600,7 +617,7 @@ will be removed once all KDE 4 modules require CMake. <entry>Overrides global</entry> <entry>Although this option overrides the global option, it only makes sense for qt-copy. Set this option to <quote>true</quote> to enable the script's -<emphasis>experimental</emphasis> srcdir != builddir mode. When enabled, +srcdir != builddir mode. When enabled, &kdesvn-build; will copy the qt-copy source module to the build directory, and perform builds from there. That means your QTDIR environment variable should be set to @@ -641,16 +658,16 @@ instead of the pre-release &kde; 4.</para> <entry>use-unsermake</entry> <entry>Overrides global</entry> <entry><para>Set this option to <quote>true</quote> in order to use the -experimental unsermake program instead of automake when running the configure +experimental &unsermake; program instead of automake when running the configure script. This can lead to some serious decreases in build time, especially for <ulink url="http://www.csh.rit.edu/slashdot/distcc.html";>distributed building systems</ulink>. This option defaults to <quote>true</quote> (for most modules). </para> -<para>Normally if you use this option kdesvn-build will automatically keep +<para>Normally if you use this option &kdesvn-build; will automatically keep unsermake up-to-date. This may start to get annoying, especially if you are -managing unsermake yourself. If this is the case, you can set this option to -<quote>self</quote>, and kdesvn-build will still use unsermake, but will not +managing &unsermake; yourself. If this is the case, you can set this option to +<quote>self</quote>, and &kdesvn-build; will still use &unsermake;, but will not do anything special to keep it updated. </para> </entry>
