---
title: "Debugging Alloy Apps with xsbug"
canonical_url: https://developer.repebble.com/guides/debugging/debugging-alloy-with-xsbug/
last_updated: 2026-06-24
sdk_version: 4.43
---
# Debugging Alloy Apps with xsbug

Source: https://developer.repebble.com/guides/debugging/debugging-alloy-with-xsbug/

Alloy apps run on Moddable's XS JavaScript engine, which ships with a graphical source-level debugger called **xsbug**. With xsbug you can set breakpoints, step through JavaScript, inspect variables, and watch `console.log` / `trace` output while your app runs on a watch or in the emulator.

> **Platform Support** : Alloy and xsbug debugging are available on Emery (Pebble Time 2) and Gabbro (Pebble Round 2). This requires `pebble-tool` 5.0.38 or later.

## Building a Debug Build

xsbug can only attach to an app that was built in debug mode. Build your project with the `--debug` flag:

```
$ pebble build --debug
```

A debug build:

- compiles your C code without optimizations (`-O0`) for easier stepping;
- defines `PBL_DEBUG`, which the Alloy entry point (`src/c/mdbl.c`) uses to set `kModdableCreationFlagDebug` and enable the xsbug connection; and
- produces a separate `<app>_debug.pbw` bundle, so your debug and release builds can coexist.

> **Note** : A debug build is larger and runs more slowly than a release build, and may not fit on memory-constrained apps. Build without `--debug` for normal testing and release.

## Launching the Debugger

When you install a `--debug` build, the Pebble tool automatically launches xsbug, opens your `src/embeddedjs` folder so breakpoints map to your source, and bridges the JavaScript debugger over the connection _before_ the app boots - so the debugger is attached as soon as your code starts running:

```
$ pebble install --emulator emery
Launching xsbug JavaScript debugger...
```

The same happens for `pebble logs`, which also prefers the `_debug` bundle when one is present.

xsbug ships in the active SDK's `moddable-tools` directory and is started for you. If the tool can't find it, it prints a warning - launch xsbug manually and re-run the install so the debugger can connect.

## Using xsbug

Once connected, xsbug shows your running app. From its interface you can:

- set and clear **breakpoints** by clicking in the gutter of a source file;
- **step** over, into, and out of functions, and continue execution;
- inspect the **call stack** , **local variables** , and **global** state; and
- view **`console.log`** and **`trace`** output in the messages pane.

For a full tour of the debugger, see the [Moddable xsbug documentation](https://www.moddable.com/documentation/xs/xsbug).

## See Also

- [_Debugging with App Logs_](https://developer.repebble.com/guides/debugging/debugging-with-app-logs.md) - viewing log output
- [_Getting Started with Alloy_](https://developer.repebble.com/guides/alloy/getting-started.md) - getting started with Alloy