docs/ide/debug/index.html - gerrit/www.eclipse.org/che - Git at Google



 <!-- jQuery Eclipse IP approval https://dev.eclipse.org/ipzilla/show_bug.cgi?id=10801 -->
 <script type="text/javascript" charset="utf8" src="../../../docs/assets/scripts/jquery-1.8.1.min.js"></script>

 <script type="text/javascript" charset="utf8">
   $(document).ready(function(){
     var images = document.getElementsByTagName('img');
     for (var i = 0; i < images.length; i++) {
       var image = images[i];
       var parentElement = image.parentElement;
       var a = document.createElement('a');
       if (! image.getAttribute('src').includes("logo-codenvy.svg") && ! image.getAttribute('src').includes("codenvy-contribute.svg") ){
           a.href = image.getAttribute('src');
           a.target = "_blank";
           a.appendChild(image);
           parentElement.appendChild(a);
       }
     }
   });
 </script>
 <!DOCTYPE HTML>
 <html lang="en-US">
 <head>
   <title>Debug -

       Docs
      - Eclipse Che</title>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width,initial-scale=1">
   <meta name="generator" content="Jekyll v3.5.1">
   <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
   <link rel="stylesheet" href="../../../docs/assets/css/screen.css">
   <link rel="icon" type="image/x-icon" href="../../../docs/assets/imgs/favicon.ico">
   <!--[if lt IE 9]>
   <script src="/js/html5shiv.min.js"></script>
   <script src="/js/respond.min.js"></script>
   <![endif]-->
 </head>


 <body class="wrap">


 <header>
   <nav class="mobile-nav show-on-mobiles">
     <ul>

   <li class="current">
     <a href="../../../docs/index.html">Docs</a>
   </li>
   <li class="">
     <a href="../../../docs/tutorials/multi-machine/index.html">Tutorials</a>
   </li>
   <li class="">
     <a href="../../../docs/openshift/config/index.html">OpenShift</a>
   </li>
   <li>
     <a href="https://github.com/eclipse/che-docs/tree/master/src/main">GitHub</a>
   </li>
 </ul>

   </nav>
   <div class="grid">
     <div class="unit one-third center-on-mobiles">
         <a href="https://eclipse.org/che/">
           <span class="sr-only">Eclipse Che</span>
           <img src="../../../docs/assets/imgs/logo-eclipseche.svg" alt="Eclipse Che Logo"  width="249" height="115">
         </a>
     </div>
     <nav class="main-nav unit two-thirds hide-on-mobiles">
       <ul>

   <li class="current">
     <a href="../../../docs/index.html">Docs</a>
   </li>
   <li class="">
     <a href="../../../docs/tutorials/multi-machine/index.html">Tutorials</a>
   </li>
   <li class="">
     <a href="../../../docs/openshift/config/index.html">OpenShift</a>
   </li>
   <li>
     <a href="https://github.com/eclipse/che-docs/tree/master/src/main">GitHub</a>
   </li>
 </ul>

     </nav>
   </div>
 </header>


     <section class="docs">
     <div class="grid">

       <div class="docs-nav-mobile unit whole show-on-mobiles">
   <select onchange="if (this.value) window.location.href=this.value">
     <option value="">Navigate the docs…</option>


     <optgroup label="SETUP">


 <ul>


     <option value="../../../docs/index.html">Introduction</option>


     <option value="../../../docs/setup/getting-started/index.html">Getting Started&#58 Local</option>


     <option value="../../../docs/setup/getting-started-saas-cloud/index.html">Getting Started&#58 SaaS Cloud</option>


     <option value="../../../docs/setup/configuration/index.html">Configuration</option>


     <option value="../../../docs/setup/managing/index.html">Managing</option>


     <option value="../../../docs/setup/cli/index.html">CLI Reference</option>


     <option value="../../../docs/setup/glossary/index.html">Glossary</option>


     <option value="../../../docs/setup/docker/index.html">Docker Installation</option>


     <option value="../../../docs/setup/openshift/index.html">OpenShift Installation</option>


     <option value="../../../docs/setup/selenium/index.html">How to run selenium tests</option>


 </ul>


 <ul>


     <li class=""><a href="../../../docs/index.html">Introduction</a></li>


     <li class=""><a href="../../../docs/setup/getting-started/index.html">Getting Started&#58 Local</a></li>


     <li class=""><a href="../../../docs/setup/getting-started-saas-cloud/index.html">Getting Started&#58 SaaS Cloud</a></li>


     <li class=""><a href="../../../docs/setup/configuration/index.html">Configuration</a></li>


     <li class=""><a href="../../../docs/setup/managing/index.html">Managing</a></li>


     <li class=""><a href="../../../docs/setup/cli/index.html">CLI Reference</a></li>


     <li class=""><a href="../../../docs/setup/glossary/index.html">Glossary</a></li>


     <li class=""><a href="../../../docs/setup/docker/index.html">Docker Installation</a></li>


     <li class=""><a href="../../../docs/setup/openshift/index.html">OpenShift Installation</a></li>


     <li class=""><a href="../../../docs/setup/selenium/index.html">How to run selenium tests</a></li>


 </ul>


     </optgroup>


     <optgroup label="WORKSPACE ADMINISTRATION">


 <ul>


     <option value="../../../docs/devops/intro/index.html">Introduction</option>


     <option value="../../../docs/devops/runtime-stacks/index.html">Runtime Stacks</option>


     <option value="../../../docs/devops/runtime-recipes/index.html">Runtime Recipes</option>


     <option value="../../../docs/devops/project-samples/index.html">Project Samples</option>


     <option value="../../../docs/devops/runtime-machines/index.html">Runtime Machines</option>


     <option value="../../../docs/devops/volume-mounts/index.html">Volume Mounts</option>


     <option value="../../../docs/devops/ws-agents/index.html">Workspace Agents</option>


     <option value="../../../docs/devops/workspaces-data-model/index.html">Workspace Data Model</option>


     <option value="../../../docs/devops/runtime-stacks-data-model/index.html">Runtime Stacks Data Model</option>


     <option value="../../../docs/devops/project-samples-data-model/index.html">Project Samples Data Model</option>


 </ul>


 <ul>


     <li class=""><a href="../../../docs/devops/intro/index.html">Introduction</a></li>


     <li class=""><a href="../../../docs/devops/runtime-stacks/index.html">Runtime Stacks</a></li>


     <li class=""><a href="../../../docs/devops/runtime-recipes/index.html">Runtime Recipes</a></li>


     <li class=""><a href="../../../docs/devops/project-samples/index.html">Project Samples</a></li>


     <li class=""><a href="../../../docs/devops/runtime-machines/index.html">Runtime Machines</a></li>


     <li class=""><a href="../../../docs/devops/volume-mounts/index.html">Volume Mounts</a></li>


     <li class=""><a href="../../../docs/devops/ws-agents/index.html">Workspace Agents</a></li>


     <li class=""><a href="../../../docs/devops/workspaces-data-model/index.html">Workspace Data Model</a></li>


     <li class=""><a href="../../../docs/devops/runtime-stacks-data-model/index.html">Runtime Stacks Data Model</a></li>


     <li class=""><a href="../../../docs/devops/project-samples-data-model/index.html">Project Samples Data Model</a></li>


 </ul>


     </optgroup>


     <optgroup label="USER GUIDE">


 <ul>


     <option value="../../../docs/ide/projects/index.html">Projects</option>


     <option value="../../../docs/ide/import-a-project/index.html">Import</option>


     <option value="../../../docs/ide/ssh/index.html">SSH</option>


     <option value="../../../docs/ide/sync/index.html">Local IDE Sync</option>


     <option value="../../../docs/ide/editor-settings/index.html">Editor</option>


     <option value="../../../docs/ide/intellisense/index.html">Intellisense</option>


     <option value="../../../docs/ide/commands/index.html">Commands</option>


     <option value="../../../docs/ide/git-svn/index.html">Git and SVN</option>


     <option value="../../../docs/ide/previews/index.html">Previews</option>


     <option value="../../../docs/ide/build/index.html">Build</option>


     <option value="../../../docs/ide/run/index.html">Run</option>


     <option value="../../../docs/ide/sharing/index.html">Share</option>


     <option value="../../../docs/ide/debug/index.html">Debug</option>


     <option value="../../../docs/ide/docker/index.html">Docker</option>


     <option value="../../../docs/ide/electron/index.html">Install Che Desktop Client</option>


 </ul>


 <ul>


     <li class=""><a href="../../../docs/ide/projects/index.html">Projects</a></li>


     <li class=""><a href="../../../docs/ide/import-a-project/index.html">Import</a></li>


     <li class=""><a href="../../../docs/ide/ssh/index.html">SSH</a></li>


     <li class=""><a href="../../../docs/ide/sync/index.html">Local IDE Sync</a></li>


     <li class=""><a href="../../../docs/ide/editor-settings/index.html">Editor</a></li>


     <li class=""><a href="../../../docs/ide/intellisense/index.html">Intellisense</a></li>


     <li class=""><a href="../../../docs/ide/commands/index.html">Commands</a></li>


     <li class=""><a href="../../../docs/ide/git-svn/index.html">Git and SVN</a></li>


     <li class=""><a href="../../../docs/ide/previews/index.html">Previews</a></li>


     <li class=""><a href="../../../docs/ide/build/index.html">Build</a></li>


     <li class=""><a href="../../../docs/ide/run/index.html">Run</a></li>


     <li class=""><a href="../../../docs/ide/sharing/index.html">Share</a></li>


     <li class="current"><a href="../../../docs/ide/debug/index.html">Debug</a></li>


     <li class=""><a href="../../../docs/ide/docker/index.html">Docker</a></li>


     <li class=""><a href="../../../docs/ide/electron/index.html">Install Che Desktop Client</a></li>


 </ul>


     </optgroup>


     <optgroup label="PORTABLE WORKSPACES">


 <ul>


     <option value="../../../docs/chedir/getting-started/index.html">Chedir - Getting Started</option>


     <option value="../../../docs/chedir/why/index.html">Chedir - Why Chedir?</option>


     <option value="../../../docs/chedir/installation/index.html">Chedir - Installation</option>


     <option value="../../../docs/chedir/project-setup/index.html">Chedir - Project Setup</option>


     <option value="../../../docs/chedir/up-and-down/index.html">Chedir - Up and Down</option>


     <option value="../../../docs/chedir/chefiles/index.html">Chedir - Chefile</option>


     <option value="../../../docs/chedir/ssh/index.html">Chedir - SSH</option>


     <option value="../../../docs/chedir/factories/index.html">Chedir - Factories</option>


     <option value="">Error Generating Page Link. Contact Maintainer./docs/factory-getting-started/</option>


     <option value="">Error Generating Page Link. Contact Maintainer./docs/factory-creating/</option>


     <option value="">Error Generating Page Link. Contact Maintainer./docs/factory-json-reference/</option>


 </ul>


 <ul>


     <li class=""><a href="../../../docs/chedir/getting-started/index.html">Chedir - Getting Started</a></li>


     <li class=""><a href="../../../docs/chedir/why/index.html">Chedir - Why Chedir?</a></li>


     <li class=""><a href="../../../docs/chedir/installation/index.html">Chedir - Installation</a></li>


     <li class=""><a href="../../../docs/chedir/project-setup/index.html">Chedir - Project Setup</a></li>


     <li class=""><a href="../../../docs/chedir/up-and-down/index.html">Chedir - Up and Down</a></li>


     <li class=""><a href="../../../docs/chedir/chefiles/index.html">Chedir - Chefile</a></li>


     <li class=""><a href="../../../docs/chedir/ssh/index.html">Chedir - SSH</a></li>


     <li class=""><a href="../../../docs/chedir/factories/index.html">Chedir - Factories</a></li>


     <li class=""><a href="../../../docs/factory/getting-started/index.html">Factory - Getting Started</a></li>


     <li class=""><a href="../../../docs/factory/creating/index.html">Factory - Creating</a></li>


     <li class=""><a href="../../../docs/factory/json-reference/index.html">Factory - JSON Reference</a></li>


 </ul>


     </optgroup>


     <optgroup label="DEVELOPER GUIDE - REST API">


 <ul>


     <option value="../../../docs/assemblies/intro/index.html">Introduction</option>


     <option value="../../../docs/assemblies/archetype/index.html">Archetype</option>


     <option value="../../../docs/assemblies/assembly-lifecycle/index.html">Assembly Dev Lifecycle</option>


     <option value="../../../docs/assemblies/plugin-lifecycle/index.html">Plugin Lifecycle</option>


     <option value="../../../docs/assemblies/sdk-rest-apis/index.html">SDK REST APIs</option>


     <option value="../../../docs/assemblies/sdk-class-reference/index.html">SDK Class Reference</option>


     <option value="../../../docs/assemblies/sdk-dependency-injection/index.html">SDK Dependency Injection</option>


     <option value="../../../docs/assemblies/sdk-dto/index.html">SDK DTOs</option>


     <option value="../../../docs/assemblies/sdk-properties/index.html">SDK Properties</option>


     <option value="../../../docs/assemblies/sdk-code-editors/index.html">SDK Editors</option>


     <option value="../../../docs/assemblies/sdk-embed-htmljs/index.html">SDK Embedded JavaScript</option>


     <option value="../../../docs/assemblies/sdk-project-types/index.html">SDK Project Types</option>


     <option value="../../../docs/assemblies/sdk-actions/index.html">SDK Actions</option>


     <option value="../../../docs/assemblies/sdk-services/index.html">SDK Services</option>


     <option value="../../../docs/assemblies/sdk-parts/index.html">SDK Parts</option>


     <option value="../../../docs/assemblies/sdk-themes/index.html">SDK Themes</option>


     <option value="../../../docs/assemblies/sdk-custom-agents/index.html">SDK Custom Agents</option>


     <option value="../../../docs/assemblies/sdk-language-server-protocol/index.html">SDK Language Server Protocol</option>


     <option value="../../../docs/assemblies/sdk-workspace/index.html">SDK Workspace</option>


 </ul>


 <ul>


     <li class=""><a href="../../../docs/assemblies/intro/index.html">Introduction</a></li>


     <li class=""><a href="../../../docs/assemblies/archetype/index.html">Archetype</a></li>


     <li class=""><a href="../../../docs/assemblies/assembly-lifecycle/index.html">Assembly Dev Lifecycle</a></li>


     <li class=""><a href="../../../docs/assemblies/plugin-lifecycle/index.html">Plugin Lifecycle</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-rest-apis/index.html">SDK REST APIs</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-class-reference/index.html">SDK Class Reference</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-dependency-injection/index.html">SDK Dependency Injection</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-dto/index.html">SDK DTOs</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-properties/index.html">SDK Properties</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-code-editors/index.html">SDK Editors</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-embed-htmljs/index.html">SDK Embedded JavaScript</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-project-types/index.html">SDK Project Types</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-actions/index.html">SDK Actions</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-services/index.html">SDK Services</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-parts/index.html">SDK Parts</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-themes/index.html">SDK Themes</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-custom-agents/index.html">SDK Custom Agents</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-language-server-protocol/index.html">SDK Language Server Protocol</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-workspace/index.html">SDK Workspace</a></li>


 </ul>


     </optgroup>


   </select>
 </div>


       <div class="unit four-fifths">
         <article>
           <div class="improve right hide-on-mobiles">
             <a href="https://github.com/codenvy/che-docs/blob/master/src/main/_docs/ide/ide-debug.md"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>
             <!--<a href="https://github.com/eclipse/che/blob/master/docs/_docs/ide/ide-debug.md"><i class="fa fa-pencil"></i> &nbsp;Improve this page</a>-->
           </div>
           <div class="doc-title">
             <h1>Debug</h1>
             <div class="doc-title-border">
             </div>
           </div>

 <p>Debuggers are included in Che for:</p>

 <ul>
   <li><a href="#java">Java</a></li>
   <li><a href="#gdb">C/C++</a> (via GDB)</li>
   <li><a href="#php">PHP</a> (via Zend debugger, zDebug and Z-Ray)</li>
   <li><a href="#nodejs">Node.js</a> (via GDB)</li>
 </ul>

 <h1 id="java">Java</h1>
 <p>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.</p>

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

 <p><img src="../../../docs/assets/imgs/breakpoint.png" alt="breakpoint.png" /></p>

 <p>In a Debug Dialog (<strong>Run &gt; Edit Debug Configurations…</strong>), 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.</p>

 <p><img src="../../../docs/assets/imgs/debug-configurations.png" alt="debug-configurations.png" /></p>

 <h2 id="java-console-apps">Java Console Apps</h2>
 <p>l
 To debug console apps, pass debug arguments to JVM:</p>

 <div class="language-shell highlighter-rouge"><pre class="highlight"><code>mvn clean install <span class="o">&amp;&amp;</span> java -jar -Xdebug -Xrunjdwp:transport<span class="o">=</span>dt_socket,address<span class="o">=</span>8000,server<span class="o">=</span>y,suspend<span class="o">=</span>y <span class="k">${</span><span class="nv">current</span><span class="p">.project.path</span><span class="k">}</span>/target/<span class="k">*</span>.jar
 </code></pre>
 </div>

 <h2 id="java-web-apps">Java Web Apps</h2>

 <p>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</p>
 <div class="language-text highlighter-rouge"><pre class="highlight"><code>$TOMCAT_HOME/bin/catalina.sh jpda run
 </code></pre>
 </div>

 <p>You can add debug commands to CMD widget to permanently save them with the workspace config.</p>
 <h1 id="gdb">GDB</h1>
 <p>GDB can be used to debug <strong>C/C++</strong> and <strong>Node.js</strong> projects. In Docker 1.13+, a container requires privileged mode for gdb and gdbserver to start. In <code class="highlighter-rouge">che.env</code> configure workspace container privileged mode and restart Che :</p>

 <div class="highlighter-rouge"><pre class="highlight"><code>Che_DOCKER_PRIVILEGED=false
 </code></pre>
 </div>

 <h2 id="debugging-local-binary">Debugging Local Binary</h2>

 <p>Compile your app with <code class="highlighter-rouge">-g</code> argument, go to <code class="highlighter-rouge">Run &gt; Edit Debug Configurations &gt; GDB</code>. Create a new configuration, check <code class="highlighter-rouge">Debug local binary</code> box. By default, binary path is <code class="highlighter-rouge">${current.project.path/a.out}</code>. When the debugger attaches, this macro is translated into an absolute path to a currently selected project. <code class="highlighter-rouge">a.out</code> is the default binary name. If you have compiled binary with a different name, change it:
 <img src="../../../docs/assets/imgs/debug.png" alt="debug.png" />
 Set a breakpoint in code, go to <code class="highlighter-rouge">Run &gt; Debug &gt; YourDebugConfiguration</code>. Once a debugger attaches, there’s a notification in the top right corner. A debugger panel will open.</p>

 <h2 id="remote-debugging-with-gdb-server">Remote Debugging with GDB server</h2>

 <p>Similar to Java debugger, one needs to start a process that a debugger will connect to. In case of GDB, this is <code class="highlighter-rouge">gdbserver</code> which is installed in C/CPP runtime by default.</p>

 <p>To <strong>run</strong> gdbserver, execute the following:</p>

 <p><code class="highlighter-rouge">gdbserver :$port /path/to/binary/file</code> where <code class="highlighter-rouge">$port</code> 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.</p>

 <p>It is important to make sure that the binary has been compiled with <code class="highlighter-rouge">-g</code> argument, i.e. with attached sources.</p>

 <p>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.</p>

 <p>To <strong>stop</strong> 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:</p>

 <p><code class="highlighter-rouge">kill $(ps ax | grep "[g]dbserver" | awk {'print $1;}')</code></p>

 <p>This commands grabs gdbserver PID and kills the process.</p>

 <h2 id="connect-to-gdb-server">Connect to GDB server</h2>

 <p>Go to <code class="highlighter-rouge">Run &gt; Edit Debug Configurations</code> 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 <code class="highlighter-rouge">a.out</code>. If you have compiled your binary with <code class="highlighter-rouge">-o</code> argument, you need to provide own custom binary name in a debug configuration.</p>

 <p>Save your configuration, choose it at <code class="highlighter-rouge">Run &gt; Debug &gt; &lt;YourDebugConfiguration&gt;</code> and attach the debugger, having previously set breakpoints in source files.</p>

 <h3 id="connection-timeouts">Connection Timeouts</h3>

 <p>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:</p>

 <div class="highlighter-rouge"><pre class="highlight"><code>echo  "set remotetimeout 10" &gt; ~/.gdbinit
 </code></pre>
 </div>

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

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

 <div class="language-shell highlighter-rouge"><pre class="highlight"><code>FROM eclipse/cpp_gcc
 RUN <span class="nb">echo</span>  <span class="s2">"set remotetimeout 10"</span> &gt; /home/user/.gdbinit
 </code></pre>
 </div>

 <h1 id="php">PHP</h1>

 <p>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.</p>

 <p>The debugging workflow involves the following steps:</p>

 <ol>
   <li>Launch the Zend Debugger Client to start listening for new debug sessions.</li>
   <li>Optionally set breakpoints in the PHP editor.</li>
   <li>Trigger a debug session from the CLI script or the web app.</li>
   <li>Use the Web IDE tooling to do the actual debugging.</li>
 </ol>

 <p><img src="../../../docs/assets/imgs/php-debugging.gif" alt="php-debugging.gif" /></p>

 <h2 id="starting-the-zend-debugger-client">Starting the Zend Debugger Client</h2>

 <p>Eclipse Che has the Zend Debugger Client integrated in the Web IDE. For launching the Zend Debugger Client:</p>

 <ol>
   <li>Go to <code class="highlighter-rouge">Run &gt; Edit Debug Configurations</code> from the main menu.</li>
   <li>Create new <code class="highlighter-rouge">PHP</code> configuration.</li>
   <li>Change any settings if necessary. The defaults are usually OK.</li>
   <li>Click the <code class="highlighter-rouge">Debug</code> button.</li>
 </ol>

 <p><img src="../../../docs/assets/imgs/php-debug-configuration.png" alt="php-debug-configuration.png" /></p>

 <p>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.</p>

 <p>The Debug Configuration window allows the following configuration for the Zend Debugger Client:</p>

 <ul>
   <li><code class="highlighter-rouge">Break at first line</code>. Determines whether to break the execution at the very first line, hit by the PHP interpreter. Enabled by default. It is useful to easily find the app’s entry point. You may want to switch this option off if you defined your own breakpoint and you are not interesting at breaking the execution at the first line.</li>
   <li><code class="highlighter-rouge">Client host/IP</code>. The host/IP on which to bind the server socket for listening for new debug sessions. The default host is <code class="highlighter-rouge">localhost</code>. Changing it should be only necessary if the PHP engine is running in a different workspace machine or outside of the Che workspace at all.</li>
   <li><code class="highlighter-rouge">Debug port</code>. The port on which to bind the server socket for listening for new debug sessions. The default port is <code class="highlighter-rouge">10137</code>. It should be rarely necessary to change it.</li>
   <li><code class="highlighter-rouge">Use SSL encryption</code>. Whether to use SSL encryption for the debugging communication between the PHP engine and the Zend Debugger Client. Disabled by default.</li>
 </ul>

 <h2 id="debugging-php-cli-scripts">Debugging PHP CLI Scripts</h2>

 <p>PHP CLI scripts can be debugged by setting the <code class="highlighter-rouge">QUERY_STRING</code> environment variable when executing the PHP script. For example, to debug the <code class="highlighter-rouge">hello.php</code> script you should execute the following command in the Terminal:</p>

 <div class="language-sh highlighter-rouge"><pre class="highlight"><code><span class="nv">QUERY_STRING</span><span class="o">=</span><span class="s2">"start_debug=1&amp;debug_host=localhost&amp;debug_port=10137"</span> php hello.php
 </code></pre>
 </div>

 <p>Let’s dissect the value of the <code class="highlighter-rouge">QUERY_STRING</code>:</p>

 <ul>
   <li><code class="highlighter-rouge">start_debug=1</code> says the PHP engine that we want to trigger a debug session for this execution.</li>
   <li><code class="highlighter-rouge">debug_host=localhost</code> says that the Zend Debugger Client runs on localhost (on the same host where the PHP engine runs).</li>
   <li><code class="highlighter-rouge">debug_port=10137</code> says that the Zend Debugger Client listens on port 10137.</li>
 </ul>

 <p>For convenience the PHP and Zend stacks have the <code class="highlighter-rouge">debug php script</code> command. It will run the PHP script, which is currently opened in the editor, with the required <code class="highlighter-rouge">QUERY_STRING</code> preprended to the launch command. It is a handy way for easily debugging CLI script without the need to remember the exact <code class="highlighter-rouge">QUERY_STRING</code> variable.</p>

 <h2 id="debugging-php-web-apps">Debugging PHP Web Apps</h2>

 <p>Debugging web apps is done in a similar way. The value of the <code class="highlighter-rouge">QUERY_STRING</code> 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.</p>

 <h3 id="using-query-params-in-the-url">Using Query Params in the URL</h3>

 <p>The <code class="highlighter-rouge">?start_debug=1&amp;debug_host=localhost&amp;debug_port=10137</code> query string must be added to the URL. For example, to debug the <code class="highlighter-rouge">http://localhost:32810/web-php-simple/index.php</code> web page you should request the following URL in the browser:</p>

 <div class="highlighter-rouge"><pre class="highlight"><code>http://localhost:32810/web-php-simple/index.php?start_debug=1&amp;debug_host=localhost&amp;debug_port=10137
 </code></pre>
 </div>

 <h3 id="using-the-zdebug-extension-for-chrome">Using the zDebug Extension for Chrome</h3>

 <p>The <a href="https://chrome.google.com/webstore/detail/zdebug/gknbnafalimbhgkmichoadhmkaoingil">zDebug</a> extension can be used for easier triggering of debug sessions from the Chrome browser. The <a href="https://chrome.google.com/webstore/detail/zend-debugger-extension/aonajadpeeaijblinaeohfdmbgdpibba">Zend Debugger Extension</a> is another extension that does the same job.</p>

 <p>It is important to configure the Chrome extension properly before using it for debugging PHP apps running in a Che workspace:</p>

 <ol>
   <li>Set <code class="highlighter-rouge">Debug Host</code> to <code class="highlighter-rouge">localhost</code> or <code class="highlighter-rouge">127.0.0.1</code>.</li>
   <li>Set <code class="highlighter-rouge">Debug Port</code> to <code class="highlighter-rouge">10137</code>.</li>
   <li>Set <code class="highlighter-rouge">Debug Local Copy</code> to <code class="highlighter-rouge">No</code>.</li>
 </ol>

 <p>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 Che 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 <code class="highlighter-rouge">Debug Host</code> must be set to <code class="highlighter-rouge">localhost</code> and not the public host of the docker container running the Che workspace.</p>

 <p>In the end the zDebug settings should look like this:</p>

 <p><img src="../../../docs/assets/imgs/zdebug-settings.png" alt="zdebug-settings.png" /></p>

 <p>Now you are ready to trigger the debug session:</p>

 <ol>
   <li>Open the web page to debug.</li>
   <li>Click on the zDebug toolbar button.</li>
   <li>Click on <code class="highlighter-rouge">This Page</code>.</li>
 </ol>

 <h3 id="using-the-zend-debugger-toolbar-for-firefox">Using the Zend Debugger Toolbar for Firefox</h3>

 <p>The <a href="https://addons.mozilla.org/firefox/addon/zend-debugger-toolbar/">Zend Debugger Toolbar for Firefox</a> can be used for easier triggering of debug sessions from the Firefox browser.</p>

 <p>After installing it, go to <code class="highlighter-rouge">Extra Stuff &gt; Setttings</code> to configure the toolbar:</p>

 <ol>
   <li>Disable the <code class="highlighter-rouge">Debug Local Copy</code> option.</li>
   <li>Switch the <code class="highlighter-rouge">Client/IDE Settings</code> to <code class="highlighter-rouge">Manual Settings</code>.</li>
   <li>Set <code class="highlighter-rouge">Debug Port</code> to <code class="highlighter-rouge">10137</code>.</li>
   <li>Set <code class="highlighter-rouge">IP Address</code> to <code class="highlighter-rouge">127.0.0.1</code>.</li>
 </ol>

 <p>In the end the toolbar settings should look like this:</p>

 <p><img src="../../../docs/assets/imgs/zend-debugger-firefox-settings.png" alt="zend-debugger-firefox-settings.png" /></p>

 <p>Now you are ready to trigger the debug session:</p>

 <ol>
   <li>Open the web page to debug.</li>
   <li>Click on the <code class="highlighter-rouge">Debug</code> toolbar button.</li>
 </ol>

 <h3 id="using-z-ray">Using Z-Ray</h3>

 <p><a href="http://www.zend.com/en/products/server/z-ray">Z-Ray</a> is a productivity tool, part of <a href="http://www.zend.com/en/products/zend_server">Zend Server</a>, 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.</p>

 <p>Among other features, it also has the capability to trigger a debug session:</p>

 <ol>
   <li>Click on the “bug” button.</li>
   <li>Click on <code class="highlighter-rouge">Debug current page</code>.</li>
 </ol>

 <p><img src="../../../docs/assets/imgs/z-ray-debug.png" alt="z-ray-debug.png" /></p>

 <p>That’s all!</p>

 <h1 id="nodejs">NodeJS</h1>

 <p>The Node.js ready-to-go <a href="../../../docs/devops/runtime-stacks/index.html">stack</a> comes with a Node.js debugger module installed and configured. The Dockerfile is located in the <a href="https://github.com/eclipse/che-dockerfiles/blob/master/recipes/node/Dockerfile">eclipse/che-dockerfiles</a> repository.</p>

 <p>The debugging workflow is:</p>

 <ol>
   <li>Launch the Node.js debugger client to start a debug session</li>
   <li>Create/Run command to generate a preview URL</li>
   <li>Click the preview URL to interact with the app</li>
   <li>Use the debugger panel to perform debug functions</li>
 </ol>

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

 <h2 id="starting-the-nodejs-debugger-client">Starting the Node.js Debugger Client</h2>

 <p>Eclipse Che has the Node.js client integrated in the web IDE. to launch the debugger client:</p>

 <ol>
   <li>Go to <code class="highlighter-rouge">Run &gt; Edit Debug Configurations</code> from the main menu</li>
   <li>Create a new <code class="highlighter-rouge">NODEJS</code> configuration</li>
   <li>Change any settings if necessary. The defaults are usually OK</li>
   <li>Click the <code class="highlighter-rouge">Debug</code> button</li>
   <li>The debugger will break at first line of code</li>
 </ol>

 <p><img src="../../../docs/assets/imgs/debug-nodejs-config.png" alt="debug-nodejs-config.png" /></p>

 <h3 id="creating-a-command-to-view-the-preview-url">Creating a Command to View the Preview URL</h3>

 <p>Eclipse Che’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.</p>

 <ol>
   <li>Add a command <code class="highlighter-rouge">Run &gt; Edit Commands</code></li>
   <li>Give the command a name like “View Preview URL”</li>
   <li>Add a fictitious command <code class="highlighter-rouge">echo</code> for required command line</li>
   <li>Provide the preview URL for your app such as <code class="highlighter-rouge">http://${server.port.&lt;port&gt;}/</code></li>
 </ol>

 <h3 id="using-the-nodejs-debugger">Using the Node.js Debugger</h3>

 <ol>
   <li>Start the debugger <code class="highlighter-rouge">Run &gt; debug &gt; &lt;config-name&gt;</code></li>
   <li>Click the continue button until server is running</li>
   <li>Add breakpoints if needed</li>
   <li>Run the preview URL command (see above)</li>
   <li>Click the preview URL to open web app in another tab</li>
   <li>Go back to IDE tab</li>
   <li>Use the Web IDE tooling to do the actual debugging</li>
 </ol>

 <p><img src="../../../docs/assets/imgs/nodejs-debugger-walkthru.gif" alt="nodejs-debugger-walkthru.gif" /></p>

         </article>
       </div>

       <div class="unit one-fifth hide-on-mobiles">
   <aside>


     <h4>SETUP</h4>


 <ul>


     <li class=""><a href="../../../docs/index.html">Introduction</a></li>


     <li class=""><a href="../../../docs/setup/getting-started/index.html">Getting Started&#58 Local</a></li>


     <li class=""><a href="../../../docs/setup/getting-started-saas-cloud/index.html">Getting Started&#58 SaaS Cloud</a></li>


     <li class=""><a href="../../../docs/setup/configuration/index.html">Configuration</a></li>


     <li class=""><a href="../../../docs/setup/managing/index.html">Managing</a></li>


     <li class=""><a href="../../../docs/setup/cli/index.html">CLI Reference</a></li>


     <li class=""><a href="../../../docs/setup/glossary/index.html">Glossary</a></li>


     <li class=""><a href="../../../docs/setup/docker/index.html">Docker Installation</a></li>


     <li class=""><a href="../../../docs/setup/openshift/index.html">OpenShift Installation</a></li>


     <li class=""><a href="../../../docs/setup/selenium/index.html">How to run selenium tests</a></li>


 </ul>


     <h4>WORKSPACE ADMINISTRATION</h4>


 <ul>


     <li class=""><a href="../../../docs/devops/intro/index.html">Introduction</a></li>


     <li class=""><a href="../../../docs/devops/runtime-stacks/index.html">Runtime Stacks</a></li>


     <li class=""><a href="../../../docs/devops/runtime-recipes/index.html">Runtime Recipes</a></li>


     <li class=""><a href="../../../docs/devops/project-samples/index.html">Project Samples</a></li>


     <li class=""><a href="../../../docs/devops/runtime-machines/index.html">Runtime Machines</a></li>


     <li class=""><a href="../../../docs/devops/volume-mounts/index.html">Volume Mounts</a></li>


     <li class=""><a href="../../../docs/devops/ws-agents/index.html">Workspace Agents</a></li>


     <li class=""><a href="../../../docs/devops/workspaces-data-model/index.html">Workspace Data Model</a></li>


     <li class=""><a href="../../../docs/devops/runtime-stacks-data-model/index.html">Runtime Stacks Data Model</a></li>


     <li class=""><a href="../../../docs/devops/project-samples-data-model/index.html">Project Samples Data Model</a></li>


 </ul>


     <h4>USER GUIDE</h4>


 <ul>


     <li class=""><a href="../../../docs/ide/projects/index.html">Projects</a></li>


     <li class=""><a href="../../../docs/ide/import-a-project/index.html">Import</a></li>


     <li class=""><a href="../../../docs/ide/ssh/index.html">SSH</a></li>


     <li class=""><a href="../../../docs/ide/sync/index.html">Local IDE Sync</a></li>


     <li class=""><a href="../../../docs/ide/editor-settings/index.html">Editor</a></li>


     <li class=""><a href="../../../docs/ide/intellisense/index.html">Intellisense</a></li>


     <li class=""><a href="../../../docs/ide/commands/index.html">Commands</a></li>


     <li class=""><a href="../../../docs/ide/git-svn/index.html">Git and SVN</a></li>


     <li class=""><a href="../../../docs/ide/previews/index.html">Previews</a></li>


     <li class=""><a href="../../../docs/ide/build/index.html">Build</a></li>


     <li class=""><a href="../../../docs/ide/run/index.html">Run</a></li>


     <li class=""><a href="../../../docs/ide/sharing/index.html">Share</a></li>


     <li class="current"><a href="../../../docs/ide/debug/index.html">Debug</a></li>


     <li class=""><a href="../../../docs/ide/docker/index.html">Docker</a></li>


     <li class=""><a href="../../../docs/ide/electron/index.html">Install Che Desktop Client</a></li>


 </ul>


     <h4>PORTABLE WORKSPACES</h4>


 <ul>


     <li class=""><a href="../../../docs/chedir/getting-started/index.html">Chedir - Getting Started</a></li>


     <li class=""><a href="../../../docs/chedir/why/index.html">Chedir - Why Chedir?</a></li>


     <li class=""><a href="../../../docs/chedir/installation/index.html">Chedir - Installation</a></li>


     <li class=""><a href="../../../docs/chedir/project-setup/index.html">Chedir - Project Setup</a></li>


     <li class=""><a href="../../../docs/chedir/up-and-down/index.html">Chedir - Up and Down</a></li>


     <li class=""><a href="../../../docs/chedir/chefiles/index.html">Chedir - Chefile</a></li>


     <li class=""><a href="../../../docs/chedir/ssh/index.html">Chedir - SSH</a></li>


     <li class=""><a href="../../../docs/chedir/factories/index.html">Chedir - Factories</a></li>


     <li class=""><a href="../../../docs/factory/getting-started/index.html">Factory - Getting Started</a></li>


     <li class=""><a href="../../../docs/factory/creating/index.html">Factory - Creating</a></li>


     <li class=""><a href="../../../docs/factory/json-reference/index.html">Factory - JSON Reference</a></li>


 </ul>


     <h4>DEVELOPER GUIDE - REST API</h4>


 <ul>


     <li class=""><a href="../../../docs/assemblies/intro/index.html">Introduction</a></li>


     <li class=""><a href="../../../docs/assemblies/archetype/index.html">Archetype</a></li>


     <li class=""><a href="../../../docs/assemblies/assembly-lifecycle/index.html">Assembly Dev Lifecycle</a></li>


     <li class=""><a href="../../../docs/assemblies/plugin-lifecycle/index.html">Plugin Lifecycle</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-rest-apis/index.html">SDK REST APIs</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-class-reference/index.html">SDK Class Reference</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-dependency-injection/index.html">SDK Dependency Injection</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-dto/index.html">SDK DTOs</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-properties/index.html">SDK Properties</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-code-editors/index.html">SDK Editors</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-embed-htmljs/index.html">SDK Embedded JavaScript</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-project-types/index.html">SDK Project Types</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-actions/index.html">SDK Actions</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-services/index.html">SDK Services</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-parts/index.html">SDK Parts</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-themes/index.html">SDK Themes</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-custom-agents/index.html">SDK Custom Agents</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-language-server-protocol/index.html">SDK Language Server Protocol</a></li>


     <li class=""><a href="../../../docs/assemblies/sdk-workspace/index.html">SDK Workspace</a></li>


 </ul>


   </aside>
 </div>


       <div class="clear"></div>

     </div>
   </section>


   <script>
   var anchorForId = function (id) {
     var anchor = document.createElement("a");
     anchor.className = "header-link";
     anchor.href      = "#" + id;
     anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
     anchor.title = "Permalink";
     return anchor;
   };

   var linkifyAnchors = function (level, containingElement) {
     var headers = containingElement.getElementsByTagName("h" + level);
     for (var h = 0; h < headers.length; h++) {
       var header = headers[h];

       if (typeof header.id !== "undefined" && header.id !== "") {
         header.appendChild(anchorForId(header.id));
       }
     }
   };

   document.onreadystatechange = function () {
     if (this.readyState === "complete") {
       var contentBlock = document.getElementsByClassName("artik")[0] || document.getElementsByClassName("openshift")[0] || document.getElementsByClassName("tutorials")[0] || document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
       if (!contentBlock) {
         return;
       }
       for (var level = 1; level <= 6; level++) {
         linkifyAnchors(level, contentBlock);
       }
     }
   };
 </script>


 </body>
 </html>