mumble/docs/dev/TheMumbleSourceCode.md

# Introduction to the Mumble source code

Hello fellow programmer. If you are reading this specific piece of documentation, you are probably about to (or consider to) make a contribution to
Mumble. Or maybe you just want to patch something for your own purpose. In any case: this is aimed at people who are unfamiliar with the general
layout and concepts of the Mumble source code.

While this documentation is aimed at providing a good entry point for picking up development with the Mumble source code, it naturally can't cover it
exhaustively. Furthermore, just as any documentation, it is prone to becoming stale at some point. Therefore the golden rule is: If you don't
understand something or have a question otherwise, feel free to ask. We will be happy to help!

For all development-related questions, feel free to join our public Matrix development channel at https://matrix.to/#/#mumble-dev:matrix.org. Creating
an issue with your question here on GitHub is also fine.


## Source tree layout

When cloning the repo, the source tree should look something like this:
```
<repo root>
├── 3rdparty
├── 3rdPartyLicenses
├── cmake
│   └── FindModules
├── docs
│   ├── additional-readmes
│   ├── dev
│   └── media
├── g15helper
├── helpers
├── icons
├── installer
├── macx
├── man
├── overlay
├── overlay_gl
├── overlay_winx64
├── plugins
├── samples
├── screenshots
├── scripts
├── src
│   ├── crypto
│   ├── mumble
│   ├── mumble_exe
│   ├── murmur
│   └── tests
└── themes
    └── Default
```

The `3rdparty*` directories contain external libraries that we make use of (generally as git submodules) and their corresponding licenses. Unless you
are planning on adding a new external library into the code base, these directories are probably of virtual zero interest for you. Unless you forget
to initialize the git submodules before attempting to compile Mumble, in which case you will experience build errors. Thus, execute `git submodule
update --init` and forget about these directories.

The `cmake` directory contains a few cmake scripts that are needed to make the build work in the way it does. Unless you are trying to debug a build
issue (or extend the build system), you can probably ignore this directory.

Obviously you are already aware of the `docs` directory (you are reading this file, which lives in there). It contains mostly development related
documentation. The more extended user documentation is available on our website or (depending on how far we have gotten to migrate it yet) on our
wiki. The most relevant documentation for you is probably within the `dev` (development) subdirectory.

`g15helper` and `helper` will generally not concern you. We could probably find a better place for these, but at the moment they are where they are…

`icons` is pretty much what you would expect, given its name. The same can be said about `installer` which contains all files related to building our
Windows installer. If you want to tinker with that, you have to know that we are using [WixSharp](https://github.com/oleg-shilo/wixsharp) for managing
it.

`macx` contains some macOS specific files (mostly overlay-related and scripts used for release mangement), whereas `man` contains the man entries
(used on Windows) for the Mumble client and server.

The `overlay*` directories contain the implementation for the Mumble overlay for the various platforms. We will not go into detail for those here, as
they aren't really part of the main Mumble source (I mean they are, but yet they aren't).

If you are into plugin development or you want to mess with existing plugins, the `plugins` directory is where you want to look. It contains the
implementation of all plugins shipped with Mumble by default and also the plugin headers needed to create new ones. For further documentation on that,
you are referred to the dedicated plugin documentation within the `docs/dev` directory.

`samples` and `screenshots` are self-describing and generally of very little interest when dealing with the Mumble source code as such. `scripts` is
mainly occupied by various scripts used throughout various tasks surrounding Mumble. In addition to that, it also contains a few things such as a
default configuration file for the Mumble server.

Your main focus should lie on the `src` directory as this is where the bulk of Mumble's source code is living. Directly in `src/` are shared sources
that are used by the Mumble client as well as by the server that live in `src/mumble` and `src/murmur` respectively. The `src/mumble_exe` direcrtory
contains code for the Windows-specific executable. In order to make sense of that you have to know that on Windows we are currently using a bit of an
odd system: The main application is packaged inside a DLL that is loaded by the main executable. This is a historic artifact and currently only
serves to create problems every now and then. In any case though, the mentioned "main executable" whose sole job is loading of that DLL lives in
`mumble_exe`. Generally you don't have to worry about it. The remaining directories within `src` should be somewhat self-explanatory.

The `themes` directory contains all built-in themes that are currently shipped with Mumble. At this point there is only one theme available: the
`Default` theme (note that it contains the Lite and the Dark theme variant). If you want to customize any kind of icons within Mumble, this is the
place to check out. It contains its own documentation, so you are encouraged to have a read.


## Important files

Now that we have established our general bearings, it is time to get a little bit more specific about the individual files in the source tree
(`src/*`).

To begin with a general note: In Mumble the name of the header file in which a class and its function is declared, is not necessarily a guarantee that
the implementation of that function is also in the source file with the corresponding name. So it can happen that the file `MyClass.h` defines a class
`MyClass` that declares a function `X`. That function may not end up being implemented in `MyClass.cpp`. Classes that make extensive use of this
pattern are the `Server` and `MainWindow` class respectively. If the header doesn't mention where the given set of functions is implemented, your best
chance is to search the source files in the same directory for a matching implementation (in almost all cases, the implementation lives in a source
file within the same directory as the header in question).


### Client

First off: all the `*.ts` are used for localizations (translations) are are handled by external services. Thus, you should not modify them by hand
as your changes would likely be overwritten by said service.

- `main.cpp`: This contains the main entry point into the client (the "main" function) in which all command-line arguments are processed and a bunch
  of objects are instantiated and prepared for further use. The main purpose (as far as most developers are concerned) is the instantiation of the
  `MumbleApplication` which mostly is just a `QApplication`. That means that from this point on the program is mainly event-driven.
- `MainWindow.cpp`: This can be pretty much be considered the heart of the Mumble client. It is responsible for managing the main Mumble UI and also
  for coordinating all sorts of events that are received and sent. If you are tracing down some functionality, chances are high that the `MainWindow`
  class is involved in it in one way or another.
- `UserModel.cpp`: This class is responsible for managing the in-memory representation of the channel and user tree. All user and channel objects on
  the client are created here.
- `Messages.cpp`: This class implements all Protobuf message handling that is performed on the client-side. Technically all these functions belong to
  the `MainWindow` class, but their implementation is separated into this dedicated source file.
- `ServerHandler.cpp`: This class is responsible for managing a connection to a given server. It handles the immediate network connection to the
  server and makes sure that all messages are sent and received in the appropriate thread. If you need to send any request to the server, the server
  handler is the one to perform the request for you.
- `AudioInput.cpp`, `AudioOutput.cpp`: These classes implement the general audio input and output handling. The actual interaction with the
  system-specific audio backend (e.g. PulseAudio, CoreAudio or WASAPI) is handled by dedicated sub-classes which are implemented in the files named
  after the supported audio backend (e.g. `PulseAudio.cpp`, `CoreAudio.mm` or `WASAPI.cpp`). These typically contain an implementation for the input
  _and_ output handling.
- `PluginManager.cpp`: Everything that is related to loading and running plugins within Mumble, is handled by the `PluginManager` class.
- `API_v*`: These are the various implementations of the plugin API functions. These are the functions plugins may call in order to interact with
  Mumble.
- `Global.cpp`: The `Global` class is a singleton accessed via `Global::get()` and it holds a variety of shared data used throughout the client.

For many UI elements, we use `.ui` files which are XML-files that describe the UI elements in a way that is understood by
[Qt Designer](https://doc.qt.io/qt-5/qtdesigner-manual.html). With this tool, you can edit the elements in a WYSIWYG fashion (at least for the most
part). In any case, it is a great tool, when you are trying to figure out what will happen once you click a certain button in a given UI element. Just
open the element in Qt Designer, check the button's name and search for that in the corresponding `.cpp` implementation. Note that we are using
implicit signal-connecting which is based on a special naming scheme of slots in a given UI class (e.g. `on_xy_actived` where `xy` is the name of the
corresponding UI element).


### Server

When working with the server, it is useful to know that the Mumble server has the concept of "virtual servers" where one running instance of the
Mumble server program, may simultaneously serve multiple Mumble servers (aka: they will show up as separate servers in a client's server list).

- `main.cpp`: This file (again) contains the main entry point into the server code (the "main" function)
- `Meta.cpp`: The `Meta` class is responsible for managing the different virtual servers. That includes booting them.
- `Messages.cpp`: Just as for the client, this file contains the implementation of all Protobuf message handling.
- `Server.cpp`: This is the heart of every virtual server instance. It contains a bunch of auxiliary functionality and completely handles the UDP
  audio thread.
- `ServerDB.cpp`: As the name suggests, this file implements database access of all kinds.

If you want to mess with or extend the server's Ice RPC framework, check out the dedicated documentation for that.