Skip to content

Commit

Permalink
Update development notes
Browse files Browse the repository at this point in the history
  • Loading branch information
cbdevnet committed Jun 29, 2021
1 parent 979ca16 commit 12142b4
Showing 1 changed file with 41 additions and 6 deletions.
47 changes: 41 additions & 6 deletions 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

Expand Down Expand Up @@ -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`

0 comments on commit 12142b4

Please sign in to comment.