Jump to: navigation, search

Difference between revisions of "FAQ How do I use the platform debug tracing facility?"

m (Changed 2nd wrong snytax of special chars)
(Replaced content with "See https://wiki.eclipse.org/FAQ_How_do_I_use_the_platform_debug_tracing_facility")
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
== Adding tracing to your code ==
+
See https://wiki.eclipse.org/FAQ_How_do_I_use_the_platform_debug_tracing_facility
During development, it is common practice to print debugging messages to standard output.  One common idiom for doing this is
+
<source lang="java">
+
  private static final boolean DEBUG = true;
+
  ...
+
  if (DEBUG)
+
      System.out.println("So far so good");
+
</source>
+
 
+
The advantage of this approach is that you can flip the <tt>DEBUG</tt>
+
field to <tt>false</tt> when it comes time to deploy your code.  The Java
+
compiler will then remove the entire <tt>if</tt> block from the class file
+
as flow analysis reveals that it is unreachable.  The downside of this
+
approach is that all the hard work that went into writing useful debug statements
+
is lost in the deployed product.  If your user calls up with a problem, you will have
+
to send a new version of your libraries with the debug switches turned on
+
before you can get useful feedback.  Eclipse provides a tracing facility that is turned
+
off by default but can be turned on in the field with a few simple steps.
+
 
+
To instrument your code, use the methods <tt>Plugin.isDebugging</tt> and
+
<tt>Platform.getDebugOption</tt> to add conditions to your trace statements:
+
<source lang="java">
+
  private static final String DEBUG_ONE =
+
      "org.eclipse.faq.examples/debug/option1";
+
  ...
+
  String debugOption = Platform.getDebugOption(DEBUG_ONE);
+
  if (ExamplesPlugin.getDefault().isDebugging() &&
+
              "true".equalsIgnoreCase(debugOption))
+
      System.out.println("Debug statement one.");
+
</source>
+
 
+
This approach will also allow you to turn on tracing dynamically using the method
+
<tt>Plugin.setDebugging</tt>.  This can be very useful while debugging if you
+
want to limit the amount of trace output that is seen.  You simply start with tracing
+
off and then turn it on when your program reaches a state at which tracing is useful.
+
 
+
If you do not need dynamic trace enablement or if you are concerned about code
+
clutter or performance, another tracing style yields cleaner and faster source:
+
<source lang="java">
+
  private static final boolean DEBUG_TWO =
+
      ExamplesPlugin.getDefault().isDebugging() &&
+
        "true".equalsIgnoreCase(Platform.getDebugOption(
+
        "org.eclipse.faq.examples/debug/option2"));
+
  ...
+
  if (DEBUG_TWO)
+
      System.out.println("Debug statement two.");
+
</source>
+
 
+
This tracing style is not quite as good as the standard approach outlined at the beginning
+
of this FAQ.  Because the debug flag cannot be computed statically, the compiler will not be able to
+
completely optimize out the tracing code.  You will still be left with the extra code
+
bulk, but the performance will be good enough for all but the most extreme applications.
+
 
+
== Turning on debug tracing ==
+
To turn tracing on, you need to create a trace-options file that contains a list
+
of the debug options that you want to turn on.  By default, the platform
+
looks for a file called <tt>.options</tt> in the Eclipse install directory.  This should
+
be a text file in the Java properties file format, with one <tt>key=value</tt>
+
pair per line.  To turn on the trace options in the preceding two examples, you
+
need an options file that looks like this:
+
<pre>
+
  org.eclipse.faq.examples/debug=true
+
  org.eclipse.faq.examples/debug/option1=true
+
  org.eclipse.faq.examples/debug/option2=true
+
</pre>
+
The first line sets the value of the flag returned by <tt>Plugin.isDebugging</tt>,
+
and the next two lines define the debug option strings returned by the
+
<tt>getDebugOption</tt> method on <tt>Platform</tt>.
+
 
+
<i>Hint</i>: If you use tracing in your plug-in, you should keep in your
+
plug-in install directory a <tt>.options</tt> file that contains
+
a listing of all the possible trace options for your plug-in.
+
This advertises your tracing facilities to prospective users and developers;
+
in addition, the Run-time Workbench launch configuration will
+
detect this file and use it to populate the Tracing Options
+
page (Figure 6.1).  If you browse through the plug-in directories of the
+
Eclipse SDK, you will see that several plug-ins use this technique
+
to document their trace options; for example, see
+
<tt>org.eclipse.core.resources</tt> or <tt>org.eclipse.jdt.core</tt>.
+
 
+
&nbsp;&nbsp;&nbsp;&nbsp;<img src=../images/trace_options.png>
+
 
+
&nbsp;&nbsp;&nbsp;&nbsp;'''Figure 6.1'''&nbsp;&nbsp;
+
Tracing Options page
+
 
+
Finally, you need to enable the tracing mechanism by starting Eclipse with the
+
<tt>-debug</tt> command line argument.  You can, optionally,
+
specify the location of the debug options file as either a URL or a file-system path
+
after the <tt>-debug</tt> argument.
+
 
+
<hr><font size=-2>This FAQ was originally published in [http://www.eclipsefaq.org Official Eclipse 3.0 FAQs]. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License v1.0].</font>
+

Latest revision as of 02:17, 13 July 2014

See https://wiki.eclipse.org/FAQ_How_do_I_use_the_platform_debug_tracing_facility