X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=README.md;h=cf1c566693b8c8af35620ba31a9028c01de7c3a4;hb=HEAD;hp=c30e7f3f09363c4de9812e897c0ec621a9652489;hpb=7b82be365510ed64ba6c21d67b51be33211a4ab4;p=lttng-ust-java-tests.git

diff --git a/README.md b/README.md
index c30e7f3..cf1c566 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Prerequisites
 * Java 1.8
 * [Apache Maven](https://maven.apache.org/) 3.0+
 * A recent version of [LTTng-Tools](https://lttng.org/download/)
-* A recent version of [Babeltrace](http://www.efficios.com/babeltrace)
+* A recent version of [Babeltrace 2.x](http://www.efficios.com/babeltrace)
 * A git branch or version of LTTng-UST you want to test
 
 For example, on Ubuntu you can use the
@@ -22,7 +22,7 @@ OpenJDK from the main repository:
 
     sudo apt-add-repository ppa:lttng/ppa
     sudo apt-get update
-    sudo apt-get install lttng-tools babeltrace maven openjdk-8-jre
+    sudo apt-get install lttng-tools babeltrace2 maven openjdk-8-jre
 
 Also make sure `mvn -version` reports a `Java version: 1.8` or higher. If it
 does not, you may need to set your `JAVA_HOME` accordingly.
@@ -55,9 +55,116 @@ Please make sure you have no `lttng` session active prior to or during the
 tests, or it might interfere with the test runs!
 
 Detailed JUnit test reports will be available under
-`lttng-ust-java-tests/target/failsafe-reports/`
+`lttng-ust-java-tests-{jul|log4j}/target/failsafe-reports/`
 
 
+Setting library paths
+---------------------
+
+By default, the tests will look for the Java and JNI libraries in the default
+locations of `make install` (`/usr/local/lib`, `/usr/local/share/java`, etc.)
+
+If for example, you installed into the `/usr` prefix instead of `/usr/local`,
+you can use the following properties to specify different locations for the
+lttng-ust-agent-java jars:
+
+    mvn clean verify \
+    -Dcommon-jar-location=/usr/share/java/lttng-ust-agent-common.jar \
+    -Djul-jar-location=/usr/share/java/lttng-ust-agent-jul.jar \
+    -Dlog4j-jar-location=/usr/share/java/lttng-ust-agent-log4j.jar \
+    -Dlog4j2-jar-location=/usr/share/java/lttng-ust-agent-log4j2.jar
+
+To specify a different locations for the JNI .so libraries, you can set the
+`-Djava.library.path` property on the JVM:
+
+    mvn (...) -DargLine=-Djava.library.path=/usr/lib
+
+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
+
+Running tests by tags
+---------------------
+
+Tests can also be filtered by Junit tags or tag expressions [1], for example to
+run only the Log4 1.x agent tests:
+
+    mvn clean verify -Dgroups='agent:log4j'
+
+Or to exclude the tests of the Log4j2 domain:
+
+   mvn clean verify -Dgroups='!domain:log4j2'
+
+[1] https://junit.org/junit5/docs/current/user-guide/#running-tests-tags
+
+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.
+You will need to ignore SIGSEV from java under gdb:
+    
+    handle SIGSEGV nostop noprint pass
+
 Running the benchmarks
 ----------------------