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;=
replaceable> [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=
replaceable> 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
+
+
+ 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:
+
+% make wrapper
+
+
+
+ The script will be named kw,
+ feel free to modify it to match your system if needed.
+
+
+ For this to work, you must not have &kwave;
+ installed on your system. If so, please uninstall the package
+ before!
+
+
+
+
+
+
+
+
+
+
+
+
+
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;=
replaceable> [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=
replaceable> 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
-
-
- 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:
-
-% make wrapper
-
-
-
- The script will be named kw,
- feel free to modify it to match your system if needed.
-
-
- For this to work, you must not have &kwave;
- installed on your system. If so, please uninstall the package
- before!
-
-
-
-
-
-
-
-
-
-
-
-
-
=
@@ -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.