Install and run

You do not need to install anything to try the language — the playground runs the real compiler, and every runnable block on this site plays in the page. This page is for running it locally.

Build the compiler#

Pole needs CMake 3.28 or newer and LLVM 21 or 22. The version is pinned rather than "whatever is installed": the compiler uses LLVM's C++ API, which is not stable across major versions, and -Werror turns one deprecation into a build failure.

The range is not arbitrary. LLVM 22 is the first release with no prebuilt Intel macOS binary anywhere, so a universal build can only link against 21 or older without building LLVM from source. POLE_LLVM_PREFIX points at a versioned formula (llvm@21) rather than one that floats, because a routine brew upgrade would otherwise move Pole onto an untested LLVM.

cmake -S tools/pole -B tools/pole/build
cmake --build tools/pole/build -j8

That produces tools/pole/build/polec, which is the whole toolchain — there is no second binary, no runtime to install, and no SDK.

Keep the working directory consistent#

The build commands above run from the repository root. The commands below use paths relative to the Pole directory, so switch into it once:

cd tools/pole

From there, ./build/polec is the compiler and examples/ is the example folder. If you get a “file not found” error, check your working directory before changing the command.

Render a file#

The default output is a 32-bit float WAV:

./build/polec examples/sine.pole --emit=wav --out=/tmp/sine.wav --frames=4800

Float rather than 16-bit, and deliberately: a filter that overshoots past full scale should show that in the file rather than be clipped into looking broken.

--frames sets the length in samples and --rate the sample rate. Feed the patch something with --input:

./build/polec examples/filter.pole --input=saw --emit=wav --out=/tmp/filtered.wav

saw, sine, silence, impulse, notes and chords are built in, and --input-wav=<path> uses a file.

Play it live#

./build/polec examples/poly_simple.pole --play

Letter keys sound notes; q quits. polec also publishes itself as a MIDI destination called polec, so any application can play it.

Live audio output and MIDI input are macOS only today — they are CoreAudio and CoreMIDI behind a platform guard, with stubs elsewhere that say so rather than failing to build. Compiling, JIT-ing and rendering a WAV work wherever the compiler builds; see platforms for what has actually been run where.

Look at what it produced#

polec will show you its own working:

./build/polec examples/synth.pole --params          # the controls this patch declares
./build/polec examples/synth.pole --emit=ir         # the intermediate representation
./build/polec examples/synth.pole --vec-report      # what LLVM vectorised, and why not the rest

The full flag list is on the command line page, which is generated from polec --help rather than transcribed.

Load a wavetable or a sample#

An external array is a buffer the host owns; the compiler never sees its contents. Fill one from a WAV:

./build/polec examples/poly_synth.pole --data=wave=examples/tables/vocal.wav --play

The examples#

tools/pole/examples/ holds thirty patches, from a four-line gain to an eight-voice wavetable synth. The cookbook develops teaching versions of these ideas, with explanations and some adapted programs. To run a chapter exactly as shown, save its complete code block as a .pole file.