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 Running the benchmarks
  62 ----------------------
  63
  64 By default only the unit/integration tests are run. To also run the benchmarks,
  65 run Maven with the `benchmark` profile, as follows:
  66
  67     mvn clean verify -Pbenchmark
  68
  69 The benchmark results should be part of the standard output.
  70