ChucK : Developer's Guide
current version of this document: http://chuck.cs.princeton.edu/doc/develop/
join the ChucK
related: the ChucK Tutorial | Programmer's Guide | ChucK
This guide describes the software architecture the ChucK compiler and
virtual machine, as well as design and implementation ChucK, and outlines
how it can be modified, improved, and extended, including:
- modifying the source code
- writing chuck external plug-ins (.ckx files) from C/C++
- using ChucK implementation as a framework/reference for new real-time audio/graphics/multimedia programming languages and systems.
ChucK implementation consists of:
The ChucK compiler and virtual machine runs in the same address space. (allowing for code to
be added, modified, and removed during runtime)
- a full COMPILER for ChucK, an interpreted/byte-code procedural audio/graphics
- a VIRTUAL MACHINE that internally manages user-level shreds (ChucK threads). A virtual
instruction set is defined for ChucK.
- a audio engine and set of audio unit generator (signal processing units)
- a real-time, on-the-fly programmable audio/multimedia system.
(by source module):
- chuck_main.cpp: the entry point for 'chuck', which is both the
compiler and the VM. this module accepts various options and multiple
concurrent source files to run in parallel in the VM. this module
invokes the following.
- chuck.lex: lexer specification - the lexer is generated by
- chuck.y: ChucK grammar specification - the parser is
generated by yacc/bison.
- chuck_absyn.(h|c): abstract syntax for the ChucK parse tree.
For each source file, a corresponding syntax tree is constructed in the
parser and passed (by chuck_main) to the type-checker.
- chuck_scan.(h|cpp): ChucK scanner. traverses the
abstract syntax tree in several passes, and resolves types.
- chuck_type.(h|cpp): ChucK type-checker. traverses the
abstract syntax tree, and assigns and validates types for each part of
the tree. If a semantic error is encountered, a message is generated and
returned. if a program type-checks, the output is returned to be passed
to the code emitter.
- chuck_emit.(h|cpp): ChucK byte-code emitter. if a program
has made it this far, then it is type-checked. the emitter traversed the
type-checked syntax tree, and emits virtual ChucK VM instructions for
each file into a shred (ChucK thread). The instruction set is defined in
- chuck_instr.(h|cpp): ChucK VM instruction set. this contains
the virtual instructions for the VM. arithmetic, logical, memory,
timing, and audio-specific instructions are all part of the instruction
- chuck_vm.(h|cpp): ChucK VM implementation, including the
ChucK 'shreduler', and data/functions for manipulating ChucK 'shreds'.
The VM is a strict interpreter over the ChucK instructions emitted in
earlier stages. It also cooperates with the ChucK shreduler for
shreduling the concurrent shreds, which are user-level constructs.
Additionally, the VM also coordinates with a real-time native audio
engine and a native graphics engine (currently, this is a wrapper for a
subset of the OpenGL API, available in ChucK, with all the timing
benefits of the language).
- chuck_oo.(h|cpp): base classes and objects for the ChucK runtime
- chuck_lang.(h|cpp): base classes and objects for the ChucK runtime
language interface implementation
- digitalio_rtaudio.(h|cpp): abstraction layer to the real-time
audio interface provided by the system. ChucK works over OS X
(CoreAudio), Linux (ALSA/OSS), and Windows/Cygwin (DirectSound).
Currently, the implementation uses an audio library by Gary Scavone,
called RtAudio, also open source.
- rtaudio.(h|cpp): Gary Scavone's audio library code for
real-time audio I/O.
- chuck_dl.(h|cpp): ChucK Dynamic Linking module. Externals
(ckx files) can be loaded dynamically and invoked from the language.
This allows for algorithms implemented in other languages (C/C++ etc.) to
be used from ChucK. This includes a interface-querying mechanism
for determining types.
- chuck_ugen.(h|cpp): interface for audio processing units
(called unit generators), which include oscillators, filters, envelopes,
noise generators, etc... this module defines data structures of unit
generators and how to import them into the type system.
- ugen_*.(h|cpp): internal unit generator libraries (statically
- ulib_*.(h|cpp): standard chuck library (stdlib, math etc...)