Getting Started with Bintracker Development
Prerequisites
As Bintracker is written in the Scheme programming language, you will need some understanding of Scheme or another Lisp-like language. Although Scheme's syntax is very different from other programming languages, it is very easy to learn. Even a basic understanding is enough to start running some simple code in Bintracker's REPL or tweaking configs/config.scm.
If you plan on writing more than a few lines of code for Bintracker, you should consider using an editor with a structured editing mode. Vim, Atom, and VS Code all support something akin to Emacs' paredit.
Reading the Source
If this is your first time working with Scheme or another language from the Lisp family, reading the Bintracker source code can seem a bit intimidating. This section gives some general hints on how to find your way around in the Bintracker source.
-
There are no header files, as you might be used to when coming from C or C++. However, the compiler generates various header-like files during compilation. Any
.scm
files in the source tree whose name contains more than one dot are auto-generated, you usually can ignore those. -
There is no explicit
main
. The top level source file isbintracker.scm
, which recursively depends on all other files in the source tree. -
Bintracker is split into several core components.
-
Read source files from the bottom. When writing Scheme code, the most high-level abstractions often end up near the bottom of the file.
-
Namespace management: In Chicken Scheme, Modules are the main means of managing namespaces. Each source file in the main source directory and the libmdal sub-directory contains a single module.
-
There is a hierarchy of modules:
libmdal/mdal.scm
is the meta-module of all libmdal modules, andbintracker-core.scm
is the top-level meta-module of Bintracker, which re-exports all bindings that will be visible to user code at runtime. To find out what a given module depends on, look for(import ...)
statements near the top of an.scm
file. If you don't find a module mentioned in animport
statement in the source tree, then it is probably a 3rd party extension. -
After startup, Bintracker is controlled by the Tcl/Tk interpreter. There is no Tcl code involved, however. Bintracker uses pstk to interface with Tcl/Tk. The relevant GUI code resides in
bt-gui.scm
. -
While libmdal is mostly purely functional, other parts of Bintracker are not. Most GUI abstractions use the coops object orientation extension, and closures are frequently used to wrap state. The
bt-state
module handles global state in Bintracker.
Components
Core Components
bintracker-core
bintracker-core
comprises the main application.
libmdal
Libmdal is an implementation of the Music Data Abstraction Language. It covers all parts related to the handling of music modules. Libmdal is a compiler generator: Given a MDEF engine definition, it generates a compiler that can transform a suitable MMOD into binary output.
Schemta
Schemta is Bintracker's assembler. It is integrated into libmdal but can also be built as a stand-alone executable.
Dependencies
PEG parsing, comparse/parsec object-orientation: coops multithreading model: srfi-18
In addition to the core and the libmdal API, the following procedures and APIs are available:
- All Scheme primitives and procedures defined in the R5RS standard.
- The SRFI-1 and SRFI-13 extensions (lists resp. strings).
- The bitwise Chicken Scheme module.
- The pstk Chicken Scheme extension, which offers an interface to the Tk widget toolkit, and the Tcl programming language.
Useful Resources
Scheme Language
-
R5RS, the language reference of the Scheme dialect used in Bintracker.
-
The Little Schemer. A very good starting book on Scheme.
-
Structure and Interpretation of Computer Programs, aka SICP. This is the "bible" of Scheme programming. Highly recommended if you want to do some serious hacking on Bintracker.
-
The Most Beautiful Program Ever Written, a talk by William Byrd. Watch if you don't mind getting hooked on Scheme.
Chicken Scheme
- Manual
- Wiki
- Chicken API, a search engine for the official Chicken Scheme documentation. Use this as reference for all Scheme and Chicken-related topics.
Tcl/Tk
- Tk Command Reference
- Tcl Command Reference and delevop GUI extensions.
- The pstk git repository contains an extensive but somewhat outdated manual of pstk.
Other
- Bintracker accesses the MAME Lua Scripting Engine. The online documentation isn' great but the source code documents the Lua engine quite well.