Add debugging example to ease life of non-java master

Signed-off-by: Jonathan Rajotte <jonathan.rajotte-julien@efficios.com>

diff --git a/README.md b/README.md
index 1bd43fd3244a81240ad6a837875dea489080f6e4..f944a59e34aaae05c20f6cfeae120c282bd686c3 100644 (file)
--- a/README.md
+++ b/README.md
@@ -81,6 +81,67 @@ To specify a different locations for the JNI .so libraries, you can set the
 Note: do not use `MAVEN_OPTS` to set the library path, since the `argLine`
 property defined in the build will overwrite it.
 
+Running a single test
+----------------------
+
+This test suite is comprised of integration tests. We use the failsafe
+maven plugin [1]. To run a single test, one can use the test class name and the
+following command:
+
+   mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false
+
+The `-DfailIfNoTests=false` argument is necessary otherwise maven will fail on
+the first test set that is empty. See [2] for more info.
+
+
+[1] http://maven.apache.org/surefire/maven-failsafe-plugin/index.html
+[2] http://maven.apache.org/surefire/maven-failsafe-plugin/examples/single-test.html
+
+Debugging a test
+----------------------
+
+Note that for most tests, the test itself is the traced application.
+The fastest and "easiest" way of putting a breakpoint is to use eclipse.
+
+Download eclipse (for java dev).
+Import a maven project that points to this repo:
+
+   File -> Import -> Project -> Select Maven folder -> Select Existing Maven Projects
+   Point the root directory to this repo. Select all projects. Finish
+
+Setup the Debug Configuration:
+   Run -> Debug Configurations.
+   Select Remote Java Application.
+   Press the New Configuration button.
+   Give it the name "Remote lttng maven".
+   Select the project and select `lttng-tools-java`
+   Set the port to 5005
+   Go in the Source tab.
+   Click Add -> Java project -> Select all
+   Click Apply
+   Click Close
+
+Now let's run a single test with debug:
+
+   mvn clean verify -Dit.test=JulAppContextOrderingIT -DfailIfNoTests=false -Dmaven.failsafe.debug
+
+Wait for:
+   Listening for transport dt_socket at address: 5005
+
+Now go back to eclipse:
+   Navigate to where you want to put a break point. For example, JulAppContextOrderingIT.registerAgent.
+   Ctrl + shift + b can be used to set a tracepoint at the desired line. 
+
+Then attach to the debugger:
+   Run -> Debug Configurations.
+   Select on the right "Remote lttng maven"
+   Click Debug
+
+You should hit the breakpoint at some point and from there use steps etc.
+
+If you want to debug lttng-ust, you need to insert a breakpoint at a valid point
+in time for the test and then use gdb to hook yourself to the java process.
+From there debugging is the same as any C application.
 
 Running the benchmarks
 ----------------------