aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
-rw-r--r--DEVELOPMENT.md47
1 files changed, 41 insertions, 6 deletions
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 3fc2268..a2ec6a2 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -1,8 +1,7 @@
# MIDIMonster development guide
This document serves as a reference for contributors interested in the low-level implementation
-of the MIDIMonster. It is currently a work in progress and will be extended as problems come
-up and need solving ;)
+of the MIDIMonster. It will be extended as problems come up and need solving ;)
## Basics
@@ -44,19 +43,55 @@ in spirit rather than by the letter.
* Avoid `atoi()`/`itoa()`, use `strto[u]l[l]()` and `snprintf()`
* Avoid unsafe functions without explicit bounds parameters (eg. `strcat()`).
-# Repository layout
+## Repository layout
* Keep the root directory as clean as possible
* Files that are not related directly to the MIDIMonster implementation go into the `assets/` directory
* Prefer vendor-neutral names for configuration files where necessary
-# Build pipeline
+## Build pipeline
* The primary build pipeline is `make`
-# Architecture
+## Architecture
+* Strive to make backends platform-portable
+ * If that is not possible, try to keep the backend configuration compatible to other backends implementing the same protocol
* If there is significant potential for sharing functionality between backends, consider implementing it in `libmmbackend`
+* Place a premium on keeping the MIDIMonster a lightweight tool in terms of installed dependencies and core functionality
+ * If possible, prefer a local implementation to one which requires additional (dynamic) dependencies
-# Debugging
+## Language & Communication
+* All visible communication (ie. error messages, debug messages) should be complete, correct english sentences
+* Strive for each output to have a concrete benefit or information to the reader
+ * Corollary: If nothing happens, don't send output
+ * Debug messages are somewhat exempt from this guideline
+* For error messages, give enough context to reasonably allow the user to either track down the problem or report a meaningful issue
+
+# Packaging
+
+Packaging the MIDIMonster for release in distributions is an important task. It facilitates easy access to
+the MIDIMonster functionality to a wide audience. This section is not strictly relevant for development, but touches
+on some of the same principles.
+
+As the MIDIMonster is a tool designed for interfacing between several different protocols, applications and
+other tools, to use "all" functionality of the MIDIMonster would imply installing additional software the user
+might not actually need. This runs counter to our goal of staying a lightweight tool for translation and control.
+
+The recommended way to package the MIDIMonster for binary distribution would be to split the build artifacts into
+multiple packages, separating out the heavier dependencies into separately installable units. If that is not an option,
+marking external dependencies of backends as `optional` or `recommended` should be preferred to having them required
+to be installed.
+
+Some backends have been marked optional in the repository and are only built when using `make full`.
+
+The recommended grouping into packaging units is as follows (without regard to platform compatibility, which
+may further impact the grouping):
+
+* Package `midimonster`: Core, Backends `evdev`, `artnet`, `osc`, `loopback`, `sacn`, `maweb`, `openpixelcontrol`, `rtpmidi`, `visca`, `mqtt`
+ * External dependencies: `libevdev`, `openssl`
+* Package `midimonster-programming`: Backends `lua`, `python`
+ * External dependencies: `liblua`, `python3`
+* Package `midimonster-media`: `midi`, `jack`, `ola`
+ * External dependencies: `libasound2`, `libjack-jackd2`, `libola`