add more links to root README to cover all the debugging topics; refactor doc names & clean up missing content / dupe content / inaccurate content

Author: nickboldt

README.adoc

@@ -27,11 +27,18 @@ This repo should be considered a wiki, into which all developers can push docs.
 ** link:building/export_plugin_from_eclipse.adoc[Exporting plugins from eclipse]
 ** link:building/tycho.adoc[All about Tycho]
 *** link:building/how_to_test_tycho.adoc[How to test new versions of Tycho]
+
 * Testing & Debugging
-** link:debugging/runtime_workbench.adoc[Debugging via Runtime Workbench]
-** link:debugging/install_a_local_build.adoc[Installing a local build]
+** link:debugging/runtime_workbench.adoc[Debugging via Eclipse runtime workbench]
+** link:debugging/how_to_install_a_build.adoc[Installing a local build to Eclipse]
 ** link:debugging/how_to_test_a_build.adoc[Testing an installed build]
-** link:debugging/remote_debugging.adoc#Using-the-Eclipse-debugger[Debugging Surefire Tests w/ Eclipse Remote Debugger]
+** link:debugging/tracing_logging_in_eclipse.adoc[Tracing and logging in Eclipse]
+*** link:tracing_logging_in_eclipse.adoc#How-to-gather-eclipse-logs-and-system-configuration-details[How to gather Eclipse logs and system configuration details]
+*** link:tracing_logging_in_eclipse.adoc#How-to-enable-tracing-in-eclipse[How to enable tracing in Eclipse]
+** link:debugging/remote_debugging.adoc[Using the Eclipse remote debugger]
+** link:debugging/debug_tycho_tests.adoc[Debugging maven (surefire) tests]
+** link:debugging/debug_remote_console.adoc[Debugging on a remote server] (via SSH or VNC)
+
 * Source and Project Management
 ** link:source/new_project_process.adoc[Adding a new module / repository to JBoss Tools or JBDS]
 ** link:source/how_to_add_a_plugin_or_feature_to_an_existing_project.adoc[Adding a new plugin or feature to an existing JBoss Tools 4.x module]

debugging/README.adoc

@@ -0,0 +1,30 @@
+= Debugging on a remote server
+
+If a UI-based test running on a remote server stalls, it it often useful to be able to see that server's GUI to determine what caused the test to stall or fail.
+
+JBoss Tools' Jenkins jobs will often capture a screenshot of the last thing the slave's GUI saw before the test was terminated, which will appear in the job's workspace. But if this is insufficient, or if you need to interact with the UI, you need to connect directly.
+
+== SSH access (commandline)
+
+In case you need to access something on a Jenkins slave that you can't access through Jenkins itself, you can request ssh access to the Jenkins slaves. This will give you filesystem access as the same user running your job's builds, but will not give you a GUI, only commandline filesystem access.
+
+Contact the JBoss Tools release engineering team (Nick, Denis, Mickael, Max) to learn how to get access. You will also require Red Hat VPN access as the Jenkins servers are firewalled.
+
+== VNC access (GUI)
+
+JBoss Tools' Jenkins jobs use Xvnc so it's easy to monitor their progress or see why a UI test has stalled, using a vncviewer.
+
+Assuming you have been given access, here's what you need to do:
+
+1. Go to the job's current build page and look at the top of the console log to get the hostname (such as _vmg39.somewhere.redhat.com_) and DISPLAY variable (such as _12_).
+
+2. Run `xvncviewer host:port` where:
+
+* *port* is 5900 + DISPLAY
+* host is the fully-qualified server name (or its IP address)
+
+Thus, in this example:
+
+`vncviewer -passwd ~/.vnc/passwd_hudson vmg39.somewhere.redhat.com:5912`
+
+Contact the JBoss Tools release engineering team (Nick, Denis, Mickael, Max) to get the vncserver password for your job. You will also require Red Hat VPN access as the Jenkins servers are firewalled.

debugging/debug_on_ci.md

@@ -1,15 +1,15 @@
-# Debugging Surefire Tests
+= Debugging maven (surefire) tests
 
-## Useful debug files in Jenkins workspace
+== Useful debug files in workspace
 
-Maven _target/_ folder actually contains all the files related to your build and tests. Assuming a test is failing in the *org.jboss.tools.acme.test* suite, here are a set of interesting locations to help debugging:
+Maven _target/_ folders actually contains all the files related to your build and tests. Assuming a test is failing in the *org.jboss.tools.acme.test* suite, here are a set of interesting locations to help debugging:
 
 * _tests/org.jboss.tools.acme.test/target/work/configuration/config.ini_ contains the main configuration of the plugin. The most interesting part is the `osgi.bundles` property which lists all bundles that are installed in the application which runs test. It's the right place to check for a missing dependency
 * _tests/org.jboss.tools.acme.test/target/work/data_ is the test workspace, where you can access create projects, and
 * _tests/org.jboss.tools.acme.test/target/work/data/.metadata/.log_ contains the log of the test execution
 * _tests/org.jboss.tools.acme.test/target/work/data/.metadata_ contains all other Eclipse runtime metadata (such as workbench state, preferences...)
 
-## Useful input in maven build log
+== Useful input in maven build log
 
 Maven's build log shows a very interesting commandline while running surefire tests. It looks like:
 ```
@@ -22,34 +22,6 @@ This commandline is the actual command used to run your tests. You can copy and
 
 Reading the parameters in the commandline could also explain differences between expected and actual behavior of tests.
 
-## Using the Eclipse debugger
-
-Instead of running a `mvn clean verify` to simply see your Surefire/JUnit tests run in a console, you can also debug them interactively using http://www.eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html#debugPort[-DdebugPort=8000], or any port number you'd like:
-
-```
-mvn clean verify -DdebugPort=8000
-```
-
-Then, from Eclipse, create a Launch Configuration using "Debug Remote Java Application". 
-
-To begin, click on `Run -> Debug Configurations...`
-
-image::../images/remote_Debugging_1.PNG[Remote Debugging 1]
-
-Right click `Remote Java Application` and select `New`
-
-image::../images/remote_Debugging_2.PNG[Remote Debugging 2]
-
-Set the port to `8000`, or whatever port you used above, and select the workspace project you want to debug.
-
-The only necessary inputs are the project you want to test, and the port on which the debugger will listen (8000 for this example).
-
-image::../images/remote_Debugging_4.PNG[Remote Debugging 3]
-
-Click `Apply` then `Close`.
-
-Set a breakpoint in your code, then from the `Run` menu, you can launch the debugger to trace through the code to find the source of the problem. 
-
-When the maven build completes, the debugPort will be dropped. If you start the build again, you can then reconnect the debugger as needed.
-
+## Remote debugging w/ breakpoints
 
+See: link:remote_debugging.adoc[Using the Eclipse Remote Debugger]

debugging/debug_remote_console.adoc

@@ -1,4 +1,4 @@
-= How to install a local build of JBoss Tools components
+= How to install a JBoss Tools component build
 
 If you've already built a component, such as `jbosstools-base` or `jbosstools-server`, you may want to 
 install it into a new clean eclipse to test it out properly. It is highly suggested to do this

debugging/debug_tycho_tests.adoc

@@ -1,6 +1,6 @@
-= How to test a build of JBoss Tools components
+= How to test a JBoss Tools component build
 
-If you haven't yet gotten your local build installed, please see link:install_a_local_build.adoc[How to Install a Local Build].
+If you haven't yet gotten your local build installed, please see link:how_to_install_a_build.adoc[How to Install a Local Build].
 
 == Everything's Installed, Now what? 
 
@@ -12,50 +12,13 @@ There are, however, three options you have to get more information:
 * Tracing
 * Debugging via a second eclipse instance
 
-=== Logs
+=== Logging
 
-When using eclipse the main place to look for logging is in the workspace log file located at `<workspace>/.metadata/.log`.
-
-==== How to gather eclipse log and other in JBoss Tools
-
-If you have JBoss Tools installed the simplest way to gather logs and system configuration is to go to: 
-
-   Help > Report Problem
-   
-This will open up a dialog where you can put in a name and description.
-
-When pressing Finish a .zip file is created that you open or share with others (for example in Jira)
+See link:tracing_logging_in_eclipse.adoc#How-to-gather-eclipse-logs-and-system-configuration-details[How to gather Eclipse logs and system configuration details]
 
 === Tracing
 
-Eclipse comes with a tracing mechanism to allow various messages to be displayed in the console's output based on what tracing flags you pass in. This does require some knowledge of what tracing flags individual plugins expose, and you can usually discover this by browsing through the plugin's source code to see what they expose. 
-
-To enable tracing, two things are required:
-
-* A .options file must live in your eclipse base directory
-* You must run your eclipse with the -debug flag. 
-
-An example of a .options file, for org.jboss.ide.eclipse.as.server.core would look something like:
-
-```
-org.jboss.ide.eclipse.as.core/debug=true
-org.jboss.ide.eclipse.as.core/config=true
-org.jboss.ide.eclipse.as.core/info=true
-org.jboss.ide.eclipse.as.core/warning=true
-org.jboss.ide.eclipse.as.core/severe=true
-org.jboss.ide.eclipse.as.core/finer=true
-org.jboss.ide.eclipse.as.core/finest=true
-org.jboss.ide.eclipse.as.core/resources=true
-org.jboss.ide.eclipse.as.core/extension_point=true
-org.jboss.ide.eclipse.as.core/listeners=true
-org.jboss.ide.eclipse.as.core/runtime_target=true
-org.jboss.ide.eclipse.as.core/performance=true
-org.jboss.ide.eclipse.as.core/publishing=true
-```
-
-Each plugin can declare its own trace keys specific to their needs. To discover what trace options are available for a given plugin, 
-you can look for a file named 'Trace.java' or similar. For example, in the `jbosstools-server` repository, you may look at 
-`jbosstools-server/as/plugins/org.jboss.ide.eclipse.as.core/jbosscore/org/jboss/ide/eclipse/as/core/Trace.java`
+See link:tracing_logging_in_eclipse.adoc#How-to-enable-tracing-in-eclipse[How to enable tracing in Eclipse]
 
 
 == Debugging via a second eclipse instance

debugging/install_a_local_build.adoc renamed to debugging/how_to_install_a_build.adoc

@@ -1,11 +1,35 @@
-= Remote Debugging
+= Using the Eclipse remote debugger
 
-If you need to attach an Eclipse instance to a running Maven build, you can do so easily.
+Instead of running a `mvn clean verify` to simply see your tests run in a console, you can also debug them interactively using http://www.eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html#debugPort[-DdebugPort=8000]. 
+
+To attach an Eclipse instance to a running Maven build, do this:
 
 ```
 mvn verify -DdebugPort=8000
 ```
 
 Then launch Eclipse, browse to the project in your workspace, and create a new Remote Java Application from the Debug Configurations menu. This will allow you to set breakpoints in your Eclipse workspace project and step through them as the maven build runs on the debug port.
 
-For more details, see: link:debug_tycho_tests.adoc[Debugging Surefire Tests].
+Create a Launch Configuration using "Debug Remote Java Application". 
+
+To begin, click on `Run -> Debug Configurations...`
+
+image::../images/remote_Debugging_1.PNG[Remote Debugging 1]
+
+Right click `Remote Java Application` and select `New`
+
+image::../images/remote_Debugging_2.PNG[Remote Debugging 2]
+
+Set the port to `8000`, or whatever port you used above, and select the workspace project you want to debug.
+
+The only necessary inputs are the project you want to test, and the port on which the debugger will listen (8000 for this example).
+
+image::../images/remote_Debugging_4.PNG[Remote Debugging 3]
+
+Click `Apply` then `Close`.
+
+Set a breakpoint in your code, then from the `Run` menu, you can launch the debugger to trace through the code to find the source of the problem. 
+
+When the maven build completes, the debugPort will be dropped. If you start the build again, you can then reconnect the debugger as needed.
+
+See also: link:debug_tycho_tests.adoc[Debugging Maven (Surefire) Unit Tests]

debugging/how_to_test_a_build.adoc

@@ -1,11 +1,13 @@
-= Debugging your code via Runtime Workbench
+= Debugging via Eclipse runtime workbench
 
 It is assumed at this point that you have properly imported the source code for your project, link:../building/target_platforms/target_platforms_for_consumers.adoc[Configured your target platforms] in eclipse, and have a workspace free of errors. 
 
 == Running the plug-in
 
 To launch a runtime workbench, you can right-click on your project and select `Debug -> Debug As...` This dialog will show you all the different kinds of ways you can launch a program. Choose Eclipse Application, click New and accept all of the default settings. This will cause another instance of the Eclipse workbench, the runtime workbench, to start. 
 
-The launch configuration will automatically connect to the runtime workbench for the purposes of debugging. You can now go ahead and set breakpoints in your source code, just as you would for any normal Java project you launch from Eclipse. link:http://www.vogella.com/tutorials/EclipseDebugging/article.html[This] tutorial outlines most of the functions of Eclipse JDT for debugging purposes. 
+The launch configuration will automatically connect to the runtime workbench for the purposes of debugging. You can now go ahead and set breakpoints in your source code, just as you would for any normal Java project you launch from Eclipse. 
 
-You may also consider looking at the Plug-in Development Environment's link:http://wiki.eclipse.org/PDE/FAQ[FAQ] for further questions. 
+See link:http://www.vogella.com/tutorials/EclipseDebugging/article.html[Java Debugging with Eclipse], by Lars Vogel - a tutorial outlining most of the functions of Eclipse JDT debugging. 
+
+See also: link:http://wiki.eclipse.org/PDE/FAQ[Plug-in Development Environment (PDE) FAQ].