Vallenta StudioVallenta Studio
Install
Back to Overview
ProBeta

The Debugger, on Linux

A Linux64 project is compiled on Windows, deployed to a Linux machine and debugged there from VS Code: breakpoints, stepping, call stack, locals and Watch expressions in Delphi syntax. The Delphi installation, the source files and the editor remain on Windows. Only the program runs on Linux.

Vallenta Studio - Debugging on Linux64
VS Code debugging a Delphi Linux64 program with Vallenta Studio: Locals showing Delphi strings, a set, a dynamic array and an object; a Watch expression resolving an interface reference to its implementing class; the build panel reporting Debug | Linux64 and the status bar showing the paired Linux target paused at a breakpoint.
Overview

Deployment and debugging without PAServer

A Linux64 project is compiled on Windows by Delphi's Linux compiler. Vallenta Studio copies the executable and the configured deployment files to the Linux machine, starts the program there under the debugger and presents the session in VS Code. The Linux side runs one static binary, VallentaAgent. PAServer, paclient, Embarcadero's LLDB and the IDE's Linux SDK registration are not used. The Linux machine needs no SDK and no development packages: only VallentaAgent and the lldb-server package of its distribution.

Setup

Three steps, once

Each step is performed once per machine. Afterwards F5 behaves as on Windows.

1

Install the agent

The agent is installed with one command on the Linux machine, without root and entirely inside the home directory. At start it prints a pairing token. lldb-server is installed from the distribution's package manager; the agent reports the package name for the distribution it detects.

Linux shell
curl -fsSL https://github.com/Vallenta/VallentaAgent/releases/latest/download/install.sh | sh
Vallenta Studio - Platform Manager
Vallenta Studio Platform Manager card: Linux targets and distributions summary, the local lldb-dap engine with its version, size and install date, and the VallentaAgent install command with Copy and GitHub buttons.
2

Pair the machine

Add Linux Target pairs the machine from host, port and the printed token; pairing is performed once. The Linux Targets panel lists each paired machine with the values it reports: agent version, lldb-server version, distribution and glibc. A project references a target by name; no host name or port is written into the .dproj.

Vallenta Studio - Linux Targets
Vallenta Studio Linux Targets panel: one configured target with address, distribution and Reachable status, and its editor showing name, host, port, distribution, the reported agent, lldb and glibc versions, and Save, Test, Re-pair and Remove buttons.
3

Prepare a sysroot

Linking a Linux64 project requires the target distribution's libraries. The Linux Distributions panel downloads them from the distribution's own package archive and prepares a sysroot per distribution; the target's distribution selects the sysroot a build links against. No Linux SDK registration in the IDE is required. A library not in the catalogue is added by package name.

Vallenta Studio - Linux Distributions
Vallenta Studio Linux Distributions panel listing three registered sysroots, ubuntu-22.04, ubuntu-24.04 and ubuntu-26.04, each from the catalogue with its folder, size and Ready state.

F5 then builds the project if it is out of date, deploys it and starts the debug session.

Key Features

Debugging on the target, from VS Code

Breakpoints, stepping and call stack on the target

Breakpoints set in the Windows source files bind in the program running on Linux. Step into, step over, step out, call stack navigation and local inspection work as on Windows. Delphi strings, dynamic arrays, sets, records, classes and interfaces are rendered in Delphi form.

Watch expressions in Delphi syntax

The Watch panel evaluates Delphi expressions against the running Linux process: Length(Temperatures), Report.ShortName.Value, or a method call on a live object, with arguments. An interface reference resolves to the implementing object and its fields.

Delphi exceptions stop at the raise site

A raised Delphi exception stops execution at the raise statement and reports the exception class and message. All Delphi Exceptions is the default filter in the Breakpoints view, as on Windows.

Deployment per build configuration

Deployment Options holds the target, the working directory and the deployed files per build configuration: single files, folders or patterns such as data/**, each with subfolder, remote name, overwrite and executable flags. The Live Target View shows the resulting layout on the target before any file is copied.

Linking without a registered SDK

The build links against a sysroot assembled from the distribution's own packages, pinned to an archive snapshot. Ubuntu 22.04, 24.04 and 26.04 are in the catalogue. A sysroot can also be linked from a local folder, or imported from a paired target that has its development packages installed.

Program output in its own terminal

Program output is written to an integrated VS Code terminal, and a program that reads standard input is driven from the same terminal. Each session writes its startup steps, with durations, to the Vallenta Linux Debug output channel.

In Practice

Deployment and program output

Vallenta Studio - Deployment Options
Vallenta Studio Deployment Options editor: configuration list on the left; on the right the Linux target with its status, the working directory, a deployed files table with subfolder, remote name, overwrite, executable and enabled columns, and a Live Target View tree of the scratch root.

Target, working directory and deployed files per build configuration. The Live Target View below shows the layout on the target, including the executable, which the debugger uploads without an entry.

Per build configurationLive Target View
Vallenta Studio - Build
Vallenta Studio build panel with Configuration Debug and Platform Linux64 selected, the paired target LinuxTestBox shown reachable with its scratch root, and Run, Debug, Build and Rebuild buttons.

The build panel shows the configuration's target and its reachability before Debug is pressed.

Linux64Target status
Vallenta Studio - Terminal
VS Code Terminal panel with the Debug WeatherReport (Linux) session selected, showing the program's table output, summary, lookups and averages, and the cursor waiting at the prompt.

The program's output in the integrated terminal of the debug session. A program that reads standard input is driven from the same terminal.

Program outputStandard input
Also included
Copy Linux Agent Install Command - copies the install command to the clipboard from the command palette.
Deploy Files - sends the configuration's files and the built executable without starting the program.
Import from Delphi - imports a project's existing Linux64 deployment entries, once and additively, and reports skipped entries.
Regenerate Debug Metadata - regenerates the type information the Linux debugger reads from the executable; a debug session regenerates it automatically when the executable is newer.
Startup log with durations - deploy, launch and transfer check are logged with their duration to the Vallenta Linux Debug output channel; vallenta.studio.linux.trace adds the adapter traffic.
Environment per launch configuration - env in the launch configuration extends the agent's environment and overrides variables of the same name.
Target status before launch - the build panel and Deployment Options show whether the target answers; the check runs on open, on configuration switch and on target change.
Debug engine downloaded on request - lldb-dap is downloaded once from the MSYS2 package index. The lldb-server version a target reports is checked against the tested range, and a version outside it is reported as untested. The Platform Manager card offers Check for Updates and a file picker for a locally installed lldb-dap.
How it works

How a session runs

VS Code communicates with Vallenta Studio's Linux debug adapter. The adapter drives lldb-dap on Windows, which connects to an lldb-server on the Linux machine that VallentaAgent starts per session. Debug information is the DWARF the Delphi compiler writes into the ELF executable. Vallenta Studio reads it into the same type model the Windows debugger uses and reads interface types from the program's RTTI, since DWARF does not record them. Breakpoints are set on Windows paths and mapped to the target.

Windows
VS Code + Vallenta Studio

The Linux debug adapter. Breakpoints are set on Windows paths.

Windows
lldb-dap

Downloaded once on request.

Linux
VallentaAgent + lldb-server

One lldb-server per debug session.

Linux
The program

Runs in the agent's scratch root.

The Linux side

One static binary

VallentaAgent is the only component installed on the Linux machine: one static binary, installed inside the home directory without root. It prints a pairing token at start, starts one lldb-server per debug session and confines deployed programs to a scratch root. The control connection is authenticated but not encrypted; the intended deployment is a trusted network or an SSH tunnel, with the agent running as a dedicated low-privilege user.

  • Install: one curl | sh line, no root, ~/.local/lib/vallenta-agent
  • lldb-server from the distribution: Debian/Ubuntu, Fedora/RHEL, Arch, openSUSE
  • Pairing token per start; five wrong tokens lock pairing for one minute
  • Proprietary license; binary attached to each GitHub release
VallentaAgent on GitHub
Roadmap

Coming soon

  • Attaching to a running Linux process
  • Encrypted control channel
  • Network discovery of agents
  • Agent self-update

Linux64 debugging with Vallenta Studio Pro

Included in the Pro plan as a beta. Every Pro feature is available free for 5 days after registration.

Get Started FreeCompare Plans