|
|
(3 intermediate revisions by the same 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>.
| + | |
− | | + | |
− | <img src=../images/trace_options.png>
| + | |
− | | + | |
− | '''Figure 6.1'''
| + | |
− | 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>
| + | |