diff options
| -rw-r--r-- | DEVELOPMENT.md | 47 |
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` |