diff options
Diffstat (limited to 'DEVELOPMENT.md')
| -rw-r--r-- | DEVELOPMENT.md | 57 |
1 files changed, 52 insertions, 5 deletions
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 79005a9..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 @@ -19,6 +18,7 @@ in spirit rather than by the letter. * Commit messages should be in the imperative voice ("When applied, this commit will: "). * The working language for this repository is english. * External dependencies are only acceptable when necessary and available from package repositories. + * Note that external dependencies make OS portability complicated ### Code style @@ -43,8 +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()`). -# Build pipeline +## Repository layout -# Architecture +* 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 -# Debugging +## Build pipeline + +* The primary build pipeline is `make` + +## 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 + +## 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` |