# The &kwave; Developer Handbook

## 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.33 (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.14 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 and/or building &kwave; under some distributions.

If you intend to compile &kwave; from the sources, you will need at least:

- cmake-3.16.0 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.

### Fetching sources 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"`.

1. First create the directory that will receive the subdirectory with &kwave; sources and change into it:

           % mkdir -p $HOME/src
           % cd $HOME/src

2. 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-tag]

   You can look up the names of the release tags in the git web page at &url_git_list_tags;. Older release tags (until `v0.9.2`) are built out of the word `Release-` and the version number of the release, with underscores instead of dots. Newer release tags consist only of a version number (starting with `v16.11.80`). For example "`v&version;`" 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

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

### Invocation of `cmake`

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;.

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``, you can do the following:

    % mkdir /tmp/kwave-build
    % cd /tmp/kwave-build
    % cmake $HOME/src/kwave [build options]

Specifying build options is a way to enable or disable specific features. Please see the following section for a list of options!

#### 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:

- `CMAKE_INSTALL_PREFIX` installation prefix of your KF5 installation [`on`/`off`, default=`/usr/local`]

  You can find out the correct value with the following command:

          % kf5-config --prefix

- `WITH_ALSA` enable playback/recording via ALSA [`on`/`off`, default=`on`]

- `WITH_DEBUG` build a debug version [`on`/`off`, default=`off`]

- `WITH_DOC` build online documentation [`on`/`off`, default=`on`]

- `WITH_FLAC` enable support for FLAC files [`on`/`off`, default=`on`]

- `WITH_MP3` enable support for mp3 files [`on`/`off`, default=`on`]

- `WITH_OGG_OPUS` enable support for Ogg/Opus files [`on`/`off`, default=`on`]

- `WITH_OGG_VORBIS` enable support for Ogg/Vorbis files [`on`/`off`, default=`on`]

- `WITH_OSS` enable playback/recording via OSS [`on`/`off`, default=`on`]

- `WITH_PULSEAUDIO` enable playback/recording via PulseAudio [`on`/`off`, default=`on`]

- `WITH_QT_AUDIO` enable playback via Qt Multimedia [`on`/`off`, default=`on`]

These options can be passed to ``cmake`` with ``-D``option``=``value``. For example, if you want to disable MP3 support, you can pass the corresponding option as follows:

        % cmake [source directory] -DCMAKE_INSTALL_PREFIX=`kf5-config --prefix` -DWITH_MP3=OFF [other options...]

## 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 spend 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. 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!