auxtools is a Rust-based successor to the extools project.
Currently, it implements some of the features such as the debug server, but is planned to supplant most functionality (maptick, etc.).
Code Coverage - A tool to generate cobertura code coverage XML reports for a codebase. Note that, due to a BYOND issue it requires some additional work to have properly un-mangled file names in the report.
Debug Server - Debug DM worlds from VS Code or the command line, with experimental hot reload.
The debugger supports line, function, instruction and data breakpoints; conditional breakpoints and logpoints; runtime error breakpoints; line and instruction stepping; sleeping proc stacks; variable inspection and assignment; expression and proc-body evaluation; and disassembly. A journal records runtime errors, reloads, output and reboots.
No changes to the world's source are required. auxtools launches a compiled .dmb in DreamDaemon (dd.exe on Windows), windowed DreamDaemon or DreamSeeker with the debug library loaded. Build the world with your project's usual tools. After world.Reboot(), the launcher reconnects and restores breakpoints and reloads.
Multiple debuggers can connect to the same world. Each session has independent breakpoints and runtime error settings. Pausing stops the world for every session; any session can resume it.
Use auxtools list to find running worlds. Worlds using an incompatible debugger protocol are listed but cannot be attached to.
For VS Code, install the extension and press F5 in a workspace containing a built world. See the extension README for configuration and debugging features.
For command-line use, run auxtools help COMMAND for options, behavior, output and exit codes. --pid PID selects a world when several are running. Requests time out after 30 seconds by default, with exit code 2. Use --response-timeout SECONDS to change the limit. Results go to stdout and diagnostics to stderr. --json returns a JSON value, or JSON Lines for log and trace.
auxtools launch tgstation.dmb --detach
auxtools wait pause --break code/game/foo.dm:120
auxtools vars
auxtools eval 'src.health'
auxtools step-over
auxtools continue
auxtools trace /mob/proc/Life --by caller --for 5
auxtools log --runtimes --follow
auxtools wait reload
auxtools reboot
auxtools stopExit codes are 0 for success, 1 for failure, 2 for timeout, 3 if the world exits or reboots before completion, and 4 if a world launched in the foreground exits unsuccessfully.
Editors use auxtools dap as the debug adapter.
The launcher watches source files and reloads changes when they are saved. Hot reload is enabled by default for launched worlds, including Run Without Debugging. Supply the same defines used to build the .dmb.
Hot reload supports proc bodies, proc and verb additions, proc removals, new types and variables, variable types and defaults, static, const and tmp declarations, parameters, set statements and parent types. Changes to proc declarations, such as converting a proc to a verb, require a rebuild.
Existing calls finish on their original bytecode. Existing instances retain their verbs and built-in values; computed defaults apply to new instances. Changed world settings and client settings stored in the world record, such as client.control_freak, take effect after restart.
After reboot, the launcher restores reloads before the world runs its code. Reloads introducing resource files absent from the build wait until world/New, so map atoms run the built code.
Running globals and statics keep their values when their initializers change. After reboot, updated initializers run once before map creation. Existing initializers keep the build's order; additions follow their preceding var in dmasm's order, which does not yet match DreamMaker exactly. New statics in deferred reloads initialize at world/New.
Saving an icon, sound or other referenced resource reloads it, including files found through FILE_DIR. Existing appearances redraw with the new file; recompiled code and defaults use it too. Stored values and generated assets keep their old resources. Shared resources need a rebuild to separate them. After reboot, resource edits are restored at world/New. Reloaded FILE_DIR resources use paths relative to the world directory rather than their source spelling. See the extension documentation for details and limits.
Saving the .dmf skin updates the interface sent at login. Connected clients need to reconnect; auxtools reconnect requests this, or reboots DreamSeeker-hosted worlds.
Changes to client/script text also apply at login. Resource-file scripts and included .dms files require a rebuild.
Proc-body edits can use a single-file parse. Other edits trigger a full project parse. See the extension documentation for reload limits and the hot reload tests for supported cases.
Windows and Linux: 515.1637–515.1647 and 516.1648–516.1689.
Symbol patterns were checked throughout these ranges. Newer builds are attempted but may fail initialization if a pattern no longer matches. Older builds and unsupported major versions are rejected with a version error. If debugger initialization fails, the world keeps running. The launcher, VS Code and CLI report the reason; auxtools stop can terminate the world.
The patterns use byond-scan and are stored in auxtools/src/symbols/.
CI tests the debugger, hot reload and CLI on 515.1637, 515.1647, 516.1659, 516.1685 and 516.1689. The integration suites cover the debug server, source reloads, launcher lifecycle, CLI output and DAP behavior. Linux tests run on Ubuntu 22.04; Windows tests run in dd.exe on Windows Server 2022 and under Wine.
The VS Code extension has separate integration coverage on Linux 516.1688 using a harness outside this repository. It has no automated Windows coverage. DreamSeeker and windowed DreamDaemon were checked manually with the first part
of launcher_test before the CLI was added; they are outside these automated runs. The auxtest suite and coverage reports were last checked on 516.1687.
These instructions were taken directly from tgstation's rust-g documentation.
The Rust compiler:
-
Install the Rust compiler's dependencies (primarily the system linker):
- Ubuntu:
sudo apt-get install gcc-multilib - Windows (MSVC): Build Tools for Visual Studio 2017
- Ubuntu:
-
Use the Rust installer, or another Rust installation method, or run the following:
curl https://sh.rustup.rs -sSfo rustup-init.sh chmod +x rustup-init.sh ./rustup-init.sh
-
Add the 32-bit compilation target:
# Clone the `auxtools` repository to a directory of your choice git clone https://github.com/auxtools/auxtools # in the `auxtools` directory... cd auxtools # Linux rustup target add i686-unknown-linux-gnu # Windows rustup target add i686-pc-windows-msvc
System libraries:
-
Ubuntu and Debian users run:
sudo dpkg --add-architecture i386 sudo apt-get update sudo apt-get install build-essential g++-multilib libc6-i386 libstdc++6:i386
-
Other Linux distributions install the appropriate 32-bit development and 32-bit runtime packages.
Cargo downloads and builds Rust dependencies. The lockfile pins two git dependencies: auxtools/dmasm for proc compilation and hot reload, and auxtools/SpacemanDMM for parser fixes.
Build the workspace in release mode:
Linux:
cargo build --workspace --release --target i686-unknown-linux-gnuOutputs in target/i686-unknown-linux-gnu/release: libauxtools.so, libdebug_server.so, libauxcov.so, auxtools.
Windows:
cargo build --workspace --release --target i686-pc-windows-msvcOutputs in target/i686-pc-windows-msvc/release: auxtools.dll, debug_server.dll, auxcov.dll, auxtools.exe.
To cross-compile Windows builds on Linux, install clang 19 or newer, lld and LLVM, then fetch the SDK (about 800 MB):
ci/msvc/fetch-sdk.sh ~/.cache/msvc-sdk
export MSVC_SDK=~/.cache/msvc-sdk
. ci/msvc/env.sh
cargo build --workspace --release --target i686-pc-windows-msvc.github/workflows/ci.yml builds, tests and packages both platforms. It runs on pull requests and pushes to master in the willox and auxtools organizations; other forks can run it manually.
Linux binaries target glibc 2.35 and later. Windows binaries target Windows 10 and later and link the C runtime statically. ci/check-linux.sh and ci/check-windows.sh check these requirements.
CI uses pinned Rust and action versions. Format code with cargo +nightly-2026-10-24 fmt --all; the rustfmt configuration requires nightly options.
BYOND test archives come from the BYOND build mirror, verified against ci/byond.sha256. To run the integration suites locally, use ci/run-tests.sh PROGRAMS BYOND.
| Artifact | Contents |
|---|---|
auxtools-linux.tar.gz |
Launcher and debug library |
auxtools-linux-symbols.tar.gz |
auxtools.debug, libdebug_server.so.debug; place beside the binaries for gdb |
auxtools-windows.zip |
Launcher and debug library |
auxtools-windows-symbols.zip |
auxtools-cli.pdb, debug_server.pdb |
auxtools-VERSION.vsix |
VS Code extension with Linux and Windows binaries |
Run Actions > Release > Run workflow on master and enter a version such
as 3.0.0. The workflow builds and tests that version before publishing the
GitHub release and sohpea.auxtools extension.
It creates a vVERSION tag and advances master to the next patch's -dev
version. Publishing uses the release environment and Marketplace Trusted
Publishing. See release.yml for setup.
Auxtools is licensed under the MIT license. See LICENSE for more details.
The debug server, launcher and Auxcov coverage tool are licensed under GPL-3.0. See debug_server/LICENSE, auxtools-cli/LICENSE and auxcov/LICENSE.