rspack-debugging

name	rspack-debugging
description	Helps Rspack users and developers debug crashes or deadlocks/hangs in the Rspack build process using LLDB. Use this Skill when users encounter "Segmentation fault" errors during Rspack builds or when the build progress gets stuck.

Rspack Debugging

Overview

This Skill guides you on how to capture the underlying crash state of Rspack (which is based on Rust). By using the LLDB debugger and Rspack packages with debug symbols, we can obtain detailed stack backtraces, which are crucial for pinpointing issues. The guides focus on non-interactive, automated debugging to easily capture backtraces.

Preparation

Before starting, please ensure your environment meets the requirements.

1. Install LLDB: You must install the LLDB debugger.

   • macOS: Run xcode-select --install
   • Linux: Install the lldb package (e.g., apt-get install lldb)
   • Detailed guide: references/lldb.md

2. Replace Debug Packages: Production packages like @rspack/core have debug symbols stripped. They must be replaced with the @rspack-debug/* series packages to see useful stack information.

   Automatic Replacement Script:

   node ${CLAUDE_PLUGIN_ROOT}/skills/debugging/scripts/setup_debug_deps.cjs
   

   Running the above script will automatically add pnpm.overrides configuration to package.json, pointing Rspack packages to their corresponding Debug versions. Afterwards, please be sure to run pnpm install to update dependencies.

Debugging Workflows

Identify your specific scenario and follow the corresponding linked guide.