From kde-commits Tue Feb 28 22:05:08 2017 From: Thomas Eschenbacher Date: Tue, 28 Feb 2017 22:05:08 +0000 To: kde-commits Subject: [kwave] /: doc: split off developer sections from handbook into seperate file Message-Id: X-MARC-Message: https://marc.info/?l=kde-commits&m=148831952609389 Git commit d425295c7e127ad5dc09aae299ade55348ddcb58 by Thomas Eschenbacher. Committed on 28/02/2017 at 22:04. Pushed by eschenbacher into branch 'master'. doc: split off developer sections from handbook into seperate file to reduce load of translators. new make target "html_doc_devel" (included in "apidoc") M +3 -0 CHANGES M +4 -2 CMakeLists.txt M +24 -0 doc/CMakeLists.txt A +776 -0 doc/devel.docbook M +7 -703 doc/en/index.docbook M +1 -1 doxy.cfg.in https://commits.kde.org/kwave/d425295c7e127ad5dc09aae299ade55348ddcb58 diff --git a/CHANGES b/CHANGES index a896affd..21aa155b 100644 --- a/CHANGES +++ b/CHANGES @@ -45,6 +45,9 @@ * renamed command "edit_label" -> "label:edit" * implemented loading and saving of labels * allow special value -1 as index for label:delete(...) to delete _all_ = labels + * doc: split off developer sections from handbook into seperate file, to + reduce load of translators. new make target "html_doc_devel" + (included in "apidoc") = 0.9.2 [2016-06-26] = diff --git a/CMakeLists.txt b/CMakeLists.txt index 01c013a6..4f421346 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -421,7 +421,7 @@ FIND_PROGRAM(DOXYGEN_EXECUTABLE doxygen) = IF (DOXYGEN_EXECUTABLE AND RM_EXECUTABLE) SET(DOXYFILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) - SET(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/apidoc) + SET(DOXYGEN_OUTPUT_DIR ${CMAKE_BINARY_DIR}/doc/api) SET(DOXYGEN_LOGFILE ${CMAKE_CURRENT_BINARY_DIR}/doxygen.log) = MESSAGE(STATUS "Found doxygen: ${DOXYGEN_EXECUTABLE}") @@ -433,7 +433,9 @@ IF (DOXYGEN_EXECUTABLE AND RM_EXECUTABLE) ) = ADD_CUSTOM_TARGET(apidoc - COMMAND "${RM_EXECUTABLE}" -R -f "${CMAKE_CURRENT_BINARY_DIR}/html" + DEPENDS html_doc_devel + COMMAND "${RM_EXECUTABLE}" -R -f "${CMAKE_BINARY_DIR}/doc/api" + COMMAND "${CMAKE_COMMAND}" -E make_directory "${CMAKE_BINARY_DIR}/doc/api" COMMAND "${DOXYGEN_EXECUTABLE}" "${DOXYFILE}" COMMAND "${CAT_EXECUTABLE}" "${DOXYGEN_LOGFILE}" DEPENDS ${DOXYFILE} diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 4dd89eab..37a3626e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -163,4 +163,28 @@ FOREACH(_file ${_files}) ENDFOREACH(_file ${_files}) = ##########################################################################= ### +### "make html_doc_devel" = ### + +SET(_common_en_dir ${CMAKE_INSTALL_PREFIX}/${HTML_INSTALL_DIR}/en/kdoctool= s5-common) +SET(_html_dir_devel ${CMAKE_CURRENT_BINARY_DIR}/devel) +GET_TARGET_PROPERTY(MEINPROC_EXECUTABLE ${KDOCTOOLS_MEINPROC_EXECUTABLE} L= OCATION) + +ADD_CUSTOM_TARGET(html_doc_devel + COMMENT "Generating HTML developer documentation" + DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/devel.docbook + # start with an empty output (_html_dir) + COMMAND ${CMAKE_COMMAND} -E remove_directory ${_html_dir_devel} + COMMAND ${CMAKE_COMMAND} -E make_directory ${_html_dir_devel} + # create the HTML pages from docbook + COMMAND cd ${_html_dir_devel} && ${MEINPROC_EXECUTABLE} + --check ${CMAKE_CURRENT_SOURCE_DIR}/devel.docbook + # copy files for the "common" directory + COMMAND ${CMAKE_COMMAND} -E make_directory ${_html_dir_devel}/com= mon + COMMAND ${CP_EXECUTABLE} -n ${_common_en_dir}/* ${_html_dir_devel}/com= mon/ + # fix wrong paths in the HTML pages + COMMAND cd ${_html_dir_devel} && ${CMAKE_SOURCE_DIR}/doc/fix-common + WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} +) + +##########################################################################= ### ##########################################################################= ### diff --git a/doc/devel.docbook b/doc/devel.docbook new file mode 100644 index 00000000..84612841 --- /dev/null +++ b/doc/devel.docbook @@ -0,0 +1,776 @@ + +Kwave"> + + + + + + + + + + + + + + + + + + + +]> + + + + + The &kwave; Developer Handbook + + + + Thomas + Eschenbacher + +
thomas.eschenbacher@gmx.de
+ + + + + + + + 1998-2000Martin Wilz + &version_year;Thomas Eschenbacher + + &FDLNotice; + + 2017-01-29 + 0.9.3 (Applications 16.12) + + &kwave; is a simple sound editor built on &kf5-full;.<= /para> + + + KDE + KF5 + multimedia + sound + audio + Kwave + wav + editor + record + playback + sonagram + FFT + Linux + + + + + + + +Installation + &underFDL; + &underGPL; + + + + + + How to obtain &kwave; + + + &kwave; has an own homepage under + &url_homepage;. Here you can + find further information about the project, as well as + information about current stable and up-to-date development + versions. + + + There also is a KDE project page + at &url_kde_project; which + shows a short summary of the application. + + + + If you want to get a &kwave; release, you have the choice to visit + &url_download; and + + + download a binary package of the latest stable version, if + there is one for your distribution, + + + download a source RPM package of the latest stable version, + + + compile on your own, from a .tar.bz2 archive with the source code + of the latest stable version, + + + compile on your own, from the latest GIT source. + + + + + + Don't be afraid, compiling Kwave should be quite simple even if + you are not a software developer. It just needs some developer + packages to be installed and some time. + + + + + + + + + Requirements + + + In order to successfully use &kwave;, you need: + + + a computer running Linux (&kwave; might also run under + some other operating system, but we have never tested + this, please let us know if you get it working under + some other platform / operating system) + + + working sound playback (not really required for using but + what would you do with a sound editor if you cannot + hear the result of your work?) + + + KDE Frameworks 5.2 (KF5) or higher (at least the libraries, + if you are using a different desktop, you can also run &kwave; + if the proper libraries are installed). + + + Qt-5.4 or higher (normally comes as a dependency of KF5) + + + ALSA 1.0.14 or higher (for record/playback) + + + PulseAudio 4.0 or higher (for record/playback) + + + id3lib-3.8.1 or higher (for ID3 tags) + + + mad-0.15 or higher (optionally for MP3 import/export) + + + flac-1.2.0 or higher (for FLAC import/export) + + + libsamplerate-0.1.3 or higher (sample rate conversion) + + + + + + For a more complete and up-to-date list, please consult the + 'README' file that is included + in the source distribution. + This file also contains some special hints for getting &kwave; running an= d/or + building &kwave; under some distributions. + + + + If you intend to compile &kwave; from the sources, you will need at l= east: + + + cmake-2.8.12 or newer + + + A recent C/C++ compiler. GCC-4.x works fine, some older and any + newer version (like gcc-5.0) should work too. + + + The glibc2 (libc-6) development environment. On SuSE systems + the package is called "libc", on other systems it might be + called "libc-devel". + + + Qt5 and KF5 development packages + + + pulseaudio-0.9.16 or newer + + + id3lib-devel-3.8.1 or newer + + + fftw-3.0 or newer + + + mad-devel-0.15 or newer + (if you have the permission to use MP3 code) + + + flac-devel-1.2.0 newer + + + If you intend to get the &kwave; sources via GIT, you will also + need a current git package. + + + ...many other packages, please take a look at the + 'README' file included in + the source package. + + + + + + + + + + + Manual Compilation and install= ation + + + Since version 0.7.10 &kwave; uses + cmake, a make system + that is also used by KDE itself. So if you know how to build other KDE + applications, you should not have any difficulties in building &kwave;. + If you run into problems please report them to + the &kwave; mailing list. + + + + In order to compile and install &kwave; on your system, it is best + practice to do a out-of-tree build. This means + that you hold the sources of &kwave; in one directory and build the + package in another (temporary) directory. + + + + For example, assuming that your sources are already + unpacked in $HOME/src/kwave-&version;, you + can do the following: + +% mkdir /tmp/kwave-build +% cd /tmp/kwave-build +% cmake $HOME/src/kwave-&version; [build options] +% make +% su root -c "make install" + + (Specifying build options is a way to enable or disable specific features. + See the following section for descriptions) + + + + + + + + + Build options + + + By specifying build options, you can enable or disable some features + of &kwave;, like excluding some components or plugins from the + generated package. Here is a list of the available options: + + + + WITH_ALSA + enable playback/recording via ALSA + [on/off, + default=3Don] + + + WITH_DEBUG + build a debug version + [on/off, + default=3Doff] + + + WITH_DOC + build online documentation + [on/off, + default=3Don] + + + WITH_FLAC + enable support for FLAC files + [on/off, + default=3Don] + + + WITH_MP3 + enable support for mp3 files + [on/off, + default=3Doff] + Please note that you need the permission to use code + covered by the MP3 software patents! + + + WITH_OGG_OPUS + enable support for Ogg/Opus files + [on/off, + default=3Don] + + + WITH_OGG_VORBIS + enable support for Ogg/Vorbis files + [on/off, + default=3Don] + + + WITH_OPTIMIZED_MEMCPY + use an optimized version of memcpy, available for + X86, X86_64 and PPC platforms + [on/off, + default=3Don] + + + WITH_OSS + enable playback/recording via OSS + [on/off, + default=3Don] + + + WITH_PULSEAUDIO + enable playback/recording via PulseAudio + [on/off, + default=3Don] + + + WITH_QT_AUDIO + enable playback via Qt Multimedia + [on/off, + default=3Don] + + + + + + These options can be passed to cmake + with -Doption<= literal>=3Dvalue. + For example, if you want to enable MP3 support, + you can pass the corresponding option as follows: + +% cmake [source directory] -DWITH_MP3=3DON [other options...] + + + + + + + + + + Building RPM packages from tar.bz2 archives + + + With working rpmbuild -ta + + + If you are running a system with RPM support, the preferred way to + install &kwave; on your system will be the creation of a nice RPM + package. First you should get the current source of &kwave;, either + as a tar.bz2 archive from the &kwave; download page or + check out an up-to-date copy via the GIT repository hosted on KDE + servers, or the mirror repository hosted by + SourceForge where + you can get the sources of the latest development version. + + + For instructions on how to get access to the repository, read + in the chapter about + building from git. + + There also is a GIT web interface on KDE= + and on SourceForge where + you can use to browse through the sources. + + + + If you have downloaded tar.bz2 archives of &kwave;, + create and install the RPMs just by doing the following steps + (where [arch] stands for the platform you + have built the package and might be something like + i586, i686, + sparc or whatever, + XXX stands for the version number + you have downloaded). + + + + To build the &kwave; package and install it do: + +% rpmbuild -ta kwave-XXX.tar.bz2 +% rpm -i /usr/src/redhat/RPMS/[arch= ]/kwave-XXX.[arch].rpm + + + + + Note for SuSE users: + you have to specify the directory + /usr/src/packages instead + of /usr/src/redhat ! + + + + If you haven't seen any errors, then that's it and you can skip the + rest of this chapter. If rpm was unable to build the packages + and says something like "spec file not found", then go on and + read the rest of this section. + + + + + + With broken rpmbuild -ta support + + + If you cannot get rpmbuild -ta working, here are + the steps for making that manually (the hard way): + + + + + Go to your RPM "topdir". This normally + is /usr/src/redhat + for the redhat distribution + or /usr/src/packages if you + have the SuSE distribution. + +% cd /usr/src/redhat<= /command> + + + + + Put the tar.bz2 archive into the SOURCES subdirectory (you + have to replace "somewhere" with the real directory where + the files are, of course). + +% cp /somewhere/kwave-XXX.tar.bz2 SOURCES + + + + + Extract the spec file from the archives and put it into + the SPEC subdirectory. + +% tar -xOjf SOURCES/kwave-XXX.tar.b= z2 \*.spec > SPECS/kwave.spec + + + + + Let rpm do the compile job and generate the rpm of &kwave;. + If you only want to make a binary package, you + can specify -bb instead of + -ba, or just -bs to build + only a source package. + +% rpmbuild -ba SPECS/kwave.spec + + + + + If everything was ok, you can install the binary rpm of + &kwave;, it will be in the BUILD directory. + If you already have a version of &kwave; installed, + please remove it first or use the parameter + -U instead + of -i for upgrading instead of installing. + +% rpm -ivh BUILD/[arch]/kwave-XXX.[= arch].rpm + + + + + + + + + + + + + + Building RPM packages from GIT + + Checking out the sources + + + For initially checking out the sources you will need some disk space + (about 25 megabytes) in a directory of your choice, the git package + of your favorite distribution and full access to the Internet. If you + get error messages about rejected connections you either have typed + something wrong or your provider doesn't give you full access. + A good place for the source files will be "$HOME/src". + + + + + First create the directory that will receive the subdirectory with + &kwave; sources and change into it: + +% mkdir -p $HOME/src<= /command> +% cd $HOME/src + + + + + Then check out the latest sources from the GIT server: + +% git clone &url_git_master; kwave + + + + or you can check out a specific release with the following commands: + + % git clone &url_git_master; kwave + % cd kwave + % git checkout tags/[release-ta= g] + + You can look up the names of the release tags in the git web page at + &url_git_list_tags;. + The release tags are always built out of the word Release- and + the version number of the release, with underscores instead of dots. + For example "Release-&version_tag;" for v&version;. + + + + + + There must not be a directory named + kwave under + the directory you want to check out. Otherwise the git program will + complain about already existing files and the checkout will + not work. + + + + + Updating fresh sources from GIT + + The procedure described in the previous section is only necessary + once. For further updates it is much easier. Just change into the + directory where you have the checked out sources and do the following + to update to the latest version: + +% git pull + + Then go on to the next section and compile as usual. + + + If you think that you have messed up your local source tree or if there + are conflicts during updating and you want to start through from a clean + state, you can do the following to discard all local changes and switch + back to the latest version from the master branch: + +% git clean --force -d +% git reset --hard +% git checkout master= + + + + + Compiling + + Building rpm package from a GIT snapshot is quite simple. The procedure + is nearly the same as described in the last section, so it unhappily also + has the same problem with the rpmbuild -ta command + our method internally uses. + Like in the previous chapter, [arch] stands + for the platform you have built the package and might be something + like i386, i586, + sparc or whatever, + XXX stands + for the version number you have checked out. + + + + Note for SuSE users: + here you have to specify the directory + /usr/src/packages instead + of /usr/src/redhat too! + + + + Assuming that + you are in the root of where you checked out from GIT, do the + following to create a Makefile, the &kwave; package and + install it. If you already have a version of &kwave; installed, + please remove it first or use rpm -U instead + of rpm -i for updating instead of installing. + +% mkdir /tmp/kwave-build +% cd /tmp/kwave-build +% cmake $HOME/src/kwave +% make rpm +% rpm -ivh /usr/src/redhat/BUILD/[a= rch]/kwave-XXX.[arch].rpm + + + + + If you still have problems with make rpm, + you will find the tar.bz2 + archive that was produced in /tmp. + Please follow the instructions in the + previous chapter. + + + + + + + + + + + Building a DEB package for testing and personal use + + + If you want to create a deb package of &kwave;, ⪚ for testing a + version that is not yet available via official package repositories, + then you can create your own package quite easily. First of all, you + need to install some required tools: + +% sudo apt-get install build-essential checkinst= all + + + + + Then you can install the required build dependencies by pretending to + install the dependencies of the official &kwave; version: + +% sudo apt-get build-dep kwave + + + + + After installing the required packages, you can build &kwave; as + described in the chapters before. After building you can type this + to get a .deb file in your current build directory: + +% make deb + + + + + The .deb file you get from this step will not have the quality that + a package from your official distribution has - it is just good enough + for installing and safely uninstalling &kwave; for testing purposes + and for personal use. + + + + + + + + + + +Developer's Guide to &kwave; + + + + + + + under construction + + + + Sorry, this chapter is still to be written... At the moment the + source code is nearly completely documented with tags suitable with + the KDE documentation tools. We currently prefer using + doxygen. Maybe some day we will spen= d some time for + writing a tool that converts the doxygen output into something + we can include into the docbook source (the source this page has + been built of). + + + If you want to write a plugin, contribute something to this + project (or maybe write the converter mentioned above), please + feel free to contact one of the authors directly + and / or subscribe to the &kwave; mailing list: + "&url_mailinglist;". + Help is always welcome! + + + + + + + + + API documentation + + + If you are interested in the internal of &kwave; and you have + doxygen installed, then you + can type: + +% make apidoc + + + + to get a directory + doc/api/html, + with documentation of the source and the internal API in your + current build directory. + + + + API documentation can be found here= .... + + + + + + + + + Starting in a test environment</ti= tle> + + <para> + If you are developing or testing &kwave;, then you do not necessarily + need to uninstall/install &kwave; after every build. Instead you can + use the application from where it is built by using a wrapper script. + This wrapper script can be built with the following command: +<screen width=3D"50" format=3D"linespecific"> +<prompt>% </prompt><command>make wrapper</command> +</screen> + </para> + <para> + The script will be named <filename><replaceable>kw</replaceable></filenam= e>, + feel free to modify it to match your system if needed. + </para> + <warning><para> + For this to work, you must <emphasis>not</emphasis> have &kwave; + installed on your system. If so, please uninstall the package + before! + </para></warning> + + </sect1> + +<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++= + --> +<!-- +++ Section: Adding a new plugin ++= + --> +<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++= + --> + +<!-- + <sect1 id=3D"add_new_plugin"><title>Adding a new Plugin + + + to be written... + + + +--> + + + + diff --git a/doc/en/index.docbook b/doc/en/index.docbook index 89218ac7..84f17b1d 100644 --- a/doc/en/index.docbook +++ b/doc/en/index.docbook @@ -7,18 +7,16 @@ + + - - - - @@ -27,13 +25,10 @@ - - - @@ -458,7 +453,8 @@ you can get the sources of the latest development version. For instructions on how to get access to the repository, read in the chapter about - building from GIT. + building from GIT + in the developer documentation. There also is a GIT web interface on KDE and on SourceForge where you can use to browse through the sources. @@ -506,597 +502,6 @@ = - - - -Installation - - - - - - How to obtain &kwave; - - - &kwave; has an own homepage under - &url_homepage;. Here you can - find further information about the project, as well as - information about current stable and up-to-date development - versions. - - - There also is a KDE project page - at &url_kde_project; which - shows a short summary of the application. - - - - If you want to get a &kwave; release, you have the choice to visit - &url_download; and - - - download a binary package of the latest stable version, if - there is one for your distribution, - - - download a source RPM package of the latest stable version, - - - compile on your own, from a .tar.bz2 archive with the source code - of the latest stable version, - - - compile on your own, from the latest GIT source. - - - - - - Don't be afraid, compiling Kwave should be quite simple even if - you are not a software developer. It just needs some developer - packages to be installed and some time. - - - - - - - - - Requirements - - - In order to successfully use &kwave;, you need: - - - a computer running Linux (&kwave; might also run under - some other operating system, but we have never tested - this, please let us know if you get it working under - some other platform / operating system) - - - working sound playback (not really required for using but - what would you do with a sound editor if you cannot - hear the result of your work?) - - - KDE Frameworks 5.2 (KF5) or higher (at least the libraries, - if you are using a different desktop, you can also run &kwave; - if the proper libraries are installed). - - - Qt-5.4 or higher (normally comes as a dependency of KF5) - - - ALSA 1.0.14 or higher (for record/playback) - - - PulseAudio 4.0 or higher (for record/playback) - - - id3lib-3.8.1 or higher (for ID3 tags) - - - mad-0.15 or higher (optionally for MP3 import/export) - - - flac-1.2.0 or higher (for FLAC import/export) - - - libsamplerate-0.1.3 or higher (sample rate conversion) - - - - - - For a more complete and up-to-date list, please consult the - 'README' file that is included - in the source distribution. - This file also contains some special hints for getting &kwave; running an= d/or - building &kwave; under some distributions. - - - - If you intend to compile &kwave; from the sources, you will need at l= east: - - - cmake-2.8.12 or newer - - - A recent C/C++ compiler. GCC-4.x works fine, some older and any - newer version (like gcc-5.0) should work too. - - - The glibc2 (libc-6) development environment. On SuSE systems - the package is called "libc", on other systems it might be - called "libc-devel". - - - Qt5 and KF5 development packages - - - pulseaudio-0.9.16 or newer - - - id3lib-devel-3.8.1 or newer - - - fftw-3.0 or newer - - - mad-devel-0.15 or newer - (if you have the permission to use MP3 code) - - - flac-devel-1.2.0 newer - - - If you intend to get the &kwave; sources via GIT, you will also - need a current git package. - - - ...many other packages, please take a look at the - 'README' file included in - the source package. - - - - - - - - - - - Manual Compilation and install= ation - - - Since version 0.7.10 &kwave; uses - cmake, a make system - that is also used by KDE itself. So if you know how to build other KDE - applications, you should not have any difficulties in building &kwave;. - If you run into problems please report them to - the &kwave; mailing list. - - - - In order to compile and install &kwave; on your system, it is best - practice to do a out-of-tree build. This means - that you hold the sources of &kwave; in one directory and build the - package in another (temporary) directory. - - - - For example, assuming that your sources are already - unpacked in $HOME/src/kwave-&version;, you - can do the following: - -% mkdir /tmp/kwave-build -% cd /tmp/kwave-build -% cmake $HOME/src/kwave-&version; [build options] -% make -% su root -c "make install" - - (Specifying build options is a way to enable or disable specific features. - See the following section for descriptions) - - - - - - - - - Build options - - - By specifying build options, you can enable or disable some features - of &kwave;, like excluding some components or plugins from the - generated package. Here is a list of the available options: - - - - WITH_ALSA - enable playback/recording via ALSA - [on/off, - default=3Don] - - - WITH_DEBUG - build a debug version - [on/off, - default=3Doff] - - - WITH_DOC - build online documentation - [on/off, - default=3Don] - - - WITH_FLAC - enable support for FLAC files - [on/off, - default=3Don] - - - WITH_MP3 - enable support for mp3 files - [on/off, - default=3Doff] - Please note that you need the permission to use code - covered by the MP3 software patents! - - - WITH_OGG_OPUS - enable support for Ogg/Opus files - [on/off, - default=3Don] - - - WITH_OGG_VORBIS - enable support for Ogg/Vorbis files - [on/off, - default=3Don] - - - WITH_OPTIMIZED_MEMCPY - use an optimized version of memcpy, available for - X86, X86_64 and PPC platforms - [on/off, - default=3Don] - - - WITH_OSS - enable playback/recording via OSS - [on/off, - default=3Don] - - - WITH_PULSEAUDIO - enable playback/recording via PulseAudio - [on/off, - default=3Don] - - - WITH_QT_AUDIO - enable playback via Qt Multimedia - [on/off, - default=3Don] - - - - - - These options can be passed to cmake - with -Doption<= literal>=3Dvalue. - For example, if you want to enable MP3 support, - you can pass the corresponding option as follows: - -% cmake [source directory] -DWITH_MP3=3DON [other options...] - - - - - - - - - - Building RPM packages from tar.bz2 archives - - - With working rpmbuild -ta - - - If you are running a system with RPM support, the preferred way to - install &kwave; on your system will be the creation of a nice RPM - package. First you should get the current source of &kwave;, either - as a tar.bz2 archive from the &kwave; download page or - check out an up-to-date copy via - GIT (like described in - the chapter about GIT) and read the - next chapter. - - - - If you have downloaded tar.bz2 archives of &kwave;, - create and install the RPMs just by doing the following steps - (where [arch] stands for the platform you - have built the package and might be something like - i586, i686, - sparc or whatever, - XXX stands for the version number - you have downloaded). - - - - To build the &kwave; package and install it do: - -% rpmbuild -ta kwave-XXX.tar.bz2 -% rpm -i /usr/src/redhat/RPMS/[arch= ]/kwave-XXX.[arch].rpm - - - - - Note for SuSE users: - you have to specify the directory - /usr/src/packages instead - of /usr/src/redhat ! - - - - If you haven't seen any errors, then that's it and you can skip the - rest of this chapter. If rpm was unable to build the packages - and says something like "spec file not found", then go on and - read the rest of this section. - - - - - - With broken rpmbuild -ta support - - - If you cannot get rpmbuild -ta working, here are - the steps for making that manually (the hard way): - - - - - Go to your RPM "topdir". This normally - is /usr/src/redhat - for the redhat distribution - or /usr/src/packages if you - have the SuSE distribution. - -% cd /usr/src/redhat<= /command> - - - - - Put the tar.bz2 archive into the SOURCES subdirectory (you - have to replace "somewhere" with the real directory where - the files are, of course). - -% cp /somewhere/kwave-XXX.tar.bz2 SOURCES - - - - - Extract the spec file from the archives and put it into - the SPEC subdirectory. - -% tar -xOjf SOURCES/kwave-XXX.tar.b= z2 \*.spec > SPECS/kwave.spec - - - - - Let rpm do the compile job and generate the rpm of &kwave;. - If you only want to make a binary package, you - can specify -bb instead of - -ba, or just -bs to build - only a source package. - -% rpmbuild -ba SPECS/kwave.spec - - - - - If everything was ok, you can install the binary rpm of - &kwave;, it will be in the BUILD directory. - If you already have a version of &kwave; installed, - please remove it first or use the parameter - -U instead - of -i for upgrading instead of installing. - -% rpm -ivh BUILD/[arch]/kwave-XXX.[= arch].rpm - - - - - - - - - - - - - - Building RPM packages from GIT - - Checking out the sources - - - For initially checking out the sources you will need some disk space - (about 25 megabytes) in a directory of your choice, the git package - of your favorite distribution and full access to the Internet. If you - get error messages about rejected connections you either have typed - something wrong or your provider doesn't give you full access. - A good place for the source files will be "$HOME/src". - - - - - First create the directory that will receive the subdirectory with - &kwave; sources and change into it: - -% mkdir -p $HOME/src<= /command> -% cd $HOME/src - - - - - Then check out the latest sources from the GIT server: - -% git clone &url_git_master; kwave - - - - or you can check out a specific release with the following commands: - - % git clone &url_git_master; kwave - % cd kwave - % git checkout tags/[release-ta= g] - - You can look up the names of the release tags in the git web page at - &url_git_list_tags;. - The release tags are always built out of the word Release- and - the version number of the release, with underscores instead of dots. - For example "Release-&version_tag;" for v&version;. - - - - - - There must not be a directory named - kwave under - the directory you want to check out. Otherwise the git program will - complain about already existing files and the checkout will - not work. - - - - - Updating fresh sources from GIT - - The procedure described in the previous section is only necessary - once. For further updates it is much easier. Just change into the - directory where you have the checked out sources and do the following - to update to the latest version: - -% git pull - - Then go on to the next section and compile as usual. - - - If you think that you have messed up your local source tree or if there - are conflicts during updating and you want to start through from a clean - state, you can do the following to discard all local changes and switch - back to the latest version from the master branch: - -% git clean --force -d -% git reset --hard -% git checkout master= - - - - - Compiling - - Building rpm package from a GIT snapshot is quite simple. The procedure - is nearly the same as described in the last section, so it unhappily also - has the same problem with the rpmbuild -ta command - our method internally uses. - Like in the previous chapter, [arch] stands - for the platform you have built the package and might be something - like i386, i586, - sparc or whatever, - XXX stands - for the version number you have checked out. - - - - Note for SuSE users: - here you have to specify the directory - /usr/src/packages instead - of /usr/src/redhat too! - - - - Assuming that - you are in the root of where you checked out from GIT, do the - following to create a Makefile, the &kwave; package and - install it. If you already have a version of &kwave; installed, - please remove it first or use rpm -U instead - of rpm -i for updating instead of installing. - -% mkdir /tmp/kwave-build -% cd /tmp/kwave-build -% cmake $HOME/src/kwave -% make rpm -% rpm -ivh /usr/src/redhat/BUILD/[a= rch]/kwave-XXX.[arch].rpm - - - - - If you still have problems with make rpm, - you will find the tar.bz2 - archive that was produced in /tmp. - Please follow the instructions in the - previous chapter. - - - - - - - - - - - Building a DEB package for testing and personal use - - - If you want to create a deb package of &kwave;, ⪚ for testing a - version that is not yet available via official package repositories, - then you can create your own package quite easily. First of all, you - need to install some required tools: - -% sudo apt-get install build-essential checkinst= all - - - - - Then you can install the required build dependencies by pretending to - install the dependencies of the official &kwave; version: - -% sudo apt-get build-dep kwave - - - - - After installing the required packages, you can build &kwave; as - described in the chapters before. After building you can type this - to get a .deb file in your current build directory: - -% make deb - - - - - The .deb file you get from this step will not have the quality that - a package from your official distribution has - it is just good enough - for installing and safely uninstalling &kwave; for testing purposes - and for personal use. - - - - - - - = @@ -5024,7 +4429,7 @@ = - + = Plugins @@ -5930,7 +5335,7 @@ Provides various internal commands useful for debugging and scripting &kwave;. These functions are only available through the main menu if &kwave; has been compiled in debug mode - (see build options). + (built with the option CMAKE_WITH_DEBUG). @@ -7807,106 +7212,6 @@ = - - - -Developer's Guide to &kwave; - - - - - - - under construction - - - - Sorry, this chapter is still to be written... At the moment the - source code is nearly completely documented with tags suitable with - the KDE documentation tools. We currently prefer using - doxygen. Maybe some day we will spen= d some time for - writing a tool that converts the doxygen output into something - we can include into the docbook source (the source this page has - been built of). - - - If you want to write a plugin, contribute something to this - project (or maybe write the converter mentioned above), please - feel free to contact one of the authors directly - and / or subscribe to - the &kwave; mailing list. - Help is always welcome! - - - - - - - - - Creating API documentation - - - If you are interested in the internal of &kwave; and you have - doxygen installed, then you - can type: - -% make apidoc - - - - to get a directory - apicod/html, - with documentation of the source and the internal API in your - current build directory. - - - - - - - - - Starting in a test environment</ti= tle> - - <para> - If you are developing or testing &kwave;, then you do not necessarily - need to uninstall/install &kwave; after every build. Instead you can - use the application from where it is built by using a wrapper script. - This wrapper script can be built with the following command: -<screen width=3D"50" format=3D"linespecific"> -<prompt>% </prompt><command>make wrapper</command> -</screen> - </para> - <para> - The script will be named <filename><replaceable>kw</replaceable></filenam= e>, - feel free to modify it to match your system if needed. - </para> - <warning><para> - For this to work, you must <emphasis>not</emphasis> have &kwave; - installed on your system. If so, please uninstall the package - before! - </para></warning> - - </sect1> - -<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++= + --> -<!-- +++ Section: Adding a new plugin ++= + --> -<!-- +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++= + --> - -<!-- - <sect1 id=3D"add_new_plugin"><title>Adding a new Plugin - - - to be written... - - - ---> - - - - = @@ -7925,8 +7230,7 @@ Read in the - chapter - mentioned before. + developer documentation. diff --git a/doxy.cfg.in b/doxy.cfg.in index 8efcb454..b0037e86 100644 --- a/doxy.cfg.in +++ b/doxy.cfg.in @@ -2165,7 +2165,7 @@ DOT_NUM_THREADS =3D 0 # The default value is: Helvetica. # This tag requires that the tag HAVE_DOT is set to YES. = -DOT_FONTNAME =3D FreeSans +DOT_FONTNAME =3D = # The DOT_FONTSIZE tag can be used to set the size (in points) of the font= of # dot graphs.