Warning, /multimedia/kwave/doc/devel.docbook is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" ?>
0002 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
0003   <!ENTITY kwave "<application>Kwave</application>">
0004   <!ENTITY % English "INCLUDE"> <!-- change language only here -->
0005   <!ENTITY % addindex "IGNORE">
0006   <!ENTITY version "20.07.70">
0007   <!ENTITY version_year "2020">
0008   <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Application-Variable Entities V2.0//EN" "entities/kde-prologue.entities">
0009   <!ENTITY url_git_web_kde "https://invent.kde.org/multimedia/kwave/">
0010   <!ENTITY url_prefix_gitweb "&url_git_web_kde;-/blob/master/">
0011   <!ENTITY url_cmake "http://www.cmake.org">
0012   <!ENTITY url_download "http://kwave.sourceforge.net/download.html">
0013   <!ENTITY url_doxygen "http://www.stack.nl/~dimitri/doxygen">
0014   <!ENTITY url_homepage "http://kwave.sourceforge.net/">
0015   <!ENTITY url_kde_project "http://www.kde.org/applications/multimedia/kwave/">
0016   <!ENTITY url_readme "&url_prefix_gitweb;README">
0017   <!ENTITY url_sourceforge "http://sourceforge.net">
0018   <!ENTITY url_git_web_sf "http://sourceforge.net/p/kwave/code/commit_browser">
0019   <!ENTITY url_git_list_tags "&url_git_web_kde;-/tags/">
0020   <!ENTITY url_git_master "https://invent.kde.org/multimedia/kwave.git">
0021 ]>
0022 
0023 <book lang="&language;">
0024 
0025 <bookinfo>
0026     <title>The &kwave; Developer Handbook</title>
0027 
0028     <authorgroup>
0029         <author>
0030             <firstname>Thomas</firstname>
0031             <surname>Eschenbacher</surname>
0032             <affiliation>
0033             <address><email>thomas.eschenbacher@gmx.de</email></address>
0034             </affiliation>
0035         </author>
0036 
0037         <!-- TRANS:ROLES_OF_TRANSLATORS -->
0038 
0039     </authorgroup>
0040 
0041     <copyright><year>1998-2000</year><holder>Martin Wilz</holder></copyright>
0042     <copyright><year>&version_year;</year><holder>Thomas Eschenbacher</holder></copyright>
0043 
0044     <legalnotice>&FDLNotice;</legalnotice>
0045 
0046     <date>2020-07-06</date>
0047     <releaseinfo>&version;</releaseinfo>
0048 
0049     <abstract><para>&kwave; is a simple sound editor built on &kf5-full;.</para></abstract>
0050 
0051     <keywordset>
0052         <keyword>KDE</keyword>
0053         <keyword>KF5</keyword>
0054         <keyword>multimedia</keyword>
0055         <keyword>sound</keyword>
0056         <keyword>audio</keyword>
0057         <keyword>Kwave</keyword>
0058         <keyword>wav</keyword>
0059         <keyword>editor</keyword>
0060         <keyword>record</keyword>
0061         <keyword>playback</keyword>
0062         <keyword>sonagram</keyword>
0063         <keyword>FFT</keyword>
0064         <keyword>Linux</keyword>
0065     </keywordset>
0066 </bookinfo>
0067 
0068 <!-- ###################################################################### -->
0069 <!-- ### Chapter: Installation                                          ### -->
0070 <!-- ###################################################################### -->
0071 
0072 <chapter id="installation"><title>Installation</title>
0073     &underFDL;
0074     &underGPL;
0075 
0076 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0077 <!-- +++ Section: Getting Kwave                                         +++ -->
0078 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0079 
0080     <sect1 id="getting"><title>How to obtain &kwave;</title>
0081 
0082     <para>
0083         &kwave; has an own homepage under
0084         <ulink url="&url_homepage;">&url_homepage;</ulink>. Here you can
0085         find further information about the project, as well as
0086         information about current stable and up-to-date development
0087         versions.
0088     </para>
0089     <para>
0090         There also is a KDE project page
0091         at <ulink url="&url_kde_project;">&url_kde_project;</ulink> which
0092         shows a short summary of the application.
0093     </para>
0094 
0095     <para>
0096         If you want to get a &kwave; release, you have the choice to visit
0097         <ulink url="&url_download;">&url_download;</ulink> and
0098         <itemizedlist>
0099         <listitem><para>
0100             download a binary package of the latest stable version, if
0101             there is one for your distribution,
0102         </para></listitem>
0103         <listitem><para>
0104             download a source RPM package of the latest stable version,
0105         </para></listitem>
0106         <listitem><para>
0107             compile on your own, from a .tar.bz2 archive with the source code
0108             of the latest stable version,
0109         </para></listitem>
0110         <listitem><para>
0111             compile on your own, from the latest GIT source.
0112         </para></listitem>
0113         </itemizedlist>
0114     </para>
0115 
0116     <para>
0117         Don't be afraid, compiling Kwave should be quite simple even if
0118         you are not a software developer. It just needs some developer
0119         packages to be installed and some time.
0120     </para>
0121 
0122     </sect1>
0123 
0124 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0125 <!-- +++ Section: Requirements                                          +++ -->
0126 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0127 
0128     <sect1 id="requirements"><title>Requirements</title>
0129 
0130     <para>
0131         In order to successfully use &kwave;, you need:
0132         <itemizedlist>
0133             <listitem><para>
0134                 a computer running Linux (&kwave; might also run under
0135                 some other operating system, but we have never tested
0136                 this, please let us know if you get it working under
0137                 some other platform / operating system)
0138             </para></listitem>
0139             <listitem><para>
0140                 working sound playback (not really required for using but
0141                 what would you do with a sound editor if you cannot
0142                 <emphasis>hear</emphasis> the result of your work?)
0143             </para></listitem>
0144             <listitem><para>
0145                 KDE Frameworks 5.33 (KF5) or higher (at least the libraries,
0146                 if you are using a different desktop, you can also run &kwave;
0147                 if the proper libraries are installed).
0148             </para></listitem>
0149             <listitem><para>
0150                 Qt-5.14 or higher (normally comes as a dependency of KF5)
0151             </para></listitem>
0152             <listitem><para>
0153                 ALSA 1.0.14 or higher (for record/playback)
0154             </para></listitem>
0155             <listitem><para>
0156                 PulseAudio 4.0 or higher (for record/playback)
0157             </para></listitem>
0158             <listitem><para>
0159                 id3lib-3.8.1 or higher (for ID3 tags)
0160             </para></listitem>
0161             <listitem><para>
0162                 mad-0.15 or higher (optionally for MP3 import/export)
0163             </para></listitem>
0164             <listitem><para>
0165                 flac-1.2.0 or higher (for FLAC import/export)
0166             </para></listitem>
0167             <listitem><para>
0168                 libsamplerate-0.1.3 or higher (sample rate conversion)
0169             </para></listitem>
0170         </itemizedlist>
0171     </para>
0172 
0173     <para>
0174         For a more complete and up-to-date list, please consult the
0175         <ulink url="&url_readme;">'README'</ulink> file that is included
0176         in the source distribution.
0177         This file also contains some special hints for getting &kwave; running and/or
0178         building &kwave; under some distributions.
0179     </para>
0180 
0181     <para>
0182         If you intend to compile &kwave; from the sources, you will need at least:
0183         <itemizedlist>
0184             <listitem><para>
0185                 <ulink url="&url_cmake;">cmake</ulink>-3.16.0 or newer
0186             </para></listitem>
0187             <listitem><para>
0188                 A recent C/C++ compiler. GCC-4.x works fine, some older and any
0189                 newer version (like gcc-5.0) should work too.
0190             </para></listitem>
0191             <listitem><para>
0192                 The glibc2 (libc-6) development environment. On SuSE systems
0193                 the package is called "libc", on other systems it might be
0194                 called "libc-devel".
0195             </para></listitem>
0196             <listitem><para>
0197                 Qt5 and KF5 development packages
0198             </para></listitem>
0199             <listitem><para>
0200                 pulseaudio-0.9.16 or newer
0201             </para></listitem>
0202             <listitem><para>
0203                 id3lib-devel-3.8.1 or newer
0204             </para></listitem>
0205             <listitem><para>
0206                 fftw-3.0 or newer
0207             </para></listitem>
0208             <listitem><para>
0209                 mad-devel-0.15 or newer
0210                 (if you have the permission to use MP3 code)
0211             </para></listitem>
0212             <listitem><para>
0213                 flac-devel-1.2.0 newer
0214             </para></listitem>
0215             <listitem><para>
0216                 If you intend to get the &kwave; sources via GIT, you will also
0217                 need a current git package.
0218             </para></listitem>
0219             <listitem><para>
0220                 ...many other packages, please take a look at the
0221                 <ulink url="&url_readme;">'README'</ulink> file included in
0222                 the source package.
0223             </para></listitem>
0224         </itemizedlist>
0225     </para>
0226 
0227     </sect1>
0228 
0229     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0230     <!-- +++ Section: Fetching sources from GIT                             +++ -->
0231     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0232 
0233     <sect1 id="fetching_sources_from_git">
0234         <title>Fetching sources from GIT</title>
0235 
0236         <sect2 id="git_checkout"><title>Checking out the sources</title>
0237 
0238             <para>
0239                 For initially checking out the sources you will need some disk space
0240                 (about 25 megabytes) in a directory of your choice, the git package
0241                 of your favorite distribution and full access to the Internet. If you
0242                 get error messages about rejected connections you either have typed
0243                 something wrong or your provider doesn't give you full access.
0244                 A good place for the source files will be <filename>"$HOME/src"</filename>.
0245             </para>
0246 
0247             <orderedlist>
0248                 <listitem><para>
0249                         First create the directory that will receive the subdirectory with
0250                         &kwave; sources and change into it:
0251 <screen width="40" format="linespecific">
0252     <prompt>% </prompt><command>mkdir -p <replaceable>$HOME/src</replaceable></command>
0253     <prompt>% </prompt><command>cd <replaceable>$HOME/src</replaceable></command>
0254 </screen>
0255                         </para></listitem>
0256                 <listitem>
0257                     <para>
0258                         Then check out the latest sources from the GIT server:
0259 <screen width="70" format="linespecific">
0260     <prompt>% </prompt><command>git clone &url_git_master; kwave</command>
0261 </screen>
0262                     </para>
0263                     <para>
0264                         or you can check out a specific release with the following commands:
0265 <screen width="70" format="linespecific">
0266     <prompt>% </prompt><command>git clone &url_git_master; kwave</command>
0267     <prompt>% </prompt><command>cd kwave</command>
0268     <prompt>% </prompt><command>git checkout tags/<replaceable>[release-tag]</replaceable> </command>
0269 </screen>
0270                         You can look up the names of the release tags in the git web page at
0271                         <ulink url="&url_git_list_tags;"> &url_git_list_tags;</ulink>.
0272                         Older release tags (until <literal>v0.9.2</literal>) are built out
0273                         of the word <literal>Release-</literal> and the version
0274                         number of the release, with underscores instead of dots.
0275                         Newer release tags consist only of a version number
0276                         (starting with <literal>v16.11.80</literal>).
0277                         For example "<literal>v&version;</literal>" for v&version;.
0278                     </para>
0279                 </listitem>
0280             </orderedlist>
0281 
0282             <warning><para>
0283                     There <emphasis>must not</emphasis> be a directory named
0284                     <filename>kwave</filename> under
0285                     the directory you want to check out. Otherwise the git program will
0286                     complain about already existing files and the checkout will
0287                     not work.
0288                     </para></warning>
0289 
0290         </sect2>
0291 
0292         <sect2 id="git_update"><title>Updating fresh sources from GIT</title>
0293             <para>
0294                 The procedure described in the previous section is only necessary
0295                 once. For further updates it is much easier. Just change into the
0296                 directory where you have the checked out sources and do the following
0297                 to update to the latest version:
0298 <screen width="40" format="linespecific">
0299     <prompt>% </prompt><command>git pull</command>
0300 </screen>
0301             </para>
0302             <note><para>
0303                     If you think that you have messed up your local source tree or if there
0304                     are conflicts during updating and you want to start through from a clean
0305                     state, you can do the following to discard all local changes and switch
0306                     back to the latest version from the master branch:
0307 <screen width="40" format="linespecific">
0308     <prompt>% </prompt><command>git clean --force -d</command>
0309     <prompt>% </prompt><command>git reset --hard</command>
0310     <prompt>% </prompt><command>git checkout <replaceable>master</replaceable></command>
0311 </screen>
0312                     </para></note>
0313         </sect2>
0314     </sect1>
0315 
0316 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0317 <!-- +++ Section: Invokation of cmake                                   +++ -->
0318 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0319 
0320     <sect1 id="cmake_invocation"><title>Invocation of <literal>cmake</literal></title>
0321 
0322     <para>
0323         Since version 0.7.10 &kwave; uses
0324         <ulink url="&url_cmake;">cmake</ulink>, a make system
0325         that is also used by KDE itself. So if you know how to build other KDE
0326         applications, you should not have any difficulties in building &kwave;.
0327     </para>
0328 
0329     <para>
0330         In order to compile and install &kwave; on your system, it is best
0331         practice to do a <emphasis>out-of-tree</emphasis> build. This means
0332         that you hold the sources of &kwave; in one directory and build the
0333         package in another (temporary) directory.
0334     </para>
0335 
0336     <para>
0337         For example, assuming that your sources are already
0338         unpacked in <filename><replaceable>$HOME/src/kwave</replaceable></filename>, you
0339         can do the following:
0340 <screen width="50" format="linespecific">
0341 <prompt>% </prompt><command>mkdir /tmp/kwave-build</command>
0342 <prompt>% </prompt><command>cd /tmp/kwave-build</command>
0343 <prompt>% </prompt><command>cmake <replaceable>$HOME/src/kwave</replaceable> <replaceable>[build options]</replaceable></command>
0344 </screen>
0345         Specifying build options is a way to enable or disable specific features.
0346         Please see the following section for a list of options!
0347     </para>
0348 
0349 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0350 <!-- +++ Section: Build options                                         +++ -->
0351 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0352 
0353     <sect2 id="build_options"><title>Build options</title>
0354 
0355         <para>
0356             By specifying build options, you can enable or disable some features
0357             of &kwave;, like excluding some components or plugins from the
0358             generated package. Here is a list of the available options:
0359 
0360             <itemizedlist>
0361                 <listitem><para>
0362                     <literal>CMAKE_INSTALL_PREFIX</literal>
0363                     installation prefix of your KF5 installation
0364                     [<literal>on</literal>/<literal>off</literal>,
0365                     default=<literal>/usr/local</literal>]
0366                     </para><para>
0367                     You can find out the correct value with the following command:
0368 <screen width="20" format="linespecific">
0369     <prompt>% </prompt><command>kf5-config --prefix</command>
0370 </screen>
0371                     </para></listitem>
0372                 <listitem><para>
0373                     <literal>WITH_ALSA</literal>
0374                     enable playback/recording via ALSA
0375                     [<literal>on</literal>/<literal>off</literal>,
0376                     default=<literal>on</literal>]
0377                 </para></listitem>
0378                 <listitem id="CMAKE_WITH_DEBUG"><para>
0379                     <literal>WITH_DEBUG</literal>
0380                     build a debug version
0381                     [<literal>on</literal>/<literal>off</literal>,
0382                     default=<literal>off</literal>]
0383                 </para></listitem>
0384                 <listitem><para>
0385                     <literal>WITH_DOC</literal>
0386                     build online documentation
0387                     [<literal>on</literal>/<literal>off</literal>,
0388                     default=<literal>on</literal>]
0389                 </para></listitem>
0390                 <listitem><para>
0391                     <literal>WITH_FLAC</literal>
0392                     enable support for FLAC files
0393                     [<literal>on</literal>/<literal>off</literal>,
0394                     default=<literal>on</literal>]
0395                 </para></listitem>
0396                 <listitem><para>
0397                     <literal>WITH_MP3</literal>
0398                     enable support for mp3 files
0399                     [<literal>on</literal>/<literal>off</literal>,
0400                     default=<literal>on</literal>]
0401                 </para></listitem>
0402                 <listitem><para>
0403                     <literal>WITH_OGG_OPUS</literal>
0404                     enable support for Ogg/Opus files
0405                     [<literal>on</literal>/<literal>off</literal>,
0406                     default=<literal>on</literal>]
0407                 </para></listitem>
0408                 <listitem><para>
0409                     <literal>WITH_OGG_VORBIS</literal>
0410                     enable support for Ogg/Vorbis files
0411                     [<literal>on</literal>/<literal>off</literal>,
0412                     default=<literal>on</literal>]
0413                 </para></listitem>
0414                 <listitem><para>
0415                     <literal>WITH_OPTIMIZED_MEMCPY</literal>
0416                     use an optimized version of memcpy, available for
0417                     X86, X86_64 and PPC platforms
0418                     [<literal>on</literal>/<literal>off</literal>,
0419                     default=<literal>on</literal>]
0420                 </para></listitem>
0421                 <listitem><para>
0422                     <literal>WITH_OSS</literal>
0423                     enable playback/recording via OSS
0424                     [<literal>on</literal>/<literal>off</literal>,
0425                     default=<literal>on</literal>]
0426                 </para></listitem>
0427                 <listitem><para>
0428                     <literal>WITH_PULSEAUDIO</literal>
0429                     enable playback/recording via PulseAudio
0430                     [<literal>on</literal>/<literal>off</literal>,
0431                     default=<literal>on</literal>]
0432                 </para></listitem>
0433                 <listitem><para>
0434                     <literal>WITH_QT_AUDIO</literal>
0435                     enable playback via Qt Multimedia
0436                     [<literal>on</literal>/<literal>off</literal>,
0437                     default=<literal>on</literal>]
0438                 </para></listitem>
0439     </itemizedlist>
0440         </para>
0441 
0442         <para>
0443             These options can be passed to <literal><command>cmake</command></literal>
0444             with <command><literal>-D</literal><replaceable>option</replaceable><literal>=</literal><replaceable>value</replaceable></command>.
0445             For example, if you want to disable MP3 support,
0446             you can pass the corresponding option as follows:
0447 <screen width="70" format="linespecific">
0448     <prompt>% </prompt><command>cmake <replaceable>[source directory]</replaceable> -DCMAKE_INSTALL_PREFIX=`kf5-config --prefix` -DWITH_MP3=OFF <replaceable>[other options...]</replaceable></command>
0449 </screen>
0450         </para>
0451     </sect2>
0452 </sect1>
0453 
0454 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0455 <!-- +++ Section: Building RPM packages from Sources                    +++ -->
0456 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0457 
0458     <sect1 id="building_rpm_from_tarbz2">
0459     <title>Building RPM packages from Sources</title>
0460 
0461     <para>
0462         If you are running a system with RPM support, the preferred way to
0463         get &kwave; on your system will be the creation and installation
0464         of a RPM package, as described in the next chapters.
0465         If you are running a Debian like system (dpkg based),
0466         you should skip to [<link linkend="building_deb_from_src">here</link>].
0467     </para>
0468 
0469     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0470     <!-- +++ Section: Finding the RPM settings of your system           +++ -->
0471     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0472 
0473     <sect2 id="find_rpm_settings">
0474     <title>Finding the RPM settings of your system</title>
0475 
0476     <para>
0477         You can find out the RPM top directory with the following command:
0478 <screen width="70" format="linespecific">
0479 <prompt>% </prompt><command>rpm --eval '%_topdir'</command>
0480 </screen>
0481     </para>
0482     <para>
0483         With this command you can find out your native system architecture:
0484 <screen width="70" format="linespecific">
0485 <prompt>% </prompt><command>rpm --eval '%_arch'</command>
0486 </screen>
0487     </para>
0488 
0489     </sect2>
0490 
0491     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0492     <!-- +++ Section: Building a RPM package from a source tree         +++ -->
0493     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0494 
0495     <sect2 id="building_rpm_from_source_tree">
0496         <title>Building a RPM package from a source tree</title>
0497 
0498         <para>
0499         Assuming you have checked out git sources of &kwave;, and you
0500         have successfully passed the cmake stage, you have two
0501         possibilities to get a binary RPM package:
0502         <orderedlist>
0503             <listitem><para>
0504                 Create a tarball with the command "<literal>make tarball</literal>"
0505                 and then continue in the <link linkend="building_with_rpm_ta">next section</link>.
0506             </para></listitem>
0507             <listitem><para>
0508                 Directly create a RPM package with the command
0509                 "<literal>make rpm</literal>" (which is the quicker way)
0510                 and then advance to the section
0511                 about <link linkend="rpm_install">installation of the RPM package</link>.
0512             </para></listitem>
0513         </orderedlist>
0514         </para>
0515     </sect2>
0516 
0517     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0518     <!-- +++ Section: Building a RPM package with working rpmbuild -ta  +++ -->
0519     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0520 
0521     <sect2 id="building_with_rpm_ta">
0522     <title>Building a RPM package with working <literal>rpmbuild -ta</literal></title>
0523 
0524     <para>
0525         Assuming you have a tar.bz2 archive of &kwave;, you can create
0526         a RPM package just by doing the steps in this section
0527         (where <replaceable>[arch]</replaceable> stands for the platform you
0528         have built the package and might be something like
0529         <literal>x86_64</literal>, <literal>i686</literal>,
0530         <literal>sparc</literal> or whatever,
0531         <replaceable>[topdir]</replaceable> stands for the RPM top directory,
0532         and
0533         <replaceable>[version]</replaceable> stands for the version number).
0534     </para>
0535 
0536     <para>
0537     You can build the &kwave; package with this command:
0538 <screen width="70" format="linespecific">
0539 <prompt>% </prompt><command>rpmbuild -ta kwave-<replaceable>[version]</replaceable>.tar.bz2</command>
0540 </screen>
0541     </para>
0542 
0543     <para>
0544         If you haven't seen any errors, then that's it - you can skip the
0545         next section and
0546         <link linkend="rpm_install">install the package</link>.
0547         If rpm was unable to build the packages
0548         and says something like "spec file not found", then please continue
0549         with the next section.
0550     </para>
0551 
0552     </sect2>
0553 
0554     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0555     <!-- +++ Section: Building a RPM package with broken rpmbuild -ta   +++ -->
0556     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0557 
0558     <sect2 id="rpm_build_with_broken_rpm">
0559     <title>Building a RPM package with broken <literal>rpmbuild -ta support</literal></title>
0560 
0561     <para><anchor id="manual_rpm_creation"/>
0562         If you cannot get <command>rpmbuild -ta</command> working, here are
0563         the steps for making that manually (the hard way):
0564     </para>
0565 
0566     <orderedlist>
0567         <listitem><para>
0568             Go to your RPM "topdir".
0569 <screen width="70" format="linespecific">
0570 <prompt>% </prompt><command>cd <replaceable>[topdir]</replaceable></command>
0571 </screen>
0572         </para></listitem>
0573 
0574         <listitem><para>
0575             Put the tar.bz2 archive into the <literal>SOURCES</literal> subdirectory (you
0576             have to replace "somewhere" with the real directory where
0577             the files are, of course).
0578 <screen width="70" format="linespecific">
0579 <prompt>% </prompt><command>cp <replaceable>/somewhere/kwave-[version].tar.bz2</replaceable> SOURCES</command>
0580 </screen>
0581         </para></listitem>
0582 
0583         <listitem><para>
0584             Extract the spec file from the archives and put it into
0585             the <literal>SPEC</literal> subdirectory.
0586 <screen width="70" format="linespecific">
0587 <prompt>% </prompt><command>tar --wildcards -xOjf SOURCES/kwave-<replaceable
0588         >[version]</replaceable>.tar.bz2 \*.spec > SPECS/kwave.spec</command>
0589 </screen>
0590         </para></listitem>
0591 
0592         <listitem><para>
0593             Let rpm do the compile job and generate the rpm of &kwave;.
0594             If you only want to make a binary package, you
0595             can specify <literal>-bb</literal> instead of
0596             <literal>-ba</literal>, or just <literal>-bs</literal> to build
0597             only a source package.
0598 <screen width="70" format="linespecific">
0599 <prompt>% </prompt><command>rpmbuild -ba SPECS/kwave.spec</command>
0600 </screen>
0601         </para></listitem>
0602     </orderedlist>
0603 
0604     </sect2>
0605 
0606     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0607     <!-- +++ Section: Installing the RPM package                        +++ -->
0608     <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0609 
0610     <sect2 id="rpm_install">
0611         <title>Installing the RPM package</title>
0612 
0613         <para>
0614             If everything was ok, you can install the binary rpm of
0615             &kwave;, it should be available below the
0616             <literal>RPMS</literal> sub directory of the RPM top directory.
0617             If you already have a version of &kwave; installed,
0618             please remove it first or use the parameter
0619             <literal>-U</literal> instead
0620             of <literal>-i</literal> for upgrading instead of installing.
0621 <screen width="70" format="linespecific">
0622 <prompt>% </prompt><command>rpm -ivh <replaceable>[topdir]</replaceable>/RPMS/<replaceable
0623         >[arch]</replaceable>/kwave-<replaceable>[version]</replaceable
0624     >.<replaceable>[arch]</replaceable>.rpm</command>
0625 </screen>
0626         </para>
0627     </sect2>
0628 
0629 </sect1>
0630 
0631 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0632 <!-- +++ Section: Building DEB package from Source                      +++ -->
0633 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0634 
0635     <sect1 id="building_deb_from_src">
0636     <title>Building a DEB package (for testing and personal use)</title>
0637 
0638     <para>
0639         If you want to create a deb package of &kwave;, &eg; for testing a
0640         version that is not yet available via official package repositories,
0641         then you can create your own package quite easily. First of all, you
0642         need to install some required tools:
0643 <screen width="70" format="linespecific">
0644 <prompt>% </prompt><command>sudo apt-get install build-essential checkinstall</command>
0645 </screen>
0646     </para>
0647 
0648     <para>
0649         Then you can install the required build dependencies by pretending to
0650         install the dependencies of the official &kwave; version:
0651 <screen width="70" format="linespecific">
0652 <prompt>% </prompt><command>sudo apt-get build-dep kwave</command>
0653 </screen>
0654     </para>
0655 
0656     <para>
0657         After installing the required packages, you should prepare the &kwave;
0658         build as described in the chapter about
0659         <link linkend="cmake_invocation">invocation of cmake</link>.
0660         Then you should be able to produce a .deb file in your current
0661         build directory with this command:
0662 <screen width="70" format="linespecific">
0663 <prompt>% </prompt><command>make deb</command>
0664 </screen>
0665     </para>
0666 
0667     <note><para>
0668         The .deb file you get from this step will not have the quality that
0669         a package from your official distribution has - it is just good enough
0670         for installing and safely uninstalling &kwave; for testing purposes
0671         and for personal use.
0672     </para></note>
0673 
0674     </sect1>
0675 
0676 </chapter>
0677 
0678 <!-- ###################################################################### -->
0679 <!-- ### Chapter: Developer's Guide to Kwave                            ### -->
0680 <!-- ###################################################################### -->
0681 
0682 <chapter id="developers"><title>Developer's Guide to &kwave;</title>
0683 
0684     <para>
0685         <inlinemediaobject>
0686         <imageobject>
0687             <imagedata fileref="under-construction.png" format="PNG"/>
0688         </imageobject>
0689         <textobject> <phrase>under construction</phrase> </textobject>
0690         </inlinemediaobject>
0691      </para>
0692     <para>
0693         Sorry, this chapter is still to be written... At the moment the
0694         source code is nearly completely documented with tags suitable with
0695         the KDE documentation tools. We currently prefer using
0696         <ulink url="&url_doxygen;">doxygen</ulink>. Maybe some day we will spend some time for
0697         writing a tool that converts the doxygen output into something
0698         we can include into the docbook source (the source this page has
0699         been built of).
0700     </para>
0701     <para>
0702         If you want to write a plugin, contribute something to this
0703         project (or maybe write the converter mentioned above), please
0704         feel free to contact one of the authors directly.
0705         Help is always welcome!
0706     </para>
0707 
0708     <!-- @@@ most of this has still to be done ... @@@ -->
0709 
0710 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0711 <!-- +++ Section: API documentation                                     +++ -->
0712 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0713 
0714     <sect1 id="make_apidoc"><title>API documentation</title>
0715 
0716     <para>
0717         If you are interested in the internal of &kwave; and you have
0718         <ulink url="&url_doxygen;">doxygen</ulink> installed, then you
0719         can type:
0720 <screen width="50" format="linespecific">
0721 <prompt>% </prompt><command>make apidoc</command>
0722 </screen>
0723     </para>
0724     <para>
0725         to get a directory
0726         <filename><replaceable>doc/api/html</replaceable></filename>,
0727         with documentation of the source and the internal API in your
0728         current build directory.
0729     </para>
0730     <tip>
0731         <para>
0732         API documentation can be found <ulink url="../api/html/index.html">here...</ulink>.
0733         </para>
0734     </tip>
0735     </sect1>
0736 
0737 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0738 <!-- +++ Section: Starting in a test environment                        +++ -->
0739 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0740 
0741     <sect1 id="create_wrapper"><title>Starting in a test environment</title>
0742 
0743     <para>
0744         If you are developing or testing  &kwave;, then you do not necessarily
0745         need to uninstall/install &kwave; after every build. Instead you can
0746         use the application from where it is built by using a wrapper script.
0747         This wrapper script can be built with the following command:
0748 <screen width="50" format="linespecific">
0749 <prompt>% </prompt><command>make wrapper</command>
0750 </screen>
0751     </para>
0752     <para>
0753         The script will be named <filename><replaceable>kw</replaceable></filename>,
0754         feel free to modify it to match your system if needed.
0755     </para>
0756     <warning><para>
0757         For this to work, you must <emphasis>not</emphasis> have &kwave;
0758         installed on your system. If so, please uninstall the package
0759         before!
0760     </para></warning>
0761 
0762     </sect1>
0763 
0764 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0765 <!-- +++ Section: Adding a new plugin                                   +++ -->
0766 <!-- ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
0767 
0768 <!--
0769     <sect1 id="add_new_plugin"><title>Adding a new Plugin</title>
0770 
0771     <para>
0772         to be written...
0773     </para>
0774 
0775     </sect1>
0776 -->
0777 
0778 </chapter>
0779 
0780 </book>