Eclipse

The logback Eclipse extension enables Eclipse RCP applications/plugins to use logback to display messages in Eclipse's Error Log.

The documentation below is a placeholder for an upcoming Eclipse plugin (not yet available) that wraps the EclipseLogAppender. The details regarding the plugin are subject to change. However, the EclipseLogAppender can still be included directly in your RCP projects.

Install

Currently, this plugin has only been tested on Eclipse Indigo (Version: Indigo Service Release 2, Build id: 20120216-1857). The plugin might have to be recompiled for earlier versions of Eclipse.

Eclipse update site: TBD

Usage

1. Edit your RCP application's manifest (${project.root}/META-INF/MANIFEST.MF) to include the following property-values:

   Property	Value to add	Purpose
   Require-Bundle	ch.qos.logback.ext.eclipse;bundle-version="${version}";resolution:=optional (where ${version} is the actual version number of the logback extension for Eclipse)	Adds support to log to Eclipse's Error Log via logback's EclipseLogAppender. It's optional so that if the bundle is removed, the SLF4J calls result in no operation.
   Eclipse-RegisterBuddy	ch.qos.logback.ext.eclipse	Eclipse requirement for classloading third-party libraries(1)
   Bundle-ClassPath	/path/to/slf4j-api-1.6.6.jar	To compile SLF4J statements in RCP application

   Example:

   Manifest-Version: 1.0
   Bundle-ManifestVersion: 2
   Bundle-Name: Helloworld
   Bundle-SymbolicName: com.example.e4.helloworld; singleton:=true
   Bundle-Version: 1.0.0.qualifier
   Bundle-Activator: com.example.e4.helloworld.Activator
   Bundle-Vendor: EXAMPLE
   Require-Bundle:  ch.qos.logback.ext.eclipse;bundle-version="1.0.0";resolution:=optional,
    org.eclipse.ui,
    org.eclipse.core.runtime
   Bundle-RequiredExecutionEnvironment: JavaSE-1.6
   Bundle-ActivationPolicy: lazy
   Eclipse-RegisterBuddy: ch.qos.logback.ext.eclipse
   Bundle-ClassPath: libs/slf4j-api-1.6.6.jar,.
   

2. Edit your RCP application's build properties (${project.root}/build.properties) so that the binary output includes the SLF4J JAR and logback.xml (i.e., add the file paths to the bin.includes property).

   Example:

   source.. = src/
   output.. = bin/
   bin.includes = plugin.xml,\
                  META-INF/,\
                  icons/,\
                  src/logback.xml,\
                  libs/slf4j-api-1.6.6.jar
   
   jars.compile.order = .
   

3. Define the logback.xml file (at the path specified in step 2) defining one or more EclipseLogAppender elements, each containing the symbolic name of an Eclipse plugin (must match the Bundle-SymbolicName property in the plugin's manifest) whose logger will write to the Error Log. For example:

   <configuration>
   	<appender name="eclipse" class="ch.qos.logback.ext.EclipseLogAppender">
   		<bundleName>com.example.e4.helloworld</bundleName>
   	</appender>
   	<root level="WARN">
   		<appender-ref ref="eclipse"/>
   	</root>
   </configuration>
   

   The following log levels are mapped to Eclipse's status levels:

   <tr><td>Level.TRACE</td><td>Status.CANCEL</td></tr>
   <tr><td>Level.ERROR</td><td>Status.ERROR</td></tr>
   <tr><td>Level.WARN</td><td>Status.WARN</td></tr>
   <tr><td>Level.INFO</td><td>Status.INFO</td></tr>
   <tr><td>Level.DEBUG (and all else)</td><td>Status.OK</td><tr>
   

   Logback Level	Eclipse Status

Building from source

The JAR is built using Maven. This has been tested with Maven 2, but Maven 3 should also work.

1. From the logback-extensions root directory, enter:

    $ mvn package
   

   The JAR is built in:

    ${logback-extensions.src}/eclipse/target/logback-ext-eclipse_1.0.0.jar
   

2. From Eclipse Indigo, import the RCP plugin project for this logback extension.

   a. Import the existing project by File > Import > Existing projects into workspace b. Clean and rebuild the project by Project > Clean. c. Export the project by File > Export > Plugin.

TODO: Use pax-construct or tycho to build plugin from command-line.

Creating Eclipse Update Site

TBD

Sample Project

1. Download the sample Eclipse RCP plugin project.
2. From Eclipse, import the project into the workspace (menu File > Import... > Existing projects into workspace).
3. Rebuild and run the project, which opens a new instance of Eclipse where the plugin is running.
4. From the new Eclipse instance, choose menu Sample Menu > Sample Command, which creates a log entry (from logback) in the Error Log, as shown in the screenshot below.