Setup

Sadly, due to the amount of hooks JTimber uses, the setup for your project is not as easy as adding a single dependency. This guide should help you with making JTimber available in your project step by step.

Note that all components are available for manual download in a package distribution on the official download page. Moreover, the artifacts com.quartercode:jtimber-api, com.quartercode:jtimber-compiler-hook and com.quartercode:jtimber-runtime-hook are available both in the maven central repository and the LoadingByte maven repository (https://repo.loadingbyte.com/content/groups/maven-public/).

First step: API

The API component is a simple JAR you can add to your classpath like any other dependency.

API with Maven

If you build with maven, you only have to add the JTimber API dependency (available in maven central) to the pom.xml of your maven project (change VERSION to the version of JTimber you want to use):

<dependency>
    <groupId>com.quartercode</groupId>
    <artifactId>jtimber-api</artifactId>
    <version>VERSION</version>
</dependency>

Of course, the API JAR must also be part of the classpath at runtime. If you do not already have a system in place for that, you might want to use the Maven Shade Plugin.

API with Eclipse

If you are using Eclipse (and not already using maven), you need to tell Eclipse it should add the JTimber API JAR to the classpath. You can do that by following this tutorial. Moreover, you need to add another library to the classpath and package it with your application: Typetools (Download).

If you need to, you can download the API JAR using a link provided at the top of the page.

API with other

Depending on your build environment, this process might be very different. It is important that the API JAR is on the classpath both at compilation time and at runtime. That means that the JTimber API JAR must somehow be packaged with your final application. Moreover, you need to add another library to the classpath and package it with your application: Typetools (Download).

If you need to, you can download the API JAR using a link provided at the top of the page. Note that a maven repository is also available and mentioned there.

Second step: Compiler hook

The compiler hook is a simple java annotation processor which automatically hooks itself into the compiler. If you are not using Eclipse, the only thing you need to do is provide the compiler hook JAR at compilation time of your project.

Compiler hook with Maven

If you build with maven, you only have to add the JTimber compiler hook dependency (available in maven central) to the pom.xml of your maven project (change VERSION to the version of JTimber you want to use):

<dependency>
    <groupId>com.quartercode</groupId>
    <artifactId>jtimber-compiler-hook</artifactId>
    <version>VERSION</version>
    <scope>provided</scope>
</dependency>

The compiler hook JAR must not be part of the classpath at runtime. Therefore, its scope is set to provided.

Note, however, that you also need to set up Eclipse if you are using it. M2E doesn't automatically add the required hooks.

Compiler hook with Eclipse

If you are using Eclipse (and even if you are already using maven), you need to tell Eclipse it should use the JTimber annotation processor. You can do that by following this tutorial. You can either download the compiler hook JAR manually or, if you are using maven, add it from your local maven repository (which is probably located under ~/.m2/repository/).

If you need to, you can download the compiler hook JAR using a link provided at the top of the page.

Compiler hook with other

Depending on your build environment, this process might be very different. It is important that the compiler hook JAR is on the classpath only at compilation time and not at runtime. That means that the JTimber compiler hook JAR must not be packaged with your final application.

If you need to, you can download the compiler hook JAR using a link provided at the top of the page. Note that a maven repository is also available and mentioned there.

Third step: Runtime hook

The runtime hook is a javaagent which actually implements all the black bytecode magic which brings JTimber to life. Sadly, there's no standard way for this step. You basically have to add the javaagent at runtime. Therefore, you need to start the JVM which runs your application with an additional VM argument:

$ java -javaagent:

/path/to/jtimber-runtime-hook.jar -jar ...

You probably don't want your users to input that command. Therefore, you should package your application JAR with a launcher that is marked as your JAR's main class. That launcher in turn calls the command above with your application's actual main class after the -jar ... part. By doing that, your users only need to launch the application JAR without having to worry about javaagents.

You can even try to shade the javaagent into your application's JAR and then use your JAR both for the -javaagent:... and the -jar ... part. The result would be one fat JAR. However, if you want to do that, don't forget to add the following line to the manifest of your fat JAR:

Premain-Class: com.quartercode.jtimber.rh.agent.TimberAgent