This is done as a separate commit to retain Git change file history association. (Git does not store renames. It assumes renames according to content similarity.)
The cross-document reference apparently worked on readthedocs (our previous docs), but does not work on GitHub.
The cross-document figure reference is replaced with a file reference.
Mumble can be compiled with several system libraries, so add their
development library to the list of Build-Depends.
In order to actually compile with them, you need to specify the
configuration options as described in cmake_options.md.
Those are for the newly added B-Ds:
1) -Dbundled-gsl=OFF
2) -Dbundled-speex=OFF
3) -Dbundled-json=OFF
Closes: #6644
Since Debian Bookworm the pkg-config package is a transitional package
to pkgconf, so update the build dependency install instructions to point
to its target.
In PR 6643 I accidentally updated the instructions for Ubuntu instead of
for Debian, so now actually update the instructions for Debian as well.
FTR: In Ubuntu Noble (2024.04) it's also a transitional package.
Link: https://github.com/mumble-voip/mumble/pull/6643
Since Debian Bookworm the pkg-config package is a transitional package
to pkgconf, so update the build dependency install instructions to point
to its target.
In a folder, GitHub shows a README by default, below the file list.
Combining the index.rst and introduction.rst, with text fixups, will serve as an appropriate landing page/doc.
Dropping the resources for Sphinx documentation generation drops support for generating this documentation into various formats (see make file; html, epub, and other less useful ones).
This network protocol documentation is the odd one out compared to our other documentation. The only one with this system.
Diverse tech has a maintenance cost, and the previous distance to our code made more likely to be missed for updates and discovery.
Handling only the network protocol documentation in this way feels disconnected/diverging.
Although readers may use the docs to implement clients and servers against only the docs, the question is whether the technology and maintenance additions are worth it.
Having simple structured text documentation files should serve us well enough.
It does for other developer documentation / documentation for developers.
We have documentation in the mumble-protocol repository and generated website.
The doc file in this repository serves as a simple reference pointing to those.
See also [mumble-www #59](https://github.com/mumble-voip/mumble-www/issues/59)
Due to RNNoise being unmaintained and the library's code being in very poor shape, this commit excludes the RNNoise feature from Mumble by default and discourages its use.
The library contains Opus and CELT symbols (probably due to copy&paste of code) that can end up being called from Opus instead of its own versions of these functions. This can lead to completely unforeseen behavior, including crashes.
An example of this is as of writing this, enabling RNNoise on macOS leads to a crash of Mumble pretty much as soon as it starts up with an "invalid instruction" error. The reason being that part of RNNoise's implementation of one of Opus's symbols contains a code path that produces an invalid instruction in optimized builds (and a segfault in debug builds) and this code path is taken when Opus (wrongly) uses this function instead of its own.
Fixes#6041
Due to RNNoise being unmaintained and the library's code being in very
poor shape, this commit excludes the RNNoise feature from Mumble by
default and discourages its use.
The library contains Opus and CELT symbols (probably due to copy&paste
of code) that can end up being called from Opus instead of its own
versions of these functions. This can lead to completely unforeseen
behavior, including crashes.
An example of this is as of writing this, enabling RNNoise on macOS
leads to a crash of Mumble pretty much as soon as it starts up with an
"invalid instruction" error. The reason being that part of RNNoise's
implementation of one of Opus's symbols contains a code path that
produces an invalid instruction in optimized builds (and a segfault in
debug builds) and this code path is taken when Opus (wrongly) uses this
function instead of its own.
Fixes#6041
Having different include files that are needed (and which are inter-dependent) to create your own plugin, makes things harder than it needs to be.
Therefore, all plugin header files (those for the "new" (1.4) plugin framework anyway) have been combined into one header file. Thus, developers now only have to download a single file and include that instead of having to figure out what files to download and what to include where.
Taking the chance, the version number has been removed from the header file's name. This allows one to track changes made to the API via git (which is not quite as easy if you create a new file every time you make a change).
Having different include files that are needed (and which are
inter-dependent) to create your own plugin, makes things harder than it
needs to be.
Therefore, all plugin header files (those for the "new" (1.4) plugin
framework anyway) have been combined into one header file. Thus,
developers now only have to download a single file and include that
instead of having to figure out what files to download and what to
include where.
Taking the chance, the version number has been removed from the header
file's name. This allows one to track changes made to the API via git
(which is not quite as easy if you create a new file every time you make
a change).
Instead of having a fixed setting that affects all build modes, we now
set LTO only for release builds (but then for all targets). This has the
advantage that a dev doesn't have to switch LTO on and off when
switching between Release and Debug builds.
Since newer versions of libsndfile now link to the system-wide installed
Opus version (on Linux distros), there would be a conflict between
symbols defined in the system-wide installation and the self-built
(bundled) Opus library.
This, as it turned out, can lead for instance to failing assertions due
to pointer identities no longer holding because e.g. a function from the
self-built Opus version ends up calling a sub-function from the
system-wide Opus installation instead. This is also the root cause for
the infamous "Opus crash" or "Audio wizard crash".
In order to avoid these issues, we don't ship a bundled Opus version
anymore and instead make it a build prerequisite to have Opus installed
on your system.
Fixes#5302
Since newer Opus versions appear to cause crashes under some
circumstances, we downgrade our Opus submodule to point to the latest
stable release, which is v1.3.1 from 2019.
We will only be able to upgrade again, once the underlying issue causing
the crashes has been identified and fixed.
Fixes#5302
