ChucK : Developer's Guide

version: 1.5.x.x (numchucks)


current version of this document: http://chuck.cs.princeton.edu/doc/develop/

join the ChucK Developer Mailng List

related: the ChucK Tutorial | Programmer's Guide | ChucK Home

Introduction:

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:
  1. modifying the source code
  2. writing chuck external plug-ins (.ckx files) from C/C++
  3. using ChucK implementation as a framework/reference for new real-time audio/graphics/multimedia programming languages and systems.

Overview:
ChucK implementation consists of:
  1. a full COMPILER for ChucK, an interpreted/byte-code procedural audio/graphics programming language
  2. a VIRTUAL MACHINE that internally manages user-level shreds (ChucK threads). A virtual instruction set is defined for ChucK.
  3. a audio engine and set of audio unit generator (signal processing units)
  4. a real-time, on-the-fly programmable audio/multimedia system.
The ChucK compiler and virtual machine runs in the same address space. (allowing for code to be added, modified, and removed during runtime)

Architecture (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 lex/flex.

  • 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.

  • 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 set.

  • 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 VM implementation

  • 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 linked)

  • ulib_*.(h|cpp): standard chuck library (stdlib, math etc...)


chuck | soundlab | cs | music | ccrma