diff options
author | Robert Adam <dev@robert-adam.de> | 2022-01-21 23:02:43 +0300 |
---|---|---|
committer | Robert Adam <dev@robert-adam.de> | 2022-01-23 17:14:03 +0300 |
commit | f07f48fce972d1ced1f27c20b617f02b705327e2 (patch) | |
tree | ccdb1f42a58788e36699ddc844db9ea30ab2097f | |
parent | 481fb2266948f0a5b27eec7d554bb75ecf88610f (diff) |
DOCS: General intro to Mumble's source code
-rw-r--r-- | README.md | 5 | ||||
-rw-r--r-- | docs/dev/TheMumbleSourceCode.md | 157 |
2 files changed, 161 insertions, 1 deletions
@@ -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. + |