Skip to content

Commit ff82e45

Browse files
akaromlakaroml
authored
Getting Started - Debugging (#186)
Signed-off-by: Rome Li <[email protected]>
1 parent 034fd16 commit ff82e45

File tree

1 file changed

+88
-2
lines changed

1 file changed

+88
-2
lines changed

‎src/getting-started/assets/index.html‎

Lines changed: 88 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ <h3 class="font-weight-light">Create a Class</h3>
8181
</blockquote>
8282
<h3 class="font-weight-light">Run the program</h3>
8383
<p>
84-
To run the program, press <a href="command:workbench.action.debug.start"><kbd>F5</kbd></a>. By default, the program is launched in the <a href="command:workbench.action.terminal.toggleTerminal">Intergrated Terminal</a>. You should already see the output there.
84+
To run the program, press <a href="command:workbench.action.debug.start"><kbd>F5</kbd></a>. By default, the program is launched in the <a href="command:workbench.action.terminal.toggleTerminal">Integrated Terminal</a>. You should already see the output there.
8585
</p>
8686
<blockquote class="card-body">
8787
<h5 class="font-weight-light">How to Debug?</h5>
@@ -208,7 +208,93 @@ <h3 class="font-weight-light">Next Steps</h3>
208208

209209
<!-- Debugging -->
210210
<div class="tab-pane fade" id="debugging-panel" role="tabpanel" aria-labelledby="debugging-tab">
211-
<p>How to use the debugger</p>
211+
<p>
212+
One of the key features of Visual Studio Code is its great debugging support. VS Code's built-in debugger helps accelerate your edit, compile and debug loop.
213+
</p>
214+
<h3 class="font-weight-light">Start Debugging</h3>
215+
<p>
216+
There are multiple ways to start debugging a Java program. By pressing <a href="command:workbench.action.debug.start"><kbd>F5</kbd></a>, the current program will be launched. You can also start by clicking the <strong>"Debug"</strong> codelens on top of the <code>main</code> function. This is super handy when you have multiple main entries. You can also launch a program <strong>without</strong> debugging by pressing <a href="command:workbench.action.debug.run"><kbd data-os="win">Ctrl + F5</kbd><kbd data-os="mac">⌃ F5</kbd></a>.
217+
</p>
218+
<p>
219+
By default, VS Code Java launches the program using <a href="command:workbench.action.terminal.toggleTerminal">Integrated Terminal</a>. As you enter the debug mode, you should also see the <a href="command:workbench.view.debug">Debug View</a>. This view shows all the runtime info of your program.
220+
</p>
221+
<blockquote class="card-body">
222+
<h5 class="font-weight-light">Debug Configurations</h5>
223+
<p class="mb-0">
224+
VS Code Java automatically generates debug configurations. In VS Code, those configurations are called <a href="https://code.visualstudio.com/docs/editor/debugging#_launch-configurations">Launch Configurations</a> and they are persisted in <code data-os="win">.vscode\launch.json</code><code data-os="mac">.vscode/launch.json</code>. To work with more sophisticated debug scenarios, please explore the <a href="https://code.visualstudio.com/docs/editor/debugging#_launchjson-attributes">Launch Options</a> that are supported by VS Code.
225+
</p>
226+
</blockquote>
227+
<h3 class="font-weight-light">Breakpoints</h3>
228+
<p>
229+
Breakpoints can be toggled by clicking on the editor margin or using <kbd>F9</kbd> on the current line. Finer breakpoint control (enable/disable/reapply) can be done in the Debug View's BREAKPOINTS section.
230+
</p>
231+
<p>
232+
You can also set <strong>Conditional Breakpoints</strong> based on expressions, hit counts, or a combination of both.
233+
</p>
234+
<dl class="row">
235+
<dt class="col-sm-3">Expression condition</dt>
236+
<dd class="col-sm-9">The breakpoint will be hit whenever the expression evaluates to <code>true</code></dd>
237+
<dt class="col-sm-3">Hit count</dt>
238+
<dd class="col-sm-9">The 'hit count' controls how many times a breakpoint needs to be hit before it will 'break' execution</dd>
239+
</dl>
240+
<p>
241+
You can add a condition and/or hit count when creating the breakpoint (with the <a href="command:editor.debug.action.conditionalBreakpoint">Add Conditional Breakpoint</a> action) or when modifying an existing one (with the Edit Breakpoint action). In both cases, an inline text box with a drop-down menu opens where you can enter expressions.
242+
</p>
243+
<blockquote class="card-body">
244+
<h5 class="font-weight-light">Logpoints</h5>
245+
<p>
246+
A Logpoint is a variant of a breakpoint that does not "break" into the debugger but instead logs a message to the console. Logpoints are especially useful for injecting logging while debugging production servers that cannot be paused or stopped.
247+
</p>
248+
<p class="mb-0">
249+
A Logpoint is represented by a ♦️ shaped icon. Log messages are plain text but can include expressions to be evaluated within curly braces ('{}').
250+
</p>
251+
</blockquote>
252+
<h3 class="font-weight-light">Debug Actions</h3>
253+
<p>
254+
Once a debug session starts, the Debug toolbar will appear on the top of the editor. You can control the execution flow using the actions below.
255+
</p>
256+
<dl class="row">
257+
<dt class="col-sm-3">Continue/Pause</dt>
258+
<dd class="col-sm-9"><kbd>F5</kbd></dd>
259+
<dt class="col-sm-3">Step Over</dt>
260+
<dd class="col-sm-9"><kbd>F10</kbd></dd>
261+
<dt class="col-sm-3">Step Into</dt>
262+
<dd class="col-sm-9"><kbd>F11</kbd></dd>
263+
<dt class="col-sm-3">Step Out</dt>
264+
<dd class="col-sm-9"><kbd data-os="win">Shift + F11</kbd><kbd data-os="mac">⇧ F11</kbd></dd>
265+
<dt class="col-sm-3">Restart</dt>
266+
<dd class="col-sm-9"><kbd data-os="win">Ctrl + Shift + F5</kbd><kbd data-os="mac">⇧ ⌘ F5</kbd></dd>
267+
<dt class="col-sm-3">Stop</dt>
268+
<dd class="col-sm-9"><kbd data-os="win">Shift + F5</kbd><kbd data-os="mac">⇧ F5</kbd></dd>
269+
</dl>
270+
<h3 class="font-weight-light">Inspect Variables</h3>
271+
<p>
272+
Variables can be inspected in the <strong>VARIABLES</strong> section of the Debug view or by hovering over their source in the editor. Variable values and expression evaluation are relative to the selected stack frame in the <strong>CALL STACK</strong> section.
273+
</p>
274+
<p>
275+
Variable values can be modified with the <strong>Set Value</strong> action from the variable's context menu. Or you can <strong>double-click</strong> the value and enter a new one. Variables and expressions can also be evaluated and watched in the Debug view's <strong>WATCH</strong> section.
276+
</p>
277+
<h3 class="font-weight-light">Hot Code Replace ⚡</h3>
278+
<p>
279+
Yes, you can apply code changes without restarting the running program. Click on the <a href="command:java.debug.hotCodeReplace">⚡</a> icon in the <strong>debug toolbar</strong> to apply code changes. When you see failures, don't worry. It is safe to continue running the program, but you may notice discrepancies between the source code and the program.
280+
</p>
281+
<blockquote class="card-body">
282+
<h5 class="font-weight-light">Limitations</h5>
283+
<p>
284+
Hot Code Replace (HCR) sounds magical but it does have limitations. In short, you can only change the code inside an existing function. Here are some scenarios that HCR will <span class="text-danger">NOT</span> work:
285+
</p>
286+
<ul class="mb-0">
287+
<li>Adding a new member function</li>
288+
<li>Changing the signature of an existing function</li>
289+
<li>Changing the value of static members (but you can do so using the VARIABLES panel when the program is paused)</li>
290+
<li>Referencing new classes/packages</li>
291+
</ul>
292+
</blockquote>
293+
<h3 class="font-weight-light">Next Step</h3>
294+
<dl class="row mb-0" id="navigationPanel">
295+
<dt class="col-sm-3"><a href="#faq-tab">FAQ</a></dt>
296+
<dd class="col-sm-9">Frequently asked questions</dd>
297+
</dl>
212298
</div>
213299

214300
<!-- Projects & Dependencies -->

0 commit comments

Comments
 (0)