Merge PR #5500: DOCS: General intro to Mumble's source code

2 files changed, 161 insertions, 1 deletions

diff --git a/README.md b/README.md
index b26c07858..54464a8ff 100644
--- a/README.md
+++ b/README.md
@@ -29,7 +29,10 @@ The documentation of the project can be found on the [wiki](https://wiki.mumble.
 
 ## Contributing
 
-We always welcome contributions to the project. If you have code that you would like to contribute, please go ahead and create a PR. While doing so, please try to make sure that you follow our [commit guidelines](COMMIT_GUIDELINES.md).
+We always welcome contributions to the project. If you have code that you would like to contribute, please go ahead and create a PR. While doing so,
+please try to make sure that you follow our [commit guidelines](COMMIT_GUIDELINES.md).
+
+If you are new to the Mumble project, you may want to check out the general [introduction to the Mumble source code](docs/dev/TheMumbleSourceCode.md).
 
 ### Translating
 
diff --git a/docs/dev/TheMumbleSourceCode.md b/docs/dev/TheMumbleSourceCode.md
new file mode 100644
index 000000000..204c88442
--- /dev/null
+++ b/docs/dev/TheMumbleSourceCode.md
@@ -0,0 +1,157 @@
+# 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
+│   ├── murmur_grpcwrapper_protoc_plugin
+│   └── 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.
+