Development

Requirements

Python 3 with numpy and Pillow: they generate the sounds, font, logo and website.
Docker: builds and runs the tests (GCC) and the emulator (Emscripten). No local compiler needed.

On Windows the Python command is py -3; on Linux and macOS, python3.

Commands

py -3 tools/build.py assets   # font, kits, waves, factory loops and logo (core/gen/)
py -3 tools/build.py test     # builds and runs the PC tests; screenshots in assets/screens/
py -3 tools/build.py web      # emulator: web/bm.js
py -3 tools/build.py site     # website documentation pages: web/docs/ and web/en/docs/
py -3 tools/build.py all      # all of the above

The tests (tests/test_core.c) go through the firmware the way a person would: boot, press buttons, record, save, power off and on again. They also check sequencer timing, the screen budget and that the flash is never written while playing.

Layout

core/        the firmware, C99 with no hardware: audio, sequencer, interface and storage
core/gen/    data generated by tools/: font, kits, waves, loops and logo
hal/         hardware layers: sim (PC and web), web (WebAssembly) and fm1 (port)
web/         website: home page, emulator (emulador.html) and docs (docs/, en/)
docs/        manual, spec, design and guides (source of the website); docs/en/ in English
tests/       automated tests
tools/       generators and build
assets/      logo, screenshots, factory loops

Core rules

core/ knows nothing about the hardware: everything goes through the platform (bm_platform) each hal/ provides.
No malloc. The FM-1 has 96 KiB of RAM; the budget is in MEMORIA.md (Spanish).
Audio runs in its own context: the interface only talks to it through the command queue.
The flash is only written with the transport stopped: writing pauses the audio.

Sounds and factory loops

Kits and waves are synthesized in tools/gen_assets.py.
Factory loops are defined in assets/loops/loops.json and synthesized in tools/gen_loops.py.
To test with your own audio, create assets/loops/loops.local.json (it is in .gitignore) and generate with:

py -3 tools/gen_loops.py --local

A build made with --local must not be published: neither web/bm.js nor binaries. Before pushing, generate again without --local.

The website

web/index.html is the Spanish home page, web/en/index.html the English one, and web/emulador.html the emulator (both languages).
The pages in web/docs/ and web/en/docs/ are generated from the .md files by tools/gen_site.py: edit the .md, not the HTML. English sources live in docs/en/.
GitHub Pages publishes the web/ folder through .github/workflows/pages.yml.

Branches

Branch	For
`dev`	Day-to-day work. Pull requests go here
`qa`	What is about to be released, under test: emulator and, once it exists, the FM-1
`main`	What is released. Every version comes from here and the website is published from here

Changes move one way only: dev › qa › main.

Continuous integration

.github/workflows/ci.yml runs the tests on every push and every pull request.

Versions

The version number lives in core/bm_config.h (BM_VERSION_STR) and in the changelog.
Every public version is a vX.Y.Z tag with its source code. The GPL requires that any published binary comes with its corresponding source.

This page is generated from docs/en/DEVELOPMENT.md. Spotted a mistake? Edit the file and send a pull request.