Difference between revisions of "JTimber/Setup"

From LoadingByte Wiki
Jump to navigation Jump to search
m
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
 
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.
 
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 [http://quartercode.com/dl/projects/details?projectId=JTimber QuarterCode DL page]. Moreover, the artifacts <code>com.quartercode:jtimber-api</code>, <code>com.quartercode:jtimber-compiler-hook</code> and <code>com.quartercode:jtimber-runtime-hook</code> are available in the QuarterCode maven repository (http://repo.quartercode.com/content/groups/public/).
+
Note that all components are available for manual download in a package distribution on the [http://quartercode.com/dl/projects/details?projectId=JTimber QuarterCode DL page]. Moreover, the artifacts <code>com.quartercode:jtimber-api</code>, <code>com.quartercode:jtimber-compiler-hook</code> and <code>com.quartercode:jtimber-runtime-hook</code> are available both in the '''maven central repository''' and the QuarterCode maven repository (http://repo.quartercode.com/content/groups/public/).
  
 
== First step: API ==
 
== First step: API ==
Line 9: Line 9:
 
=== Maven ===
 
=== Maven ===
  
If you build with maven, you only have to add a dependency to the <code>pom.xml</code> of your maven project:
+
If you build with maven, you only have to add the JTimber API dependency (available in maven central) to the <code>pom.xml</code> of your maven project (change VERSION to the version of JTimber you want to use):
 
 
* Add the QuarterCode maven repository:
 
 
 
<source lang="xml">
 
<repositories>
 
    ...
 
 
 
    <repository>
 
        <id>quartercode-repository</id>
 
        <name>QuarterCode Repository</name>
 
        <url>http://repo.quartercode.com/content/groups/public/</url>
 
    </repository>
 
</repositories>
 
</source>
 
 
 
* Add the JTimber API dependency (change VERSION to the version of JTimber you want to use):
 
  
 
<source lang="xml">
 
<source lang="xml">
Line 39: Line 23:
 
=== Eclipse ===
 
=== 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 [https://stackoverflow.com/questions/8486403/eclipse-ide-add-jar-add-external-jar-add-library this tutorial]. Moreover, you need to add another libraries to the classpath and package it with your application: Typetools ([http://mvnrepository.com/artifact/net.jodah/typetools Download]).
+
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 [https://stackoverflow.com/questions/8486403/eclipse-ide-add-jar-add-external-jar-add-library this tutorial]. Moreover, you need to add another library to the classpath and package it with your application: Typetools ([http://mvnrepository.com/artifact/net.jodah/typetools Download]).
  
 
If you need to, you can download the API JAR using a link provided at the top of the page.
 
If you need to, you can download the API JAR using a link provided at the top of the page.
Line 45: Line 29:
 
=== Other ===
 
=== 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 libraries to the classpath and package it with your application: Typetools ([http://mvnrepository.com/artifact/net.jodah/typetools Download]).
+
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 ([http://mvnrepository.com/artifact/net.jodah/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.
 
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 ==
 
== Second step: Compiler hook ==
  
Line 54: Line 39:
 
=== Maven ===
 
=== Maven ===
  
If you build with maven, you only have to add the JTimber compiler hook dependency to the <code>pom.xml</code> of your maven project. Note that you should have already added the QuarterCode maven repository in the first step.
+
If you build with maven, you only have to add the JTimber compiler hook dependency (available in maven central) to the <code>pom.xml</code> of your maven project (change VERSION to the version of JTimber you want to use):
 
 
Change VERSION to the version of JTimber you want to use:
 
  
 
<source lang="xml">
 
<source lang="xml">
Line 68: Line 51:
  
 
The compiler hook JAR must '''not''' be part of the classpath at runtime. Therefore, its scope is set to <code>provided</code>.
 
The compiler hook JAR must '''not''' be part of the classpath at runtime. Therefore, its scope is set to <code>provided</code>.
 +
 +
Note, however, that you also need to set up Eclipse if you are using it. M2E doesn't automatically add the required hooks.
  
 
=== Eclipse ===
 
=== Eclipse ===

Latest revision as of 10:24, 2 May 2015

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 QuarterCode DL 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 QuarterCode maven repository (http://repo.quartercode.com/content/groups/public/).

First step: API

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

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.

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.

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.

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.

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.

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