diff options
19 files changed, 705 insertions, 22 deletions
@@ -28,6 +28,11 @@ The documentation of the project can be found on the [wiki](https://wiki.mumble. [FAQ](https://wiki.mumble.info/wiki/FAQ/English) can also be found there. +## Building + +For information on how to build Mumble, checkout [the dedicated documentation](docs/dev/build-instructions/README.md). + + ## Reporting issues If you want to report a bug or create a feature-request, you can open a new issue (after you have checked that there is none already) on diff --git a/docs/AudioInputDebug.md b/docs/dev/AudioInputDebug.md index d94d66357..ba51f3023 100644 --- a/docs/AudioInputDebug.md +++ b/docs/dev/AudioInputDebug.md @@ -2,9 +2,11 @@ Mumble does quite a bit of signal processing on the raw microphone input, so if something breaks it may not be immediately apparent _where_ it breaks. -For this reason, the `--dump-input-streams` option was added, to help tap into various parts of the DSP chain, and find where the issue is. Consider it a bit like the digital equivalent of probing with an oscilloscope the signal path of an analog audio gear. +For this reason, the `--dump-input-streams` option was added, to help tap into various parts of the DSP chain, and find where the issue is. Consider +it a bit like the digital equivalent of probing with an oscilloscope the signal path of an analog audio gear. -As the option was introduced to debug the echo canceller, the default tap points are at the input and output of that algorithm, but if you are going to debug some C++ code, you should not have problems moving a `write()` to an `ofstream` here and there should you need to, right? +As the option was introduced to debug the echo canceller, the default tap points are at the input and output of that algorithm, but if you are going +to debug some C++ code, you should not have problems moving a `write()` to an `ofstream` here and there should you need to, right? ## How to use `--dump-input-streams` @@ -14,7 +16,9 @@ You'll need to run Mumble from the command line, and the directory from where yo $ ./mumble --dump-input-streams ``` -Then log into a server as usual, and start using Mumble. It's usually good enough to just run it for 10/20 seconds and then quit. Unless your bug happens only after some time or occurs at random, there's no need to accumulate gigabytes of dumped audio. It's also best to make reproducible tests, like playing the same video or speaking the same phrase, so as to compare results. +Then log into a server as usual, and start using Mumble. It's usually good enough to just run it for 10/20 seconds and then quit. Unless your bug +happens only after some time or occurs at random, there's no need to accumulate gigabytes of dumped audio. It's also best to make reproducible tests, +like playing the same video or speaking the same phrase, so as to compare results. After closing Mumble, there should be 3 new files in the directory you launched it from: @@ -22,37 +26,48 @@ After closing Mumble, there should be 3 new files in the directory you launched * `speaker_dump` * `processed_microphone_dump` -Please note that if you run Mumble again, those files will be overwritten. Also, those files are overwritten whenever the `AudioInput` class is reinstantiated, such as when going though the audio wizard. If you find it difficult to get the data you want, such as because closing the audio wizard clears your files, terminate Mumble with Ctrl-C at any moment and the files won't be erased. +Please note that if you run Mumble again, those files will be overwritten. Also, those files are overwritten whenever the `AudioInput` class is +reinstantiated, such as when going though the audio wizard. If you find it difficult to get the data you want, such as because closing the audio +wizard clears your files, terminate Mumble with Ctrl-C at any moment and the files won't be erased. ### Opening the files These files contain the raw PCM streams that have been sampled. No header, no file format; nothing. Just data. -This makes the dumping code as simple as possible, and you also don't have to change the header every time you tap a point with a different sample rate or encoding, as there's no header. +This makes the dumping code as simple as possible, and you also don't have to change the header every time you tap a point with a different sample +rate or encoding, as there's no header. To open the raw files, you can use Audacity. Select `File > Import > Raw Data`. Since there's no metadata, Audacity will ask you what's in those files: -* Encoding is `Signed 16 bit PCM` in the default tap point (i.e. you haven't modified `write()`). Mumble's signal path is partly 16 bit and partly float, so remember to select `32 bit float` if you move the tap points to some float part of the Mumble audio path. +* Encoding is `Signed 16 bit PCM` in the default tap point (i.e. you haven't modified `write()`). Mumble's signal path is partly 16 bit and partly + float, so remember to select `32 bit float` if you move the tap points to some float part of the Mumble audio path. * Byte order is `Little-endian` if you're on an x86 CPU, which you most likely are. * Channels is always `1` for the microphone signal path, but may be more for the speaker readback if you use multichannel echo cancellation. -* Sample rate is `48000` for the default tap point, as Mumble's audio chain resamples everything to 48KHz regardless of what your audio card is configured to. Change accordingly when tapping before the resampler. +* Sample rate is `48000` for the default tap point, as Mumble's audio chain resamples everything to 48KHz regardless of what your audio card is + configured to. Change accordingly when tapping before the resampler. In Audacity you can open multiple tracks and mute them individually, so it's usually a good idea to open all three tracks to compare. ## Debugging the echo canceller -The audio dumps have an additional property that is fundamental for debugging the echo canceller: the're synchronous. If you open them all in Audacity, you'll be able not only to see what gets passed to the echo canceller, but the relative time between the signals. +The audio dumps have an additional property that is fundamental for debugging the echo canceller: the're synchronous. If you open them all in +Audacity, you'll be able not only to see what gets passed to the echo canceller, but the relative time between the signals. -This is fundamental for an echo canceller, which can break simply because the microphone data arrives before the speaker one (how can the echo canceller predict an echo from the future?), or if the speaker data is so ahead that exceeds its limited filter length. +This is fundamental for an echo canceller, which can break simply because the microphone data arrives before the speaker one (how can the echo +canceller predict an echo from the future?), or if the speaker data is so ahead that exceeds its limited filter length. ### The `--print-echocancel-queue` option -Now that I've mentioned the requirement for the echo canceller to have well aligned inputs, maybe it's best to introduce the `--print-echocancel-queue` option. When running Mumble with this option, the current state of the queue in the Resynchronizer class is used to align the microphone and speaker readback streams is printed on the command line. Moreover, if packets are dropped (which is necessary to keep the signals aligned if the OS/pulseaudio/audio card is playing tricks to us), those will be printed as well. +Now that I've mentioned the requirement for the echo canceller to have well aligned inputs, maybe it's best to introduce the +`--print-echocancel-queue` option. When running Mumble with this option, the current state of the queue in the Resynchronizer class is used to align +the microphone and speaker readback streams is printed on the command line. Moreover, if packets are dropped (which is necessary to keep the signals +aligned if the OS/pulseaudio/audio card is playing tricks to us), those will be printed as well. ### The Resynchronizer class -Documentation on the Resynchronizer class is put as a comment in the `AudioInput.h` file, but it doesn't hurt to repeat it here, also because the statemachine design doesn't fit in a C++ comment as it's an image. +Documentation on the Resynchronizer class is put as a comment in the `AudioInput.h` file, but it doesn't hurt to repeat it here, also because the +statemachine design doesn't fit in a C++ comment as it's an image. According to https://www.speex.org/docs/manual/speex-manual/node7.html "It is important that, at any time, any echo that is present in the input @@ -74,17 +89,23 @@ statemachine that introduces packet drops to control the fill level to at least 2 (plus or minus one) and less than 4 elements. With a 10ms chunk, this queue should introduce a ~20ms lag to the voice. - + -Here _m_ means a microphone chunk was received, _s_ a speaker chunk was received, and the number in the state is the queue fill level. The design tries to keep the limit cycle of the queue add/remove pattern between 1 and 4 elements, preventing the queue to operate in a limit cycle between 0 and 1 elements (queue too empty, the speaker data may risk arriving after the microphone) and in a limit cycle between 4 and 5 elements (too full, we're wasting some precious filter length to cancel real echo just because some delay accumulated). +Here _m_ means a microphone chunk was received, _s_ a speaker chunk was received, and the number in the state is the queue fill level. The design +tries to keep the limit cycle of the queue add/remove pattern between 1 and 4 elements, preventing the queue to operate in a limit cycle between 0 and +1 elements (queue too empty, the speaker data may risk arriving after the microphone) and in a limit cycle between 4 and 5 elements (too full, we're +wasting some precious filter length to cancel real echo just because some delay accumulated). ### A reproducible test for verifying the correct operation of the echo canceller -To avoid regressions being introduced in the echo cancellation feature, it is beneficial to have a controlled test that can be easily reproduced to test whether the echo canceller works. +To avoid regressions being introduced in the echo cancellation feature, it is beneficial to have a controlled test that can be easily reproduced to +test whether the echo canceller works. You will need: -* Low quality headphones that cause echo. The in-ear type that's used with smartphones and has a combined microphone/headphones jack works best. If you don't have them or your PC lacks a combined microphone/headphones jack, do the test with your speakers, but keep the volume relatively quiet. Some echo is unavoidable at high volume levels, especially if it makes the microphone clip. +* Low quality headphones that cause echo. The in-ear type that's used with smartphones and has a combined microphone/headphones jack works best. If + you don't have them or your PC lacks a combined microphone/headphones jack, do the test with your speakers, but keep the volume relatively quiet. + Some echo is unavoidable at high volume levels, especially if it makes the microphone clip. * A quiet Mumble server to connect to. Just join an empty room with no other users. Here's the step by step guide: @@ -92,19 +113,26 @@ Here's the step by step guide: 1. Make sure Mumble echo cancellation is enabled. You may also need to repeat this test twice with mixed and multichannel echo cancellation. 1. Run Mumble with the `--dump-input-streams` option 2. Join the quiet server -3. Play the first 15 or so seconds of a YouTube video that contains both a relatively periodic note and voice, such as this one: https://www.youtube.com/watch?v=im9z8NT96Iw +3. Play the first 15 or so seconds of a YouTube video that contains both a relatively periodic note and voice, such as this one: + https://www.youtube.com/watch?v=im9z8NT96Iw 4. Say a phrase, such as "Testing 1 2 3" 5. Close Mumble -6. Open the three dumped streams in Audacity. Don't forget to select the correct number of channels for the `speaker_dump` when testing multichannel echo cancellation -7. Play the raw microphone stream, you should hear the echo of the YouTube video clearly above the noise, and it should be less loud than you saying "Testing 1 2 3". If you hear no echo, increase you headphones volume, switch to worse headphones or use your speakers and repeat. If the echo is as loud as or louder than you speaking, reduce your audio volume and repeat. -8. Now listen to the processed microphone stream: the echo should be almost gone, both the note and the voice coming from YouTube, while your voice should remain. It is acceptable that after a silence gap, the first part of the echo can reappear, but it should quickly be cancelled. If not, there's a bug in Mumble. +6. Open the three dumped streams in Audacity. Don't forget to select the correct number of channels for the `speaker_dump` when testing multichannel + echo cancellation +7. Play the raw microphone stream, you should hear the echo of the YouTube video clearly above the noise, and it should be less loud than you saying + "Testing 1 2 3". If you hear no echo, increase you headphones volume, switch to worse headphones or use your speakers and repeat. If the echo is as + loud as or louder than you speaking, reduce your audio volume and repeat. +8. Now listen to the processed microphone stream: the echo should be almost gone, both the note and the voice coming from YouTube, while your voice + should remain. It is acceptable that after a silence gap, the first part of the echo can reappear, but it should quickly be cancelled. If not, + there's a bug in Mumble. 9. Play the speaker dump. It should sound as well as the YouTube video itself. If not, there's a bug in Mumble. -10. As a final check, take a transition from silence to noise as a reference and zoom in in Audacity: the speaker dump should precede the microphone dump by 20ms or so (0 to 50ms is acceptable). If not, there's a bug in Mumble. +10. As a final check, take a transition from silence to noise as a reference and zoom in in Audacity: the speaker dump should precede the microphone + dump by 20ms or so (0 to 50ms is acceptable). If not, there's a bug in Mumble. Example of an echo canceller bug: the speaker data lags compared to the microphone one. As a result, only the note is cancelled, but voice is not. - + Exampe of the a working echo canceller. - + diff --git a/docs/MurmurLocking.md b/docs/dev/MurmurLocking.md index a8e5ed4a6..a8e5ed4a6 100644 --- a/docs/MurmurLocking.md +++ b/docs/dev/MurmurLocking.md diff --git a/docs/dev/build-instructions/README.md b/docs/dev/build-instructions/README.md new file mode 100644 index 000000000..326dd64d7 --- /dev/null +++ b/docs/dev/build-instructions/README.md @@ -0,0 +1,19 @@ +# Build Mumble + +A fundamental dependency for building Mumble is [git](https://git-scm.com/), so make sure you have it installed. If you are new to git, make sure to +checkout [this guide](https://guides.github.com/introduction/git-handbook/) on git's basics in order to be able to follow the given instructions. + +The first step in building Mumble is to clone this repository via `git clone https://github.com/mumble-voip/mumble.git`. + +In order to actually build Mumble, you can follow one of the following instruction sets: +- [Build on Windows](build_windows.md) +- [Build on Linux](build_linux.md) +- [Build on macOS](build_macos.md) +- [Static build](build_static.md) + + +Furthermore you might find these helpful as well: +- [FAQ](faq.md) +- [List of available cmake options](cmake_options.md) +- [IDE integration](ide_integration.md) +- [Create an installer](build_installer.md) diff --git a/docs/dev/build-instructions/build_installer.md b/docs/dev/build-instructions/build_installer.md new file mode 100644 index 000000000..44424f866 --- /dev/null +++ b/docs/dev/build-instructions/build_installer.md @@ -0,0 +1,12 @@ +# Creating an installer + +Currently, the installer creation has been tested on Windows only. + +For creating the installer, the [WiX Toolset](https://wixtoolset.org/) has to be installed on your system. + +An installer can be created after invoking cmake with the `-Dpackaging=ON` option and building. + +To create a *single-language* installer (default English) run `cpack -C Release`. + +To create a *multi-language* installer run the script `scripts/Create-Win32InstallerMUI.ps1` from the root of this repository. + diff --git a/docs/dev/build-instructions/build_linux.md b/docs/dev/build-instructions/build_linux.md new file mode 100644 index 000000000..dc945518f --- /dev/null +++ b/docs/dev/build-instructions/build_linux.md @@ -0,0 +1,63 @@ +# Building on Linux + +These are instructions for performing a regular build using the libraries that are shipped with your distribution. For instructions to build a static +version of Mumble, checkout [this file](build_static.md). + +## Dependencies + +In order to install the needed dependencies on Ubuntu, you have to run the following command: +```bash +sudo apt install \ + build-essential \ + cmake \ + pkg-config \ + qt5-default \ + qttools5-dev \ + qttools5-dev-tools \ + libqt5svg5-dev \ + libboost-dev \ + libssl-dev \ + libprotobuf-dev \ + protobuf-compiler \ + libcap-dev libxi-dev \ + libasound2-dev \ + libogg-dev \ + libsndfile1-dev \ + libspeechd-dev \ + libavahi-compat-libdnssd-dev \ + libzeroc-ice-dev +``` + +If you are using a distribution that is not based on Ubuntu, you probably have to change the command accordingly. + +You will need `cmake` **v3.15 or later**. If the version shipped by your distribution is not recent enough, you can install a recent one via the +[official PPA](https://apt.kitware.com/) by following the instructions on the linked page. + + +## Running cmake + +It is recommended to perform a so-called "out-of-source-build". In order to do so, navigate to the root of the Mumble directory and then issue the +following commands: +1. `mkdir build` (Creates a build directory) +2. `cd build` (Switches into the build directory) +3. `cmake ..` (Actually runs cmake) + +This will cause cmake to create the necessary build files for you. If you want to customize your build, you can pass special flags to cmake in step 3. +For all available build options, have a look [here](cmake_options.md). + +E.g. if you only want to build the server, use `cmake -Dclient=OFF ..`. + + +## Building + +By default cmake will create Makefiles if run on Linux, so in order to build, you can simply run `make` in the build directory. If you want to +parallelize the build (to speed things up), you can use `make -j $(nproc)`. + +If you want to stay independent of the type of the generated build files, you should issue `cmake --build .` (from the build directory) in order to +start the compilation. If you want to parallelize the build, use `cmake --build . -j <jobs>` where `<jobs>` is the amount of parallel jobs to be run +concurrently. A good choice usually is `<jobs> = $(nproc)`. + + +## FAQ + +See the general [build-FAQ](faq.md). diff --git a/docs/dev/build-instructions/build_macos.md b/docs/dev/build-instructions/build_macos.md new file mode 100644 index 000000000..ef9a505a5 --- /dev/null +++ b/docs/dev/build-instructions/build_macos.md @@ -0,0 +1,45 @@ +# Building on macOS + +These instructions are for performing a regular build of Mumble that will only run on systems that have the necessary libraries installed on them. For +building a static version, checkout [this file](build_static.md). + +## Dependencies + +On macOS, you can use [homebrew](https://brew.sh/) to install the needed packages. If you don't have it installed already, you can follow the +instruction on their official website to install homebrew itself. + +Once homebrew is installed, you can run the following command to install all required packages: +```bash +brew update && brew install \ + cmake \ + pkg-config \ + qt5 \ + boost \ + libogg \ + libvorbis \ + flac \ + libsndfile \ + protobuf \ + openssl \ + ice +``` + + +## Running cmake + +It is recommended to perform a so-called "out-of-source-build". In order to do so, navigate to the root of the Mumble directory and the issue the +following commands: +1. `mkdir build` (Creates a build directory) +2. `cd build` (Switches into the build directory) +3. `cmake ..` (Actually runs cmake) + +This will cause cmake to create the necessary build files for you. If you want to customize your build, you can pass special flags to cmake in step 3. +For all available build options, have a look [here](cmake_options.md). + +E.g. if you only want to build the server, use `cmake -Dclient=OFF ..`. + + +## Building + +Once cmake has been run, you can issue `cmake --build .` from the build directory in order to actually start compiling the sources. If you want to +parallelize the build, use `cmake --build . -j <jobs>` where `<jobs>` is the amount of parallel jobs to be run concurrently. diff --git a/docs/dev/build-instructions/build_static.md b/docs/dev/build-instructions/build_static.md new file mode 100644 index 000000000..e80f7af9b --- /dev/null +++ b/docs/dev/build-instructions/build_static.md @@ -0,0 +1,214 @@ +# Building static Mumble + +These instructions are for creating a static build of Mumble. "Static" means that it bundles most (all) of its dependencies into the built library in +order to make it run on systems that don't have the necessary dependencies installed. + + +## Dependencies + +We are using [vcpkg](https://github.com/Microsoft/vcpkg) in order to manage the dependencies needed for the build. This package manager is available +on all major platforms (Windows, Linux, macOS, probably more), so the instructions here apply to all of these systems. + +The entire build environment will require between 30GB and 60GB of space on your hard-drive. If installed via script, it tends to converge towards the +lower bound whereas a manual installation usually tends towards the higher bound. + +In addition to the dependencies installed via vcpkg, you'll also need [cmake](https://cmake.org/) (v3.15 or later). On Linux you might have to install +cmake using a [PPA](https://apt.kitware.com/) and on macOS you can install it using [homebrew](https://formulae.brew.sh/formula/cmake). + + +### Installing via script + +The recommended way to install vcpkg and the dependencies on your system, is to run one of the installation scripts on your system. If you are on +Windows, that'd be [get_mumble_dependencies.ps1](../../../scripts/vcpkg/get_mumble_dependencies.ps1). If you are on Linux or macOS, you have to use +[get_mumble_dependencies.sh](../../../scripts/vcpkg/get_mumble_dependencies.sh). + +On Windows you'll have to run the script by opening a PowerShell window, executing `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` and then +running the mentioned script. On Linux and macOS no such preliminaries are necessary. + +The respective script will clone and install vcpkg to your user's home directory by default (note that vcpkg itself will install all dependencies into +the same directory). If you want to change that, you'll have to adapt the scripts before running. + +If you already have vcpkg installed on your system, you should probably prefer using the manual installation of dependencies in order to avoid a +second vcpkg installation (unless of course you want to edit the respective script accordingly). + + +### Manual installation + +If you don't have vcpkg installed on your system, clone the [git repostory](https://github.com/microsoft/vcpkg.git) and follow the instructions in +their README file. + +Once vcpkg is installed on your system, you have to switch into the directory vcpkg is installed in and then install the following packages: +``` +qt5-base +qt5-svg +qt5-tools +grpc +boost-accumulators +opus +poco +libvorbis +libogg +libflac +libsndfile +libmariadb +zlib +``` + +The command for installing a package is `vcpkg install <packageName> --triplet <triplet>` where `<packageName>` is to be replaced with the name of the +package you want to install and `<triplet>` is the desired target triplet. We recommend using these triplets: + +| **OS** | **Triplet** | +|--------|-------------| +| Windows | x64-windows-static-md | +| Linux | x64-linux | +| macOS | x64-osx | + +Therefore if you are on Windows, you'd install `qt5-base` as `vcpkg install qt5-base --triplet x64-windows-static-md`. + +**Important**: If you want to include the [Ice RPC framework](https://zeroc.com/products/ice) support when building the server, you have to also use +vcpkg to install `zeroc-ice`. At the moment Ice can't be built using cmake though and therefore there does not exists a native vcpkg port (install +target) for it. + +Instead you'll have to copy the entire [zeroc-ice directory](../../../helpers/vcpkg/ports/zeroc-ice) (not only the contents!) to `<vcpkg dir>/ports/` +where `<vcpkg dir>` is the directory you installed vcpkg into. This will make our custom ice port available to be installed via vcpkg. Just install +as a regular vcpkg package named `zeroc-ice`. + +Note: The custom port uses our [own fork](https://github.com/mumble-voip/ice) of Ice that includes support for cmake. + + +### Additional dependencies on Linux + +Additional `dev` packages will need to be installed for some components in vcpkg on GNU/Linux: + +* `libxi(X11)` +* `libgl1-mesa` +* `libglu1-mesa` +* `mesa-common` +* `libxrandr` +* `libxxf86vm` + +vcpkg will also require installation of: + +* `python3` +* `python2` +* `python` + +Most GNU/Linux distros should have these or equivalent packages. + + +### Additional dependencies on macOS + +The following is required for macOS: + +* `Xquartz` + + +## Building Mumble + +After all dependencies are installed, you can follow these steps in order to actually build Mumble itself: + +1. Start a command line (on Windows see caveats listed below) +2. Clone the Mumble repo <https://github.com/mumble-voip/mumble.git> (if not done already) +3. Navigate into the cloned directory +5. Create a directory named `build` and navigate into it (`mkdir build && cd build`) +6. Run the cmake generator with relative target path `..` (more on that further down) +7. Run the cmake in build-mode: `cmake --build .` or invoke your buildsystem of choice directly (e.g. `make -j $(nproc)`) + +cmake will generate a bunch of files so you should call it from a dedicated, empty directory ("out-of-source build"). In the list above we suggest +`build`. + + +#### Windows caveats + +On Windows you can't use the default command-prompt (as is) as it won't have the needed development tools in its PATH. Instead you have to use +a "Developer Command Prompt". You can find it by searching in the start-menu. If you are on a 64bit system, then special care must be taken +that you use a "x64" version of the Developer Prompt (often these are then called "x64 Native Tools Command Prompt"). The easiest way to get a hold of +the correct command prompt is to search for "x64" and usually that is enough to bring up the x64 developer prompt in the search results. + +Note also that you **have** to use the command prompt and **not** the Developer Powershell as the latter is always 32bit only. + +If you are on a 64bit system, then you'll know that you have opened the correct prompt, if it prints `Environment initialized for: 'x64'`. + + +#### CMake Generator + +Important configuration options + +| Option | Value | Description | +| --- | --- | --- | +| `VCPKG_TARGET_TRIPLET` | `x64-windows-static-md` or `x64-linux` or `x64-osx` | The vcpkg triplet chosen when installing the dependencies via vcpkg | +| `CMAKE_TOOLCHAIN_FILE` | `<vcpkg_root>/scripts/buildsystems/vcpkg.cmake` | | +| `Ice_HOME` | `<vcpkg dir>/installed/x64-windows-static-md` | Required if you build with Ice (enabled by default) | +| `static` | `ON` | | + +`<vcpkg dir>` is a placeholder for your prepared build environment vcpkg setup (the path to the vcpkg directory created by the get_dependency script). + +For Linux the cmake invokation may be (using the default generator `make`) + +```bash +cmake "-DVCPKG_TARGET_TRIPLET=x64-linux" "-Dstatic=ON" "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" "-DIce_HOME=<vcpkg dir>/installed/x64-linux" "-DCMAKE_BUILD_TYPE=Release" .. +``` + +For macOS the command may be +```bash +cmake "-DVCPKG_TARGET_TRIPLET=x64-osx" "-Dstatic=ON" "-DCMAKE_TOOLCHAIN_FILE=<vcpkg dir>/scripts/buildsystems/vcpkg.cmake" "-DIce_HOME=<vcpkg dir>/installed/x64-osx" "-DCMAKE_BUILD_TYPE=Release" .. +``` + +For Windows the command may be + +```bash +cmake -G "NMake Makefiles" "-DVCPKG_TARGET_TRIPLET=x64-windows-static-md" "-Dstatic=ON" "-DCMAKE_TOOLCHAIN_FILE=<vcpkg_root>/scripts/buildsystems/vcpkg.cmake" "-DIce_HOME=<vcpkg_root>/installed/x64-windows-static-md" "-DCMAKE_BUILD_TYPE=Release" .. +``` + +Optionally you can use `-G "Ninja"` to use the [Ninja buildsystem](https://ninja-build.org/) (which probably has to be installed separately). +Especially on Windows this is recommended as the default `NMake Makefiles` only compile using a single thread (which takes quite a while). + + +### Customizing the build + +There are various options that can be passed to cmake when performing step 6 from above. See [here](cmake_options.md) for details. + + +## Troubleshooting + +See also our [general build FAQ](faq.md) if your problem is not listed below. + +### sndfile not found + +This is an error that is often encountered on 64bit Windows systems. The problem is usually that you have used the wrong developer command prompt and +therefore cmake is trying to build a 32bit version of Mumble. The `./Get-MumbleDeps.ps1` script automatically detects your system's architecture and +only builds the 64bit version of the libraries (including `sndfile`). cmake then tries to locate a 32bit version of the library and fails as only the +64bit version is present. + +The solution is to use a x64 developer command prompt. You can see what kind of build cmake is performing at the top of the cmake output. For 64 bit +it should say `Architecture: 64bit`. + +NOTE: If you initially have run cmake from the wrong prompt (32bit), then you'll have to delete all files in your `build` directory before running +cmake again from the new prompt. Otherwise cmake will not check the architecture again and proceed with the cached 32bit variant. + +### CMake can't find library + +If cmake doesn't find a library and you don't really know why this might be, you can use `-Ddebug-dependency-search=ON` when running cmake in order to +get a lot of debug information regarding the search for the needed dependencies. Chances are that this will shed some light on the topic. + +### Unable to download from https://repo.msys2.org + +This can happen if you're using a system that doesn't support TLS 1.3 (which https://repo.msys2.org requires) such as Windows 7. In this case the only +possible workaround is either to download the respective files manually using a brower that does support TLS 1.3 (e.g. Firefox) or to replace all +occurences of `https://repo.msys2.org` in the vcpkg dir with `http://repo.msys2.org` and thereby forxing vcpkg to use the HTTP mirror instead. Note +though that this is inherently unsafer than using HTTPS. + +A common error message for this scenario could be +``` +-- Acquiring MSYS2... +-- Downloading https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-base-x86_64-20190524.tar.xz/download... +-- Downloading https://repo.msys2.org/msys/x86_64/msys2-keyring-r21.b39fb11-1-any.pkg.tar.xz... +-- Downloading https://repo.msys2.org/msys/x86_64/msys2-keyring-r21.b39fb11-1-any.pkg.tar.xz... Failed. Status: 35;"SSL connect error" +CMake Error at scripts/cmake/vcpkg_download_distfile.cmake:173 (message): + + Failed to download file. + If you use a proxy, please set the HTTPS_PROXY and HTTP_PROXY environment + variables to "https://user:password@your-proxy-ip-address:port/". + Otherwise, please submit an issue at https://github.com/Microsoft/vcpkg/issue +``` +Ref: https://github.com/microsoft/vcpkg/issues/13217 diff --git a/docs/dev/build-instructions/build_windows.md b/docs/dev/build-instructions/build_windows.md new file mode 100644 index 000000000..3695d2295 --- /dev/null +++ b/docs/dev/build-instructions/build_windows.md @@ -0,0 +1,3 @@ +# Building on Windows + +On Windows we only support [static builds](build_static.md). diff --git a/docs/dev/build-instructions/cmake_options.md b/docs/dev/build-instructions/cmake_options.md new file mode 100644 index 000000000..67508b6a6 --- /dev/null +++ b/docs/dev/build-instructions/cmake_options.md @@ -0,0 +1 @@ +# cmake options diff --git a/docs/dev/build-instructions/faq.md b/docs/dev/build-instructions/faq.md new file mode 100644 index 000000000..7242ea2fb --- /dev/null +++ b/docs/dev/build-instructions/faq.md @@ -0,0 +1,10 @@ +# Build FAQ + +### How can I specify the build type + +In order to set the build type (Debug vs Release), you have to use the `CMAKE_BUILD_TYPE` variable when invoking cmake like so: `cmake +-DCMAKE_BUILD_TYPE=Release`. The supported types currently are: "Debug" and "Release". + +Note that this only works for *single-config* generators. If you are using a *multi-config* generator (e.g. visual studio projects), the steps +mentioned above won't have any effect. Instead, you'll have to choose the config type when invoking the build itself. This works by using e.g. `cmake +--build . --config Release`. diff --git a/docs/dev/build-instructions/ide_integration.md b/docs/dev/build-instructions/ide_integration.md new file mode 100644 index 000000000..86a9e21c7 --- /dev/null +++ b/docs/dev/build-instructions/ide_integration.md @@ -0,0 +1,25 @@ +# IDE integration + +## Visual Studio + +[Visual Studio supports cmake projects](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=vs-2019) when you install the +*C++ cmake tools for Windows* in the Visual Studio Installer. + +* Start Visual Studio +* Open the project folder (with the open folder option) +* In the cmake configuration settings specify the cmake toolchain file + This file should be at `%USERPROFILE%/mumble-vcpkg/scripts/buildsystems/vcpkg.cmake` after using `get-mumble_deps.sh`. +* As cmake command argument add `-DVCPKG_TARGET_TRIPLET=x64-windows-static-md -Dstatic=ON -DIce_HOME=%USERPROFILE%/mumble-vcpkg/installed/x64-windows-static-md` +* Save and cmake should generate the build files, which will take a bit of time +* Use the build all action to build the project +* On success the built binaries will be placed in `out\build\<configuration-name>\` + +Note: Visual Studio may wrongfully identify the error `The system was unable to find the specified registry key or value.` despite the build +succeeding. This is due to a VS script that outputs `ERROR` as text early on in the build process. The queried registry key is not required for the +build to succeed. Check the text Output or for other errors instead and **ignore this specific error**. + +## Other IDEs with cmake support + +IDE's such as Qt Creator, Visual Studio and VS Code (Code OSS) are capable of handling the configure and build step as part of the normal operation of +the IDE. The needed cmake options are called "Configure Arguments" and would need to be added for the project or workspace settings in the IDE when +the source folder is opened as a cmake project. diff --git a/docs/AudioInputDebugFiles/bug.png b/docs/media/images/AudioInputDebugging_Bug.png Binary files differindex e5b0eafb5..e5b0eafb5 100644 --- a/docs/AudioInputDebugFiles/bug.png +++ b/docs/media/images/AudioInputDebugging_Bug.png diff --git a/docs/AudioInputDebugFiles/fix.png b/docs/media/images/AudioInputDebugging_Fix.png Binary files differindex c8d5ce998..c8d5ce998 100644 --- a/docs/AudioInputDebugFiles/fix.png +++ b/docs/media/images/AudioInputDebugging_Fix.png diff --git a/docs/AudioInputDebugFiles/fsm.png b/docs/media/images/AudioInputDebugging_Fsm.png Binary files differindex fc6fddab8..fc6fddab8 100644 --- a/docs/AudioInputDebugFiles/fsm.png +++ b/docs/media/images/AudioInputDebugging_Fsm.png diff --git a/helpers/vcpkg/ports/zeroc-ice/CONTROL b/helpers/vcpkg/ports/zeroc-ice/CONTROL new file mode 100644 index 000000000..0a52b17ce --- /dev/null +++ b/helpers/vcpkg/ports/zeroc-ice/CONTROL @@ -0,0 +1,9 @@ +Source: zeroc-ice
+Version: 3.7.3
+Homepage: https://github.com/zeroc-ice/ice
+Description: Comprehensive RPC framework with support for C++, CSharp, Java, JavaScript, Python and more.
+Build-Depends: bzip2 (!uwp), expat (!uwp), mcpp, lmdb (!uwp), openssl (!uwp), zlib (!uwp)
+
+Feature: cpp11
+Description: build C++11 libraries
+Build-Depends: bzip2, expat, mcpp, openssl, mcpp, zlib
diff --git a/helpers/vcpkg/ports/zeroc-ice/portfile.cmake b/helpers/vcpkg/ports/zeroc-ice/portfile.cmake new file mode 100644 index 000000000..9062aaa80 --- /dev/null +++ b/helpers/vcpkg/ports/zeroc-ice/portfile.cmake @@ -0,0 +1,55 @@ +vcpkg_from_github(
+ OUT_SOURCE_PATH SOURCE_PATH
+ REPO mumble-voip/ice
+ REF 3.7
+ SHA512 12cebb53ad1a9271e7db8c12df5f2db9f8cbaec97b562596c4c592bd2449177b6927156100166b432b7e27b13f0d202155748691fd1e848eb6db815f16bcc57f
+)
+
+if("cpp11" IN_LIST FEATURES)
+ vcpkg_configure_cmake(
+ SOURCE_PATH ${SOURCE_PATH}
+ PREFER_NINJA
+ OPTIONS
+ -DBUILD_ICE_CXX=ON
+ -DBUILD_ICE_CPP11=ON
+ )
+else()
+ vcpkg_configure_cmake(
+ SOURCE_PATH ${SOURCE_PATH}
+ PREFER_NINJA
+ OPTIONS
+ -DBUILD_ICE_CXX=ON
+ )
+endif()
+
+vcpkg_install_cmake()
+
+vcpkg_copy_pdbs()
+
+file(INSTALL ${SOURCE_PATH}/cpp/include DESTINATION ${CURRENT_PACKAGES_DIR})
+file(INSTALL ${SOURCE_PATH}/slice DESTINATION ${CURRENT_PACKAGES_DIR})
+file(INSTALL ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/include
+ DESTINATION ${CURRENT_PACKAGES_DIR}
+)
+
+if(EXISTS ${CURRENT_PACKAGES_DIR}/bin)
+ file(INSTALL ${CURRENT_PACKAGES_DIR}/bin/ DESTINATION ${CURRENT_PACKAGES_DIR}/tools/Ice)
+endif()
+
+file(INSTALL ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel/icebuilder/bin/ DESTINATION ${CURRENT_PACKAGES_DIR}/tools/Ice)
+
+vcpkg_copy_tool_dependencies(${CURRENT_PACKAGES_DIR}/tools/Ice)
+
+if(UNIX)
+ vcpkg_execute_required_process(COMMAND chmod -R +x Ice
+ WORKING_DIRECTORY ${CURRENT_PACKAGES_DIR}/tools
+ LOGNAME ice-${TARGET_TRIPLET}-setexe
+ )
+endif()
+
+file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/bin ${CURRENT_PACKAGES_DIR}/debug/bin)
+
+file(REMOVE_RECURSE ${CURRENT_PACKAGES_DIR}/debug/include)
+
+file(INSTALL ${SOURCE_PATH}/LICENSE DESTINATION ${CURRENT_PACKAGES_DIR}/share/${PORT} RENAME copyright)
+file(INSTALL ${SOURCE_PATH}/ICE_LICENSE DESTINATION ${CURRENT_PACKAGES_DIR}/share/${PORT})
diff --git a/scripts/vcpkg/get_mumble_dependencies.ps1 b/scripts/vcpkg/get_mumble_dependencies.ps1 new file mode 100644 index 000000000..50d47734b --- /dev/null +++ b/scripts/vcpkg/get_mumble_dependencies.ps1 @@ -0,0 +1,92 @@ +$profiledir = $Env:USERPROFILE
+$vcpkgdir = $profiledir + "\vcpkg"
+
+$mumble_deps = "qt5-base",
+ "qt5-svg",
+ "qt5-tools",
+ "grpc",
+ "boost-accumulators",
+ "opus",
+ "poco",
+ "libvorbis",
+ "libogg",
+ "libflac",
+ "libsndfile",
+ "libmariadb",
+ "zlib",
+ "zeroc-ice"
+
+$ErrorActionPreference = 'Stop'
+
+function vcpkg_install {
+ Param(
+ [string] $package,
+ [string] $targetTriplet,
+ [switch] $cleanAfterBuild = $false
+ )
+
+ if ($cleanAfterBuild) {
+ ./vcpkg.exe install "$package" --triplet "$targetTriplet" --clean-after-build
+ } else {
+ ./vcpkg.exe install "$package" --triplet "$targetTriplet"
+ }
+
+ if (-not $?) {
+ Write-Error("Failed at installing package $package ($targetTriplet)")
+ }
+}
+
+$prevDir=pwd
+
+try {
+ Write-Host "Setting triplets for $Env:PROCESSOR_ARCHITECTURE"
+ if ($Env:PROCESSOR_ARCHITECTURE -eq "AMD64") {
+ $triplet = "x64-windows-static-md"
+ $xcompile_triplet = "x86-windows-static-md"
+ } else {
+ $triplet = "x86-windows-static-md"
+ }
+
+ Write-Host "Checking for $vcpkgdir..."
+ if (-not (Test-Path $vcpkgdir)) {
+ git clone https://github.com/Microsoft/vcpkg.git $vcpkgdir
+ }
+
+ if (Test-Path $vcpkgdir) {
+ if (-not (Test-Path $vcpkgdir/ports/zeroc-ice)) {
+ Write-Host "Adding ports for ZeroC Ice..."
+ Copy-Item -Path ./helpers/vcpkg/ports/zeroc-ice -Destination $vcpkgdir/ports -Recurse
+ }
+
+ cd $vcpkgdir
+
+ if (-not (Test-Path -LiteralPath $vcpkgdir/vcpkg.exe)) {
+ Write-Host "Installing vcpkg..."
+ ./bootstrap-vcpkg.bat -disableMetrics
+ }
+
+ vcpkg_install -package mdnsresponder -targetTriplet $triplet
+ vcpkg_install -package icu -targetTriplet $triplet
+
+ if ($Env:PROCESSOR_ARCHITECTURE -eq "AMD64") {
+ Write-Host "Installing cross compile packages..."
+ vcpkg_install -package boost-optional:$xcompile_triplet -targetTriplet $xcompile_triplet -cleanAfterBuild
+ }
+
+ Write-Host "Beginning package install..."
+
+ foreach ($dep in $mumble_deps) {
+ Write-Host("---------------------------------------")
+ Write-Host("> Installing Mumble dependency $dep ...")
+ Write-Host("---------------------------------------")
+
+ vcpkg_install -package $dep -targetTriplet $triplet -cleanAfterBuild
+ }
+ }
+} catch {
+ # rethrow
+ throw $_
+} finally {
+ # restore previous directory
+ cd $prevDir
+}
diff --git a/scripts/vcpkg/get_mumble_dependencies.sh b/scripts/vcpkg/get_mumble_dependencies.sh new file mode 100644 index 000000000..e46f0d917 --- /dev/null +++ b/scripts/vcpkg/get_mumble_dependencies.sh @@ -0,0 +1,102 @@ +#!/bin/bash + +# Copyright 2020 The 'mumble-releng-experimental' Authors. All rights reserved. +# Use of this source code is governed by a BSD-style license that +# can be found in the LICENSE file in the source tree or at +# <http://mumble.info/mumble-releng-experimental/LICENSE>. + +# Helper function to check if a certain parameter has been passed to the script +has_option() { + local desiredOption="$1" + shift + for currentOption in "$@"; do + if [[ $currentOption == "$desiredOption" ]]; then + return 0 + fi + done + return 1 +} + +if ! has_option '--auto' "$@" + then + # Make sure the command-prompt stays open if an error is encountered so that the user can read + # the error message before the console closes. + # If you run call this script as part of some automation, you'll want to pass --auto + # to make sure you don't get stuck. + trap "printf '\n\n'; read -p 'ERROR encountered... Press Enter to exit'" ERR +fi + +# On failed command (error code) exit the whole script +set -e +# Treat using unset variables as errors +set -u +# For piped commands on command failure fail entire pipe instead of only the last command being significant +set -o pipefail + +VCPKGDIR=~/vcpkg + +mumble_deps='qt5-base, + qt5-svg, + qt5-tools, + grpc, + boost-accumulators, + opus, + poco, + libvorbis, + libogg, + libflac, + libsndfile, + libmariadb, + zlib, + zeroc-ice' + +# Determine vcpkg triplet from OS https://github.com/Microsoft/vcpkg/blob/master/docs/users/triplets.md +# Available triplets can be printed with `vcpkg help triplet` +case "$OSTYPE" in + msys* ) triplet='x64-windows-static-md' + xcompile_triplet='x86-windows-static-md' + ;; + linux-gnu* ) triplet='x64-linux';; + darwin* ) triplet='x64-osx';; + * ) echo "The OSTYPE is either not defined or unsupported. Aborting...";; +esac + +if [ ! -d "$VCPKGDIR" ] + then + git clone https://github.com/Microsoft/vcpkg.git $VCPKGDIR +fi + +if [ -d "$VCPKGDIR" ] + then + # copy ZeroC Ice port files + cp -R helpers/vcpkg/ports/zeroc-ice $VCPKGDIR/ports + cd $VCPKGDIR + + if [ ! -x $VCPKGDIR/vcpkg ] + then + case "$OSTYPE" in + msys* ) ./bootstrap-vcpkg.bat -disableMetrics + ;; + * ) bash bootstrap-vcpkg.sh -disableMetrics + ;; + esac + fi + + if [ -z "$triplet" ] + then + echo "Triplet type is not defined! Aborting..." + else + if [ $OSTYPE == msys ] + then + # install dns-sd provider + ./vcpkg install mdnsresponder icu --triplet $triplet + ./vcpkg install boost-optional:$xcompile_triplet --clean-after-build + fi + for dep in ${mumble_deps//,/ } + do + ./vcpkg install $dep:$triplet --clean-after-build + done + fi +else + echo "Failed to retrieve the 'vcpkg' repository! Aborting..." +fi |
