Debug

Java debugger is deployed with the workspace agent, i.e. runs in the workspace. It can connect to local processes (those running in a workspace) or remote ones.

Breakpoints are set with a single click on a line number in the editor. You can set breakpoints before attaching a debugger:

In a Debug Dialog (Run > Edit Debug Configurations…), choose if you want to attach to a process in a local workspace or a remote machine. If localhost is chosen, a drop down menu will show all ports that are exposed in a container. You may either choose an existing port or provide your own.

Java Console Apps

To debug console apps, pass debug arguments to JVM:

Java Web Apps

To debug a web application, you need to start a web server in a debug mode. Debug arguments may vary depending on the web server in use. For example, to start Tomcat in a debug mode, run: st

You can add debug commands to CMD widget to permanently save them with the workspace config.

Java debugger supports the following features:

GDB can be used to debug *C/C+* and *Node.js* projects. In Docker 1.13, a container requires certain capabilities for gdb and gdbserver to start. In che.env uncomment the following line and restart Che:

Compile your app with -g argument, go to Run > Edit Debug Configurations > GDB. Create a new configuration, check Debug local binary box. By default, binary path is ${current.project.path/a.out}. When the debugger attaches, this macro is translated into an absolute path to a currently selected project. a.out is the default binary name. If you have compiled binary with a different name, change it:

Set a breakpoint in code, go to Run > Debug > YourDebugConfiguration. Once a debugger attaches, there’s a notification in the top right corner. A debugger panel will open.

Similar to Java debugger, one needs to start a process that a debugger will connect to. In case of GDB, this is gdbserver which is installed in C/CPP runtime by default.

To run gdbserver, execute the following:

gdbserver :$port /path/to/binary/file where $port is a random port that you will then connect to. It is important to provide an absolute path to a binary file if you run gdbserver in a command.

It is important to make sure that the binary has been compiled with -g argument, i.e. with attached sources.

When gdbserver starts, it produces some output with info on process ID and port it’s listening on. When a remote client connects to gdbserver, there will be a message with IP address of a remote connection.

To stop gdbserver, terminate the command in Consoles panel (if the server has been started as a command). If gdbserver has been started in a terminal, Ctrl+C does not kill it. Open another terminal into a machine, and run:

kill $(ps ax | grep "[g]dbserver" | awk {'print $1;}')

This commands grabs gdbserver PID and kills the process.

Connect to GDB server

Go to Run > Edit Debug Configurations and enter host (localhost if gdbserver has been started in the same workspace environment), port and path to the binary file being debugged. By default, binary name is a.out. If you have compiled your binary with -o argument, you need to provide own custom binary name in a debug configuration.

Save your configuration, choose it at Run > Debug > <YourDebugConfiguration> and attach the debugger, having previously set breakpoints in source files.

Connection Timeouts

Latency or poor connectivity may cause issues with remote debugging. A local GDB may fail to receive a timely response from the remote server. To fix it, set a default timeout for a local GDB. In the terminal, run:

You may set a bigger timeout, say, 20 seconds, if there are serious connectivity issues with a remote GDB server.

It is also possible to add this command as a Dockerfile instruction for a custom recipe:

The PHP and Zend stacks come with the Zend Debugger module installed and configured. Debugging both PHP CLI scripts and PHP web apps is supported.

The debugging workflow involves the following steps:

\{\{site.product_formal_name}} has the Zend Debugger Client integrated in the Web IDE. For launching the Zend Debugger Client:

The successful launch of the Zend Debugger Client is noted with a notification message. From this moment on the Zend Debugger Client listens for new debug sessions initiated by the Zend Debugger module of the PHP engine.

The Debug Configuration window allows the following configuration for the Zend Debugger Client:

PHP CLI scripts can be debugged by setting the QUERY_STRING environment variable when executing the PHP script. For example, to debug the hello.php script you should execute the following command in the Terminal:

Let’s dissect the value of the QUERY_STRING:

For convenience the PHP and Zend stacks have the debug php script command. It will run the PHP script, which is currently opened in the editor, with the required QUERY_STRING preprended to the launch command. It is a handy way for easily debugging CLI script without the need to remember the exact QUERY_STRING variable.

Debugging web apps is done in a similar way. The value of the QUERY_STRING used for debugging CLI scripts must be added as a query string to the URL of the debugged web page. This can be done either manually or by using a browser toolbar/extension that does it automatically. Such browser extensions also make it easier to debug POST requests.

Using Query Params in URL

The ?start_debug=1&debug_host=localhost&debug_port=10137 query string must be added to the URL. For example, to debug the http://localhost:32810/web-php-simple/index.php web page you should request the following URL in the browser:

The zDebug extension can be used for easier triggering of debug sessions from the Chrome browser. The Zend Debugger Extension is another extension that does the same job.

It is important to configure the Chrome extension properly before using it for debugging PHP apps running in a \{\{site.product_mini_name}} workspace:

Note that it is not the browser that opens the debug session to the Zend Debugger Client. This is done by the PHP engine that runs in the \{\{site.product_mini_name}} workspace. The browser just tells the PHP engine to do so. So the above settings are for the PHP engine (the Zend Debugger module in particular). Thus the Debug Host must be set to localhost and not the public host of the docker container running the \{\{site.product_mini_name}} workspace.

In the end the zDebug settings should look like this:

Now you are ready to trigger the debug session:

The Zend Debugger Toolbar for Firefox can be used for easier triggering of debug sessions from the Firefox browser.

After installing it, go to Extra Stuff > Setttings to configure the toolbar:

In the end the toolbar settings should look like this:

Now you are ready to trigger the debug session:

Z-Ray is a productivity tool, part of Zend Server, that is available in the Zend stack. Z-Ray requires no installation or configuraton. It is injected into the response coming from your PHP app and shown right in the browser you are using for development.

Among other features, it also has the capability to trigger a debug session:

That’s all!

The Node.js ready-to-go stack comes with a Node.js debugger module installed and configured. The Dockerfile is located in the eclipse/che-dockerfiles repository.

The debugging workflow is:

You can set breakpoints in the editor at any time by clicking on the line number.

Starting Node.js Debugger Client

\{\{site.product_formal_name}} has the Node.js client integrated in the web IDE. to launch the debugger client:

Creating a Command with Preview URL

\{\{site.product_formal_name}}’s workspaces have machine(s) that are docker container(s). Docker container’s exposed ports are given an ephemeral port. The preview url provides an easy way convert an internal port to it’s external ephemeral port counter part.