Remote debug ACAP application: Part 3b - debug using Visual Studio Code

[Corallo]

Important

This tutorial is replaced by remote-debug-example for AXIS OS versions 11.11 and later.

Introduction

This is a tutorial in three parts showing how-to remote debug an ACAP application on an Axis device from a user machine.

• Part 1 - build a gdbserver
• Part 2 - application with debug symbols
• Part 3
  • Part 3a - debug the application
  • Part 3b - debug using Visual Studio Code

The setup

• Axis device (target, remote)
  • Will run gdbserver and either attach to or start an installed ACAP application to debug
• User machine (desktop)
  • Use Visual Studio Code to run gdb-multiarch and connect to the gdbserver on the device.
  • Needs access to the application binary with debug symbols (not stripped)

Limitations

• This tutorial requires root access on an Axis device and this solution will only work up until next AXIS OS LTS 2024. More information in this announcement.

Requirements

• The gdbserver container image from Part 1 - build a gdbserver
• The application container image hello-debug:1.9-armv7hf-dev from Part 2 - application with debug symbols
• Install Visual Studio Code (VS Code)
• Install VS Code extensions
  • Dev Containers (ms-vscode-remote.remote-containers)
• VS Code extensions will be automatically installed in Dev container
  • C/C++ (ms-vscode.cpptools)
  • Native Debug (webfreak.debug)

Part 3b - debug using Visual Studio Code

This guide shows how to remote debug an ACAP application in VS Code. The approach is similar to the command-line approach in part 3 and will use the gdbserver from part 1 and the container image with the application binary with debug symbols from part 2 to debug an installed ACAP application. Part 3 doesn't represent a prerequisite.

On user machine

Start in the application directory from part 2. Create a folder called .devcontainerand add file devcontainer.json to it with the following content:

{
    "name": "My dev container",
    "image": "hello-debug:1.9-armv7hf-dev",
    "workspaceMount": "source=${localWorkspaceFolder},target=/opt/app,type=bind",
    "workspaceFolder": "/opt/app",
    "customizations": {
        "vscode": {
          "extensions": ["ms-vscode.cpptools", "webfreak.debug"]
        }
      }
}

Also create a .vscode directory and add file launch.json to it with the following content:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(gdb) Remote Attach",
            "type": "cppdbg",
            "request": "launch",
            "program": "/opt/app/debug/hello_debug",
            "MIMode": "gdb",
            "cwd": "${workspaceFolder}",
            "miDebuggerPath": "/usr/bin/gdb-multiarch",
            "miDebuggerServerAddress": "192.168.0.90:1234",
            "setupCommands": [
                {
                    "description": "Enable pretty-printing for gdb",
                    "text": "-enable-pretty-printing",
                    "ignoreFailures": true,
                }
            ]
        },
    ]
}

The work directory should look like this:

.
├── app
│    └── .devcontainer
│   │    └── devcontainer.json
│    └── .vscode
│   │    └── launch.json
│   ├── hello_debug.c
│   ├── LICENSE
│   ├── Makefile
│   └── manifest.json
├── Dockerfile
└── README.md

Now use the Visual Studio Code extension Dev Containers to start an instance of image hello-debug:1.9-armv7hf-dev.

• Press F1
• Select Dev Containers: Open Folder in Container...
• Select the app directory

You are now attached to your development container. All the changes you make here will apply also to the application project in your local file system.

Open a terminal in the VS Code development container, then build and install the application.

Note

• Password from root user is required at install.

acap-build .
eap-install.sh 192.168.0.90 <password> install

On Axis device

In a terminal, SSH in to the device as root. Start gdbserver with the application binary installed under /usr/local/packages/APPNAME/BINARYNAME and open a TCP connection to a debug port on the Axis device, here port 1234 is used.

ssh root@192.168.0.90
root@axisdevice$ /tmp/gdbserver :1234 /usr/local/packages/hello_debug/hello_debug <Application_arguments>
Process /usr/local/packages/hello_debug/hello_debug created; pid = 21919
Listening on port 1234

The gdbserver will stop at the entry point of the application to let you add breakpoints and start stepping through the application from the user machine.

Start debugging

Now you can open the source code of your application, and start debugging by pressing F5.

If you wish to keep developing in the developer container you are using to debug, it is recommended to integrate this guide with the ACAP documentation page Setting up Visual Studio Code to also get the Visual Studio IntelliSense symbols auto-completion.