Debugging

This contract is identical to the one in Notifications, except it extends CMakeLists.txt to build notify-debug.wasm and it has an additional config file (launch.json).

CMakeLists.txt

# All cmake projects need these
cmake_minimum_required(VERSION 3.16)
project(notify)

# clsdk requires C++20
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# Libraries for building contracts and tests
find_package(clsdk REQUIRED)

# Build notify.wasm contract
add_executable(notify notify.cpp)
target_link_libraries(notify eosio-contract-simple-malloc)

# Build notify-debug.wasm
# This is like notify.wasm, but includes debugging information.
add_executable(notify-debug notify.cpp)
target_link_libraries(notify-debug eosio-contract-simple-malloc-debug)

# Generate notify.abi
# This is a 2-step process:
#   * Build notify.abi.wasm. This must link to eosio-contract-abigen.
#   * Run the wasm to generate the abi
add_executable(notify-abigen notify.cpp)
target_link_libraries(notify-abigen eosio-contract-abigen)
add_custom_command(TARGET notify-abigen POST_BUILD
    COMMAND cltester notify-abigen.wasm >notify.abi
)

# These symlinks help vscode
execute_process(COMMAND ln -sf ${clsdk_DIR} ${CMAKE_CURRENT_BINARY_DIR}/clsdk)
execute_process(COMMAND ln -sf ${WASI_SDK_PREFIX} ${CMAKE_CURRENT_BINARY_DIR}/wasi-sdk)

# Generate compile_commands.json to aid vscode and other editors
set(CMAKE_EXPORT_COMPILE_COMMANDS on)

Additional files

Building

This will create notify.wasm, notify-debug.wasm, and notify.abi:

mkdir build
cd build
cmake `clsdk-cmake-args` ..
make -j $(nproc)

Nodeos debug_plugin

debug_plugin (included in the nodeos binary that comes with clsdk) adds these new capabilities to nodeos:

  • Wasm substitution (--subst contract.wasm:debug.wasm). This instructs nodeos to execute debug.wasm whenever it would otherwise execute contract.wasm. nodeos identifies wasms by hash, so this affects all accounts which have the same wasm installed.
  • Relaxed wasm limits. Debugging wasms are usually much larger than normal contract wasms. debug_plugin removes eosio wasm limits to allow the larger wasms to execute. They are also slower, so it also removes execution time limits.
  • Debug info support. It transforms wasm debug info into native debug info. This enables gdb to debug executing contracts.

Only substituted wasms get the relaxed limits and debug info support.

Caution: debug_plugin intentionally breaks consensus rules to function; nodes using it may fork away from production chains.

Caution: stopping nodeos from inside the debugger will corrupt its database.