Library

Debugging

Nova 9 adds support for debugging.

Supported Environments

Working with the following debugging environments are available directly within Nova, provided you have installed any prerequisite tools necessary for those environments:

  • 🐘 PHP
  • 🐍 Python
  • 🏐 Chrome
  • 💎 Node.js
  • 🦕 Deno
  • 🟨 Playdate Simulator

These are the environments for which our users have most often requested debugger support, and which we believe are most likely to benefit Nova users. We may add support for more environments in the future, and will be providing an extension API so that users may implement debugging support for other environments.

For more information on using these environments, see the Getting Started section.

Features

Debug sidebar

The Debug sidebar allows you to observe debugging sessions and manage breakpoints. It can be added to your sidebar dock by dragging it from the All Sidebars sidebar.

Debugger pane

The Debugger section of the console pane is used to control the focused debug session, as well as introspect variables and state while a session is paused. This pane will automatically expand when a debugging session pauses.

Breakpoints

Line breakpoints can be added by clicking a line number in the editor gutter of any file which supports them.

Function breakpoints can be added from the Debug sidebar.

Exception breakpoints are provided by each debugger and will appear in the Debug sidebar the first time you invoke a debug session.

You can double-click on any breakpoint to set conditions and additional actions to run when the breakpoint is hit.

Getting Started

🐘 PHP

  1. Ensure your PHP environment has Xdebug installed.

    • You can install both PHP and Xdebug with Homebrew and PECL, if desired:
      1. brew install php
      2. pecl install xdebug

  2. Ensure that your php.ini file has been set up to enable Xdebug. Generally, this is done automatically by the Xdebug install process. See also the Documentation on this setting.

    [xdebug]
xdebug.mode = "debug"

  3. In Nova’s Project Settings, configure a new Task from one of the new PHP templates:

    • The PHP Debug template allows you to connect and debug existing PHP applications.
    • The PHP Local Web Server template allows you to run simple PHP applications using the php built-in web server and Xdebug directly from within Nova. This template will take care to automatically enable debugging for requests.

  4. Run your new task.

  5. Navigate to a page in your web application. Xdebug should automatically connect to Nova.

🐍 Python

  1. Ensure your Python environment has debugpy installed.
    • pip install debugpy or pip3 install debugpy
  2. In Nova’s Project Settings, configure a new Task from one of the new Python templates:
    • The Python Debug template allows you to run and debug local Python scripts and modules.
    • The Python Remote Debug template allows you to connect to Python applications running locally or remotely (such as on a server or in a containerized environment).
  3. Run your new task.

🏐 Chrome

  1. In Nova’s Project Settings, configure a new Task using the Chrome Debug template.
    • Setting the task to Launch will automatically start the browser and connect.
    • Setting the task to Attach will attempt to connect to an already-running browser instance.
  2. Run your new task.

💎 Node.js

  1. In Nova’s Project Settings, configure a new Task using the Node.js Debug template.
    • Setting the task to Launch will automatically start an instance of your application and connect.
    • Setting the task to Attach will attempt to connect to an already-running instance of your application.
  2. Run your new task.

🦕 Deno

  1. In Nova’s Project Settings, configure a new Task using the Deno Debug template.
    • Setting the task to Launch will automatically start an instance of your application and connect.
    • Setting the task to Attach will attempt to connect to an already-running instance of your application.
  2. Run your new task.

🟨 Playdate

  1. Ensure you have Playdate SDK v1.7 or later installed, as well as the Playdate extension.
  2. In Nova’s Project Settings, configure a new Task using the Playdate Simulator template.
  3. Run your new task.

Extensibility

Debugging support in Nova relies upon the Debug Adapter Protocol. Each built-in environment listed above is implemented using this mechanism, and extensions can contribute support for additional debuggers in the same way.

We intend to add an extension template for contributing additional debuggers in the future. In the interim, if you are interested in adding support for additional adapters, please refer to Nova’s built-in extensions (inside the app bundle at Contents/SharedSupport/Extensions/). Adapter code using the new APIs is located within each extension’s Tasks.js script. The extensions which provide debugging support are JavaScript, PHP, and Python.

Additional Notes

🐘 PHP

  • Debugging with PHP is implemented using a custom adapter, wrapping Xdebug.

🐍 Python

  • Debugging with Python is implemented using the debugpy package.
  • We recommend using Python 3. Python 2.x has not been tested, although debugpy still supports it.

🏐 Chrome and 💎 Node.js

  • Debugging with Chrome and Node are implemented using a custom adapter, wrapping Chrome DevTools.
  • Chrome DevTools does not currently support named function breakpoints within its runtime, so they are not currently supported in the Chrome adapter.
  • Debugging of Web Workers and Shared Workers is supported, but not fully tested. Work will continue on this during the beta. (Chrome only)
  • SourceMap resolution is supported for TypeScript and other languages that compile to JavaScript. Setting breakpoints in TypeScript files should translate properly provided source maps have been generated.
  • Other Chromium-based browser that support DevTools should work (such as Edge), but have not been fully tested. If you encounter issues, please provide feedback.

🧭 Safari support

Apple’s browser does not allow its debugger to be controlled by third-party tools. WebKit itself does contain a debugging interface, but Safari’s use of it is restricted behind special entitlements that macOS enforces, which so far have only been granted to Apple’s own software.

We had a discussion with the Safari / WebKit team about this, and unfortunately the conclusion was that opening up support for this to third party software was not in their near-term plans. If this does happen on Apple’s end we will absolutely work to include Safari debugging support.

This also applies to Nova’s built-in preview, which uses WebKit. While the preview is within Nova, WebKit renders it in a secondary process which is bound by the same entitlements as Safari itself.

🦊 Firefox support

Support for controlling the Firefox debugger would be possible through Mozilla’s Remote Debugging Protocol. We initially intended to support Firefox using this in a similar manner to Chrome. However, the Firefox protocol’s relative complexity combined with the browser’s current share of the market (averaging under 5% of Mac users) made us rethink this for the time being, as our engineering effort is needed elsewhere.