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.
launch.json.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:
UE4/Projects directory. Blueprints-only projects are not supported.GenerateProjectFiles.bat -VSCode in the UE4 root directory on the command line to generate the VS Code workspace.UE4.code-workspace in the UE4 root directory in VS Code.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.
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:
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.