UserGuide

Remote Debugging

From Xojo Documentation

When you run your project it runs on the same platform you are using. So if you develop on Mac, then clicking Run will run your project on macOS.

Since Xojo is a cross-platform development tool, you are likely to want to also run your projects on other platforms for debugging purposes. You can do this using the Remote Debugger, which has two version: Desktop and Console.

The desktop version is used to remotely debug to an OS that has a desktop UI. It can be used with desktop and console apps. The console version is used to remotely debug to an OS that does not have a UI (such as servers). It can debug console and web apps.

Remote Debugger Configuration

The Remote Debugger is a small app that lets you run your project on a different target platform. Xojo communicates with it so that when you run your project, it sends it to the target platform rather than running it locally. Normally when you run your project from within Xojo (Project ↠ Run), it runs the debug build locally. If you have the Remote Debugger configured, you can instead have Xojo send and run your debug build on a remote computer, which is incredibly useful for testing cross-platform apps. This remote build still communicates with Xojo, so you can access the debugger and test just as if you were running it locally.

Remote Debugger Desktop

On the remote machine, you need to run Remote Debugger Desktop, which is included with your Xojo installation in the Extras folder. There are separate versions for these platforms:

  • macOS: 32-bit and 64-bit
  • Windows: 32-bit and 64-bit
  • Linux: 32-bit and 64-bit
  • Linux ARM: 32-bit (used for Raspberry Pi Remote Debugging)
Remote Debugger Desktop

Copy the version you need to the platform you are using.

Remote Debugger Options

You can only use the 64-bit Remote Debugger on 64-bit operating systems. A 64-bit Remote Debugger can run either a 32-bit or a 64-bit app. When using a 64-bit Remote Debugger, the build settings for the target are used to determine if a 32-bit or a 64-bit build is sent.

A 32-bit Remote Debugger can only run 32-bit apps.

Remote Debugger Desktop has an Options window that lets you configure its settings.

  • Name: The name of the machine. This appears on the Developer Machine in Xojo's Remote Debugger preferences.
  • Password: An optional password used to connect to the Remote Debugger.
  • Download Location: Click the Choose button to set the location where the app will be download to and run from. Be sure you have read/write access to this location.
  • Network Interface: If you have more than one network interface, you can choose the one to use here. Typically you'll leave this as "Default".
  • Port: The default port is 44553, which you'll need to make sure is open in the firewall for both UDP and TCP connections.
  • Max Connections: This specifies how many concurrent connections to the Remote Debugger are allowed.
  • Public: Allows the Remote Debugger to be displayed on the Developer Machine in Xojo's Remote Debugger preferences.

After you have set the Options, click OK and leave Remote Debugger Desktop running.

The "Launch executable after receiving" checkbox is used to disable the automatic running of your app after the Remote Debugger receives it. You may want to disable this if you have to manually set up specific things on the remote machine (copy files or folders, start a separate app, etc.) before your app should launch.

If you are using a firewall on the remote machine, you need to make sure that port 44553 is open for both UDP and TCP connections.

If you hold Shift when launching the Remote Debugger Stub, it creates a "Stub Log" file on the desktop that contains log information that can help you troubleshoot any Remote Debugger configuration issues.

Remote Debugger Console

The console version can debug console apps, standalone web apps and CGI web apps on remote machines that do not have a desktop interface (such as servers). Currently it can only be used across a local network (or VPN).

On the remote machine, you need to run Remote Debugger Console, which is included with your Xojo installation in the Extras folder. There are separate versions for these platforms:

  • macOS: 32-bit and 64-bit
  • Windows: 32-bit and 64-bit
  • Linux: 32-bit and 64-bit
  • Linux ARM: 32-bit (used for Raspberry Pi Remote Debugging)

Copy the version you need to the platform you are using.

If you are trying to debug a CGI app, set the Remote Debugger to not launch automatically (in the Options) and set the path to point to where your CGI apps must be installed in order for them to work with the web server. The web server will launch the debug app when you visit the appropriate URL in your browser.

You can only use the 64-bit Remote Debugger on 64-bit operating systems. A 64-bit Remote Debugger can run either a 32-bit or a 64-bit app (macOS or Linux. You cannot remote debug 64-bit Windows apps at this time). When using a 64-bit Remote Debugger, the build settings for the target are used to determine if a 32-bit or a 64-bit build is sent.

A 32-bit Remote Debugger can only run 32-bit apps.

The ARM remote debugger does not automatically start the console app. You'll need to manually launch it from the Terminal after it has been sent to the Pi.

Remote Debugger Console runs from Terminal or the command line. The first time you launch it, you are prompted for the settings:

  • Machine Name: The name of the machine.
  • Download Directory: The location to download the app to and run from. Be sure you have read/write access to this location.
  • IP Address: Specifies the IP address to listen on (must match an IP address available on the computer).
  • Maximum Connections: Sets the maximum number of connections.
  • Auto Launch: Have the remote debugger automatically launch the app being debugged.
  • Public: Indicates if the remote debugger is publicly visible.
  • Password: Specifies an optional connection password.

These settings are saved in the RDS.config file in the same folder as the Console Remote Debugger.

You can also provide these an other options via the command line. Use the “--help” argument to get a list of all available command line options.

Development Machine Configuration

Remote Debugger IDE Preferences

On the development machine, you need to configure Xojo so that it can see the Remote Debugger. In Preferences, select Debugger. There you'll see a list of configured remote machines. You can also see this list by going to Project ↠ Run Remotely ↠ Setup.

Click Add to add your remote machine. Depending on your network configuration, the remote machine may appear as a public remote machine. If it does, you can just click its name and then OK to add it. If it does not appear, you can enter the IP address (specified on the Remote Debugger App on the remote machine) and give it a name.

If you are using a firewall on your development machine, you need to make sure that port 44553 is open for UDP and TCP connections and port 13897 is open for TCP connections.

Note: Virtual machine software such as VMware Fusion, Parallels Desktop, VMware Desktop and Microsoft Virtual PC all work great with remote debugging, but you typically want to have their networking configured to use "Bridged Networking" so that they will have their own IP address.

Remote Debugging

Now you can try running a project remotely. On the development machine, create a new desktop project.

To run the project remotely, instead of selecting Project ↠ Run (or clicking the Run button on the toolbar), choose Project ↠ Run Remotely and click your remote machine name. Your project is compiled and linked as usual, but you will now see an additional step where this debug build is sent over to the Remote Debugger App on the remote machine.

When the Remote Debugger App has received the debug build, it runs it. Interact with the running app on the remote machine. Any breakpoints you have set will jump to the debugger on the development machine.

Virtual Machines

Microsoft makes available several different versions of Windows for testing purposes, which you can use with virtual machines to test your Xojo apps.

Linux distributions are generally free and work fine within most virtual machines.

You are allowed to run macOS 10.7 and later within a virtual machine, but only if the VM is running on a Mac.

Here are some commonly used Virtual Machine products:

  • VirtualBox
  • VMware Fusion
  • Parallels Desktop
  • Virtual PC

See Also

UserGuide:Debugger Usage, UserGuide:Raspberry Pi Remote Debugging topics; TargetRemoteDebugger constant