Summary

Lightcode is a VSCode extension to debug iOS apps on iPhone - a lightweight alternative to Xcode.

Features

Two common modes:

• Run: build the app, install to iPhone, launch the app to start debugging.
• Attach: with the app already installed, launch the app to start debugging right away.

Debug features:

• Breakpoints, callstacks, inspect local variables.
• Use po to check variables.

Setup

1. Quickstart

Sample iOS app to try it out: ObjcSampleApp

• Create launch configurations in your project folder. This is just a ./vscode/launch.json in the project's root folder.
• Replace the content of launch.json as below, make sure to update <Your app's name> and <Your app bundle ID>:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run",
      "type": "lightcode",
      "request": "launch",
      "program": "${workspaceFolder}/build/Debug-iphoneos/<Your app's name>.app",
      "buildCommand": "xcodebuild -configuration Debug -sdk iphoneos -allowProvisioningUpdates",
      "appBundleId": "<Your app bundle ID>"
    },
    {
      "name": "Attach",
      "type": "lightcode",
      "request": "attach",
      "program": "${workspaceFolder}/build/Debug-iphoneos/<Your app's name>.app",
      "buildCommand": "xcodebuild -configuration Debug -sdk iphoneos -allowProvisioningUpdates",
      "appBundleId": "<Your app bundle ID>"
    }
  ]
}

• Open the project folder with VSCode; in the "Run and Debug" view, click the Run button.

2. launch.json details

To use this extension, you just need to properly write the configurations array in launch.json. VSCode automatically creates a button for each item in the configurations array. For example, when an item has "name": "Run", a Run button will show up in VSCode.

2.1 Required fields

The Run and Attach configurations share the same 6 fields. Here is the definition of each field:

• name: just a name of the configuration. It will show up as button in VSCode "Run and Debug" view.
• type: set it as lightcode. This is to let VSCode know that you want to use this extension to debug the iOS project.
• request: 2 allowed values - launch to build, install, and launch the app; attach to launch the app directly, skipping build and install.
• program: the location of the build output (the YourAppName.app file).
  • When using Xcode's default build system, this is usually "${workspaceFolder}/build/Debug-iphoneos/<Your app's name>.app". ${workspaceFolder} is a VSCode convenient variable to represent "the folder where VSCode was opened".
  • When using BUCK, this is usually "${workspaceFolder}/buck-out/...
• buildCommand: the command to build your iOS app.
  • When using Xcode's default build system, this is usually xcodebuild -configuration Debug -sdk iphoneos -allowProvisioningUpdates
  • When using BUCK, this is usually buck build folder:target
• appBundleId: the Bundle Identier of the iOS project, which can be found in Xcode.

2.2 Optional fields

• sourceMap: if you use a build system (such as BUCK), location of a source file may change before and after build. sourceMap is a dictionary to map from post-build path to pre-build path. For example, if the build system always adds a prefix "/build_out/base" to output symbols, you can use the following sourceMap:

"sourceMap": {
  "/build_out/base": "${workspaceFolder}"
}

Acknowledgement

• The LLDB part of the extension is a fork from CodeLLDB
• The iOS part of the extension is a fork from iOS debug