Document how to set non-default library paths
[lttng-ust-java-tests.git] / README.md
1 LTTng-UST Java Agent Test Package
2 =================================
3
4 This git tree contains integration tests and benchmarks for the
5 [LTTng-UST](https://lttng.org/) Java Agent. It requires many additional
6 dependencies compared to the library itself, so it is shipped as a separate
7 package for now.
8
9
10 Prerequisites
11 -------------
12
13 * Java 1.8
14 * [Apache Maven](https://maven.apache.org/) 3.0+
15 * A recent version of [LTTng-Tools](https://lttng.org/download/)
16 * A recent version of [Babeltrace](http://www.efficios.com/babeltrace)
17 * A git branch or version of LTTng-UST you want to test
18
19 For example, on Ubuntu you can use the
20 [LTTng PPA](https://launchpad.net/~lttng/+archive/ubuntu/ppa), then Maven and
21 OpenJDK from the main repository:
22
23 sudo apt-add-repository ppa:lttng/ppa
24 sudo apt-get update
25 sudo apt-get install lttng-tools babeltrace maven openjdk-8-jre
26
27 Also make sure `mvn -version` reports a `Java version: 1.8` or higher. If it
28 does not, you may need to set your `JAVA_HOME` accordingly.
29
30
31 Usage
32 -----
33
34 First you need to `make install` the LTTng-UST git branch you want to test.
35 For example:
36
37 git clone git://git.lttng.org/lttng-ust.git
38 cd lttng-ust/
39 (do some modifications, checkout a different branch, etc.)
40 ./bootstrap
41 ./configure --enable-java-agent-all
42 make
43 sudo make install
44
45 Then, `cd` back to the directory where you cloned the present git tree, and
46 issue a
47
48 mvn clean verify
49
50 This will run all the tests on the UST agent that was `make install`'ed. Tests
51 will be skipped if they cannot find their required classes or native libraries,
52 so make sure the output mentions succesful tests and not skipped ones.
53
54 Please make sure you have no `lttng` session active prior to or during the
55 tests, or it might interfere with the test runs!
56
57 Detailed JUnit test reports will be available under
58 `lttng-ust-java-tests-{jul|log4j}/target/failsafe-reports/`
59
60
61 Setting library paths
62 ---------------------
63
64 By default, the tests will look for the Java and JNI libraries in the default
65 locations of `make install` (`/usr/local/lib`, `/usr/local/share/java`, etc.)
66
67 If for example, you installed into the `/usr` prefix instead of `/usr/local`,
68 you can use the following properties to specify different locations for the
69 lttng-ust-agent-java jars:
70
71 mvn clean verify
72 -Dcommon-jar-location=/usr/share/java/lttng-ust-agent-common.jar
73 -Djul-jar-location=/usr/share/java/lttng-ust-agent-jul.jar
74 -Dlog4j-jar-location=/usr/share/java/lttng-ust-agent-log4j.jar
75
76 To specify a different locations for the JNI .so libraries, you can set the
77 `-Djava.library.path` property on the JVM:
78
79 mvn (...) -DargLine=-Djava.library.path=/usr/lib
80
81 Note: do not use `MAVEN_OPTS` to set the library path, since the `argLine`
82 property defined in the build will overwrite it.
83
84
85 Running the benchmarks
86 ----------------------
87
88 By default only the unit/integration tests are run. To also run the benchmarks,
89 run Maven with the `benchmark` profile, as follows:
90
91 mvn clean verify -Pbenchmark
92
93 The benchmark results should be part of the standard output.
94
This page took 0.031314 seconds and 4 git commands to generate.