Using Oculus Debugger for VS Code

Oculus Debugger is a Visual Studio (VS) Code extension that is primarily intended for real-time debugging of Unreal Engine apps for Oculus. It fully supports debugging Oculus applications (APK files) and Oculus Native C/C++ binaries. It is integrated with Unreal Engine’s project generator.

Features of the Oculus Debugger Extension

  • Attaches to and/or launches targets defined in launch.json.
  • Supports debugging native C/C++ (ELF) binaries.
  • Supports debugging Oculus apps shipped via APK files.
  • Integrates with Unreal Engine, which produces a VS Code workspace file with build and launch configurations.
  • Uses LLDB debugger, which is downloaded from Oculus servers so no additional setup is required.
  • Supports setting breakpoints or watch variables, stepping over lines of code, stepping into executed functions, views of running threads, and their stacktraces.

Installation

  1. Download and install VS Code from the VS Code website.
  2. Open VS Code and click the Extensions icon.
  3. Search Oculus Debugger from MS Marketplace and then install it.

Debugging Unreal Projects

This section describes the setup necessary to create the workspace files required to use the extension to debug Unreal projects.

To set up the workspace files, follow these steps:

  1. Use the Oculus Source Distribution of Unreal.
  2. Make sure your code project is located under the UE4/Projects directory. Blueprints-only projects are not supported.
  3. Run GenerateProjectFiles.bat -VSCode in the UE4 root directory on the command line to generate the VS Code workspace.
  4. Open UE4.code-workspace in the UE4 root directory in VS Code.
  5. Use PROJECTNAME Oculus (Development) Launch to launch the debugger. This will automatically build your UE4 project before launching.

Note: To reduce the time needed to launch the application when debugging, cooking is skipped and only source code is compiled. If you need to cook assets, you can do so from VS Code by running Ctrl-Shift-P > Task: Run Task > PROJECTNAME Android Development Cook.

Debugging Native Binaries and Apps

The Oculus Debugger for VS Code can also be used with native applications.

Configurations must be set up in the launch.json before the Oculus Debugger can be used. To set up launch.json, follow these instructions:

  1. In VS Code, go to View > Run or click on the play button located on the left hand side bar.
  2. Use Run > Add Configuration to add a new configuration.
    • In case you don’t have an existing launch.json, you’ll get a popup that will have the Oculus Debugger option, and selecting it will populate launch.json with two sample Oculus Debugger configurations that you can further change to suit your project. A complete Android application launch.json configuration for the Oculus Debugger looks like the following:
"configurations": [
  {
    "type": "fb-lldb",
    "request": "launch",
    "name": "Launch Android Application example",
    "android": {
      "application": {
        "package": "com.mycompany.androidapp",
        "activity": ".MainActivity"
      },
      "lldbConfig": {
        "regexBreakpoints": [
          "startRendering",
        ],
        "librarySearchPaths": [
           "${env:HOME}/myproject/build/symbols",
        ],
        "sourceMaps": [
          "${env:HOME}/myproject ${workspaceFolder}",
        ],
        "lldbPreTargetCreateCommands": [
          "command script import \"${workspaceFolder}/PythonLLDBFormatters.py\""
        ],
      }
    },
  },

Descriptions of configuration attributes are as follows:

  • type - Is always fb-lldb because it is the debugger type that this configuration is for. The Oculus Debugger extension provides this type.
  • name - Specifies the name of the configuration that will be shown in the drop-down menu.

Android app attributes (shown in the example configuration above): package - Package containing the APK file for the android app. activity - Activity that specified Android app will start with.

Native C/C++ binary attributes (shown here):

"android": {
  "binary": {
    "remoteExecutable": "/data/local/tmp/native_binary",
    "arguments": "-a -b"
  },

remoteExecutable - Specifies the path on the device where the binary is located. arguments - Arguments to be passed to the binary.

Attributes for Android and native C/C++:

  • lldbConfig - Contains attributes that specify the LLDB configuration:
    • regexBreakpoints - The list of regular expressions that specify the functions that the debugger will stop on. Each of these values gets converted to the LLDB command breakpoint set --func-regex <VALUE>. In this example, it means that the debugger will stop when it hits any function that matches “getHello” regular expression.
    • librarySearchPaths - This is the list of paths that contain debug symbols. Usually, the device has a binary without the debug info running on it and there is a binary with the debug info locally somewhere in the build folder. The binary without the debug info is called a stripped binary whereas the binary with the debug info is called unstripped. In order for the debugger to provide stack traces and source mapping, it needs the debug info and it searches these folders for the unstripped versions of the loaded libraries for the process you are trying to debug.
      • sourceMaps - This is the mapping between the folder that’s specified in the binary’s debug info and the local file system. Usually, for binaries that are produced locally, there is no need to do anything as the debug info contains the local paths. However, sometimes the binaries contain debug info with either relative paths or paths from the machine they were created on. Please check your build system to see if it produces non-local paths.
      • lldbPreTargetCreateCommands - This is the list of LLDB commands that will be executed before the target is created. This could be used for loading LLDB python scripts for example. It is important to note that these are specifically LLDB commands. More LLDB commands can be found at (https://lldb.llvm.org/use/tutorial.html).
      • lldbPostTargetCreateCommands - This is the list of commands to be executed after the target has been created, once we have attached to or started the target process. It could be used to list the loaded modules for example, with image list, or could be used for adding symbols for a particular module, with add-dsym /path/to/particular/module.so.

        Troubleshooting

  • Using the Command Palette to execute Clean LLDB caches and Oculus Runtime downloads can be helpful if the debug session is stuck. If the session can’t start and it’s unclear what the issue is, the problem is sometimes in broken LLDB caches or Oculus runtime installations. In those situations clearing them by using this command may help resolve the issue.
  • If you are having trouble and wish to file a bug report, you can submit a bug report at (https://github.com/facebookexperimental/oculus-debugger-vscode/). To file a bug from within VS Code, use the links in the Marketplace or use Help: Report Issue from the Command Palette. You can also click the Tweet Feedback button in the bottom-right corner and select the Submit a Bug link.