## Classpath Setup

In order to run the examples provided in the documentation, you need to add the following jars to your class path:

- logback-core-${project.version}.jar
- logback-classic-${project.version}.jar
- logback-examples-${project.version}.jar
- slf4j-api-${slf4j.version}.jar

The logback-*.jar files are part of the logback distribution whereas slf4j-api-${slf4j.version}.jar ships with SLF4J, a separate project.

### Running from the command line

You can launch the first sample application, chapters.introduction.HelloWord1 with the following command. This assumes that your current directory is $LOGBACK_HOME/logback-examples, where $LOGBACK_HOME stands for the directory where you installed logback:

java -cp lib/slf4j-api-${slf4j.version}.jar;../logback-core-${project.version}.jar;\ ../logback-classic-${project.version}.jar;logback-examples-${project.version}.jar\ chapters.introduction.HelloWorld1

It is more convenient to set the CLASSPATH environment variable once and for all before running the examples.

The setClasspath.cmd script located in the $LOGBACK_HOME/logback-examples folder will configure the class path for the MS Windows platform. For Unix, you can use setClasspath.sh.

Please edit the script in order to adapt the LB_HOME variable to match your local environment.

Please be aware that many examples will launch Java classes along with configuration files. To access these files by using the same commands as written in the documentation, you will need to issue the commands from within the $LOGBACK_HOME/logback-examples directory.

## Maven dependency declaration

To use logback-classic in your Maven project, declare the following dependency in your project's pom file.

    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <version>${project.version}</version>
    </dependency>

TRANSITIVITY Note that in addition to logback-classic.jar, the above declaration will automatically pull-in slf4j-api.jar and logback-core.jar into your project by virtue of Maven's transitivity rules.

To include logback-access in your Maven project, declare the following dependency in your project's pom file.

    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-access</artifactId>
      <version>${project.version}</version>
    </dependency>

#### Maven "Bill of materials" (useful for large teams)

To facilitate the synchronization of logback and slf4j modules, we provide a "Bill of materials" pom file. It can be imported in the `dependencyManagement` section of your parent `pom` file, as shown below.

    <dependencyManagement>
      <dependencies>
         <dependency>
           <groupId>ch.qos.logback</groupId>
           <artifactId>logback-bom</artifactId>
           <version>${project.version}</version>
           <type>pom</type>
           <scope>import</scope>
           <dependency>
           ...
      </dependencies>
    </dependencyManagement>

Importing logback-bom as shown above allows you to declare the version for logback/slf4j modules in one step and keep them in sync. This can be convenient particularly in larger software teams.

Note that you still need to declare a dependency on logback-classic (or logback-access). However, you no longer will have to specify the version.

After logback-bom is imported, the previous dependency declaration becomes:

    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <!-- Look mom, no version! -->
    </dependency>

## Optional dependencies

### `SMTPAppender` requires JavaMail API

`SMTPAppender` related examples require the JavaMail API version 1.4 or later. Once you download JavaMail, you need to place mail.jar on your class path.

Here is the corresponding Maven dependency declaration for your convenience.

    <!-- The javax.activation:activation:1.1 dependency will be -->
    <!-- automatically pulled in by Maven's transitivity rules -->
    <dependency>
      <groupId>javax.mail</groupId>
      <artifactId>mail</artifactId>
      <version>${javax.mail.version}</version>
    </dependency>

### `GEventEvaluator` and logback.groovy configuration files require the Groovy runtime

`GEventEvaluator` depends on the Groovy runtime. It was tested with Groovy version ${groovy.version}. Similarly, as the name indicates groovy configuration files require the groovy runtime to be present on your class path.

Here is the corresponding Maven dependency declaration for your convenience.

    <dependency>
      <groupId>org.codehaus.groovy</groupId>
      <artifactId>groovy-all</artifactId>
      <version>${groovy.version}</version>
    </dependency>

### Conditional processing and `JaninoEventEvaluator` require the Janino library

Conditional processing in configuration files requires the Janino library. Moreover, the evaluator examples based on `JaninoEventEvaluator` require Janino as well. Once you download Janino, simply place commons-compiler.jar and janino.jar on your application's class path.

Don't forget As of Janino version 2.6.0, in addition to janino.jar, commons-compiler.jar needs to be on the class path as well.

Here is the corresponding Maven dependency declaration for your convenience.

    <!-- The org.codehaus.janino:commons-compiler:${janino.version} dependency -->
    <!-- will be automatically pulled in by Maven's transitivity rules -->
    <dependency>
      <groupId>org.codehaus.janino</groupId>
      <artifactId>janino</artifactId>
      <version>${janino.version}</version>
    </dependency>

## Building with an IDE

If you wish to contribute to the project or just hack for fun, you will probably want to import logback as a project into your favorite IDE. Logback uses Maven as its build tool. Logback offers a Groovy-based configurator so there is a dependency on the Groovy language. It follows that your IDE should have plugins for Maven and Groovy in order to build logback from your within IDE. The Groovy dependency just mentioned is a build-time dependency. The only mandatory logback dependency at runrime is the JRE, unless of course you wish to use the Groovy configurator in which case Groovy runtime will be a required dependency as well. Also note that building from the command line is fairly trivial, the command 'mvn install' given from $LOGBACK_HOME folder should suffice.

ask for help Notwithstanding the instructions below, if you have trouble building logback from the sources, just ask for help on the logback-dev mailing list.

### Building logback with IntelliJ IDEA

Assuming you have the latest version of IntelliJ IDEA installed, no additional plugin installation is necessary. IntelliJ IDEA supports Maven as well as Groovy out of the box. You can import logback into IDEA by selecting File→ New Project → Import from external model→ Maven, then select $LOGBACK_HOME as the Root directory. The import should finish successfully in a few seconds.

### Building with Eclipse

Building logback under Eclipse is a little trickier. Here are instructions for building logback under Eclipse using the maven eclipse:eclipse plugin.

The procedure outlines below assumes that M2Eclipse is not active. If you have `m2eclipse` installed, you can disable it by removing the Maven Nature for a given project. In later versions of Eclipse, m2eclipse is installed by default.

And without further ado here are the steps:

1. Install Eclipse
2. Install the Groovy plugin for Eclipse.

   - You first need to determine the update site appropriate for your version of Eclipse. The list of available update sites is available from Groovy Eclipse Wiki.

   - In Eclipse, select Help → Intall new Software → Work with the update site you chose in the previous step and then Select "Groovy-Eclipse Feature". Installation of other plugins in particular "m2e Configurator for Groovy-Eclipse" is not necessary

3.     cd $LOGBACK_HOME

   where $LOGBACK_HOME stands for the location where you cloned the logback project from github
4. From the command line, run `mvn eclipse:eclipse` in $LOGBACK_HOME
5. In Eclipse, import the logback project: Import→ General→ Existing Projects into Workspace, select $LOGBACK_HOME folder for the import
6. In Eclipse, clean all projects in Eclipse (Project → Clean)
7. In Eclipse, select logback-classic project and check that it has "Groovy" nature. If not add it by right clicking on logback-classic project → Groovy → Convert Groovy to Project.

The above listed procedure has been last tested by the author using Eclipse Luna on February 25th, 2016.

Call for volunteers Given that many users prefer M2Eclipse for building projects under Eclipse IDE, we are looking for volunteers to help work out the steps for building logback with M2Eclipse.