Skip to main content
Conversational AI Engine: Create advanced voice apps by combining Agora's real-time audio with powerful conversational AI.

Debug applications

The TEN framework supports debugging applications built with multiple programming languages, including C++, Go, and Python. This guide shows you how to configure VS Code to debug your TEN applications effectively, whether you are working with single-language or mixed-language projects.

Debug use cases​

There are two main use cases when debugging TEN applications. You can use VS Code's debugging capabilities with language-specific debuggers and custom launch configurations for both:

Framework development When contributing to or modifying the TEN framework itself, use the launch.json file available in the framework's source tree. This file provides default debug targets to help you get started quickly.

Application development
When building your own applications using the TEN framework, add custom configurations to your .vscode/launch.json file. This enables you to set breakpoints and inspect variables, regardless of the programming language you use: C++, Go, or Python.

Both use cases provide breakpoint debugging, variable inspection, and step-through execution capabilities.

Application development​

When developing your own application based on the TEN framework using VS Code, add custom configurations to your .vscode/launch.json file. This enables you to set breakpoints and inspect variables, regardless of the programming language you use: C++, Go, or Python.

C++ applications​

When you write your application in C++, you can write extensions in either C++ or Python.

Debug C++ code with lldb or gdb​

Use the following configurations to debug C++ code:

  • With lldb:


    _11
    {
    _11
    "name": "app (C++) (lldb, launch)",
    _11
    "type": "lldb",
    _11
    "request": "launch", // "launch" or "attach"
    _11
    "program": "${workspaceFolder}/bin/worker", // The executable path
    _11
    "cwd": "${workspaceFolder}/",
    _11
    "env": {
    _11
    "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
    _11
    "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib" // macOS
    _11
    }
    _11
    }

  • With gdb:


    _20
    {
    _20
    "name": "app (C++) (gdb, launch)",
    _20
    "type": "cppdbg",
    _20
    "request": "launch", // "launch" or "attach"
    _20
    "program": "${workspaceFolder}/bin/worker", // The executable path
    _20
    "cwd": "${workspaceFolder}/",
    _20
    "MIMode": "gdb",
    _20
    "environment": [
    _20
    {
    _20
    // linux
    _20
    "name": "LD_LIBRARY_PATH",
    _20
    "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
    _20
    },
    _20
    {
    _20
    // macOS
    _20
    "name": "DYLD_LIBRARY_PATH",
    _20
    "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
    _20
    }
    _20
    ]
    _20
    }

Debug Python code with debugpy​

Use debugpy to debug Python code in TEN applications. Since TEN applications run Python code inside an embedded interpreter rather than starting with the Python interpreter directly, you must attach the debugger to the running process instead of launching it directly.

  1. Install debugpy in the Python environment:


    _1
    pip install debugpy

  2. Set the TEN_ENABLE_PYTHON_DEBUG and TEN_PYTHON_DEBUG_PORT environment variables before starting the application:


    _1
    TEN_ENABLE_PYTHON_DEBUG=true TEN_PYTHON_DEBUG_PORT=5678 ./bin/worker

    When you set TEN_ENABLE_PYTHON_DEBUG to true, the application blocks until a debugger is attached. When you set TEN_PYTHON_DEBUG_PORT, the debugger server listens on the specified port for incoming connections.

  3. After starting the application, attach the debugger to the running process using the following configuration:


    _10
    {
    _10
    "name": "app (C++) (debugpy, attach)",
    _10
    "type": "debugpy",
    _10
    "request": "attach",
    _10
    "connect": {
    _10
    "host": "localhost",
    _10
    "port": 5678
    _10
    },
    _10
    "justMyCode": false
    _10
    }

Debug C++ and Python code simultaneously​

To debug C++ and Python code simultaneously with one click in VS Code:

  1. Define a delay task before attaching the debugger:


    _9
    {
    _9
    "label": "delay 3 seconds",
    _9
    "type": "shell",
    _9
    "command": "sleep 3",
    _9
    "windows": {
    _9
    "command": "ping 127.0.0.1 -n 3 > nul"
    _9
    },
    _9
    "group": "none"
    _9
    }

  2. Add the following configurations to the launch.json file:


    _35
    "configurations": [
    _35
    {
    _35
    "name": "app (C++) (lldb, launch with debugpy)",
    _35
    "type": "lldb",
    _35
    "request": "launch", // "launch" or "attach"
    _35
    "program": "${workspaceFolder}/bin/worker", // The executable path
    _35
    "cwd": "${workspaceFolder}/",
    _35
    "env": {
    _35
    "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
    _35
    "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // macOS
    _35
    "TEN_ENABLE_PYTHON_DEBUG": "true",
    _35
    "TEN_PYTHON_DEBUG_PORT": "5678"
    _35
    }
    _35
    },
    _35
    {
    _35
    "name": "app (C++) (debugpy, attach with delay)",
    _35
    "type": "debugpy",
    _35
    "request": "attach",
    _35
    "connect": {
    _35
    "host": "localhost",
    _35
    "port": 5678
    _35
    },
    _35
    "justMyCode": false,
    _35
    "preLaunchTask": "delay 3 seconds"
    _35
    }
    _35
    ],
    _35
    "compounds": [
    _35
    {
    _35
    "name": "app (C++) (lldb, launch) and app (C++) (debugpy, attach)",
    _35
    "configurations": [
    _35
    "app (C++) (lldb, launch with debugpy)",
    _35
    "app (C++) (debugpy, attach with delay)"
    _35
    ]
    _35
    }
    _35
    ]

  3. Start debugging by selecting the compound configuration app (C++) (lldb, launch) and app (C++) (debugpy, attach).

Go applications​

When you write your application in Go, you can write extensions in either Go or Python.

Debug Go code with delve​

Use the following configuration to debug your Go extensions:


_13
{
_13
"name": "app (golang) (go, launch)",
_13
"type": "go",
_13
"request": "launch",
_13
"mode": "exec",
_13
"cwd": "${workspaceFolder}/",
_13
"program": "${workspaceFolder}/bin/worker", // The executable path
_13
"env": {
_13
"LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
_13
"DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // macOS
_13
"TEN_APP_BASE_DIR": "${workspaceFolder}"
_13
}
_13
}

Debug C++ extensions with lldb or gdb​

Use the following configurations to debug C++ extensions in your Go application:

  • With lldb:


    _12
    {
    _12
    "name": "app (Go) (lldb, launch)",
    _12
    "type": "lldb",
    _12
    "request": "launch", // "launch" or "attach"
    _12
    "program": "${workspaceFolder}/bin/worker", // The executable path
    _12
    "cwd": "${workspaceFolder}/",
    _12
    "env": {
    _12
    "LD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib", // linux
    _12
    "DYLD_LIBRARY_PATH": "${workspaceFolder}/ten_packages/system/xxx/lib" // macOS
    _12
    },
    _12
    "initCommands": ["process handle SIGURG --stop false --pass true"]
    _12
    }

  • With gdb:


    _20
    {
    _20
    "name": "app (Go) (gdb, launch)",
    _20
    "type": "cppdbg",
    _20
    "request": "launch", // "launch" or "attach"
    _20
    "program": "${workspaceFolder}/bin/worker", // The executable path
    _20
    "cwd": "${workspaceFolder}/",
    _20
    "MIMode": "gdb",
    _20
    "environment": [
    _20
    {
    _20
    // linux
    _20
    "name": "LD_LIBRARY_PATH",
    _20
    "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
    _20
    },
    _20
    {
    _20
    // macOS
    _20
    "name": "DYLD_LIBRARY_PATH",
    _20
    "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
    _20
    }
    _20
    ]
    _20
    }

Debug Python code with debugpy​

For Python debugging setup, refer to the C++ applications section. Set the environment variables TEN_ENABLE_PYTHON_DEBUG and TEN_PYTHON_DEBUG_PORT before starting the application:


_1
TEN_ENABLE_PYTHON_DEBUG=true TEN_PYTHON_DEBUG_PORT=5678 ./bin/worker

Attach the debugger to the running process using the following configuration:


_10
{
_10
"name": "app (Go) (debugpy, attach)",
_10
"type": "debugpy",
_10
"request": "attach",
_10
"connect": {
_10
"host": "localhost",
_10
"port": 5678
_10
},
_10
"justMyCode": false
_10
}

Debug multiple languages simultaneously​

To debug C++, Go, and Python code simultaneously with one click in VS Code:

  1. Define a delay task before attaching the debugger:


    _9
    {
    _9
    "label": "delay 3 seconds",
    _9
    "type": "shell",
    _9
    "command": "sleep 3",
    _9
    "windows": {
    _9
    "command": "ping 127.0.0.1 -n 3 > nul"
    _9
    },
    _9
    "group": "none"
    _9
    }

  2. Add the following configurations to the launch.json file:


    _56
    "configurations": [
    _56
    {
    _56
    "name": "app (golang) (debugpy, remote attach with delay)",
    _56
    "type": "debugpy",
    _56
    "request": "attach",
    _56
    "connect": {
    _56
    "host": "localhost",
    _56
    "port": 5678
    _56
    },
    _56
    "preLaunchTask": "delay 3 seconds",
    _56
    "justMyCode": false
    _56
    },
    _56
    {
    _56
    "name": "app (golang) (go, launch with debugpy)",
    _56
    "type": "go",
    _56
    "request": "launch",
    _56
    "mode": "exec",
    _56
    "cwd": "${workspaceFolder}/",
    _56
    "program": "${workspaceFolder}/bin/worker",
    _56
    "env": {
    _56
    "TEN_APP_BASE_DIR": "${workspaceFolder}",
    _56
    "TEN_ENABLE_PYTHON_DEBUG": "true",
    _56
    "TEN_PYTHON_DEBUG_PORT": "5678"
    _56
    }
    _56
    },
    _56
    {
    _56
    "name": "app (golang) (lldb, launch with debugpy)",
    _56
    "type": "lldb",
    _56
    "request": "launch",
    _56
    "program": "${workspaceFolder}/bin/worker",
    _56
    "cwd": "${workspaceFolder}/",
    _56
    "env": {
    _56
    "TEN_ENABLE_PYTHON_DEBUG": "true",
    _56
    "TEN_PYTHON_DEBUG_PORT": "5678"
    _56
    },
    _56
    "initCommands": [
    _56
    "process handle SIGURG --stop false --pass true"
    _56
    ]
    _56
    }
    _56
    ],
    _56
    "compounds": [
    _56
    {
    _56
    "name": "Mixed Go/Python",
    _56
    "configurations": [
    _56
    "app (golang) (go, launch with debugpy)",
    _56
    "app (golang) (debugpy, remote attach with delay)"
    _56
    ]
    _56
    },
    _56
    {
    _56
    "name": "Mixed Go/Python/C++ (lldb)",
    _56
    "configurations": [
    _56
    "app (golang) (lldb, launch with debugpy)",
    _56
    "app (golang) (debugpy, remote attach with delay)"
    _56
    ]
    _56
    }
    _56
    ]

Use compound configurations:

  • For C++ and Python debugging: Use Mixed Go/Python/C++ (lldb). This supports breakpoint debugging for all three languages, but variable inspection only works for C++ and Python.
  • For Go and Python debugging: Use Mixed Go/Python. This supports both breakpoint debugging and variable inspection for Go and Python.

Python applications​

When you write your application in Python, you can write extensions in either Python or C++.

Debug C++ extensions with lldb or gdb​

Use the following configuration to debug C++ extensions in your Python application:


_19
{
_19
"name": "app (Python) (cpp, launch)",
_19
"type": "cppdbg",
_19
"request": "launch", // "launch" or "attach"
_19
"program": "/usr/bin/python3", // The Python interpreter path
_19
"args": ["main.py"],
_19
"cwd": "${workspaceFolder}/",
_19
"environment": [
_19
{
_19
"name": "PYTHONPATH",
_19
"value": "${workspaceFolder}/ten_packages/system/ten_runtime_python/lib:${workspaceFolder}/ten_packages/system/ten_runtime_python/interface"
_19
},
_19
{
_19
"name": "TEN_APP_BASE_DIR",
_19
"value": "${workspaceFolder}/"
_19
}
_19
],
_19
"MIMode": "gdb" // "gdb" or "lldb"
_19
}

Debug Python code with debugpy​

Use the following configuration to debug Python code directly:


_14
{
_14
"name": "app (Python) (debugpy, launch)",
_14
"type": "debugpy",
_14
"python": "/usr/bin/python3",
_14
"request": "launch",
_14
"program": "${workspaceFolder}/main.py",
_14
"console": "integratedTerminal",
_14
"cwd": "${workspaceFolder}/",
_14
"env": {
_14
"PYTHONPATH": "${workspaceFolder}/ten_packages/system/ten_runtime_python/lib:${workspaceFolder}/ten_packages/system/ten_runtime_python/interface",
_14
"TEN_APP_BASE_DIR": "${workspaceFolder}/",
_14
"TEN_ENABLE_PYTHON_DEBUG": "true"
_14
}
_14
}

Debug C++ and Python code simultaneously​

To debug both C++ and Python code simultaneously:

  1. Launch the application with the app (Python) (debugpy, launch) configuration

  2. Attach the C++ debugger to the running process using the following configuration:


    _18
    {
    _18
    "name": "app (Python) (cpp, attach)",
    _18
    "type": "cppdbg",
    _18
    "request": "attach", // "launch" or "attach"
    _18
    "program": "${workspaceFolder}/bin/worker", // The executable path
    _18
    "cwd": "${workspaceFolder}/",
    _18
    "MIMode": "gdb",
    _18
    "environment": [
    _18
    {
    _18
    "name": "LD_LIBRARY_PATH",
    _18
    "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
    _18
    },
    _18
    {
    _18
    "name": "DYLD_LIBRARY_PATH",
    _18
    "value": "${workspaceFolder}/ten_packages/system/xxx/lib"
    _18
    }
    _18
    ]
    _18
    }