1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Setup</title>
<link rel="stylesheet" type="text/css" href="css/common.css" />
<link rel="stylesheet" type="text/css" href="css/screen.css" media="screen" />
<link rel="stylesheet" type="text/css" href="css/_print.css" media="print" />
<link rel="stylesheet" type="text/css" href="css/prettify.css" media="screen" />
</head>
<body onload="prettyPrint(); decorate();">
<script type="text/javascript">prefix=''; </script>
<script type="text/javascript" src="templates/header.js"></script>
<script type="text/javascript" src="js/prettify.js"></script>
<script type="text/javascript" src="js/jquery-min.js"></script>
<script type="text/javascript" src="js/decorator.js"></script>
<div id="left">
<script type="text/javascript" src="templates/left.js"></script>
</div>
<div id="content">
<h2 class="doAnchor">Classpath Setup</h2>
<p>In order to run the examples provided in the documentation, you
need to add the following jars to your class path:
</p>
<ul>
<li>logback-core-1.2.3.jar</li>
<li>logback-classic-1.2.3.jar</li>
<li>logback-examples-1.2.3.jar</li>
<li>slf4j-api-1.7.25.jar</li>
</ul>
<p>The <em>logback-*.jar</em> files are part of the logback
distribution whereas <em>slf4j-api-1.7.25.jar</em> ships
with <a href="http://www.slf4j.org">SLF4J</a>, a separate project.
</p>
<h3 class="doAnchor" name="commandLine">Running from the command
line</h3>
<p>You can launch the first sample application,
<em>chapters.introduction.HelloWord1</em> with the following
command. This assumes that your current directory is
<em>$LOGBACK_HOME/logback-examples</em>, where
<em>$LOGBACK_HOME</em> stands for the directory where you
installed logback:
</p>
<p class="source">java -cp lib/slf4j-api-1.7.25.jar;../logback-core-1.2.3.jar;\
../logback-classic-1.2.3.jar;logback-examples-1.2.3.jar\
chapters.introduction.HelloWorld1</p>
<p>It is more convenient to set the CLASSPATH environment variable
once and for all before running the examples.
</p>
<p>The <em>setClasspath.cmd</em> script located in the
$LOGBACK_HOME/logback-examples folder will configure the class path
for the MS Windows platform. For Unix, you can use
<em>setClasspath.sh</em>.
</p>
<p>Please edit the script in order to adapt the <em>LB_HOME</em> variable
to match your local environment.</p>
<p>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
<em>$LOGBACK_HOME/logback-examples</em> directory.
</p>
<h2 class="doAnchor" name="mavenBuild">Maven dependency
declaration</h2>
<p>To use logback-classic in your Maven project, declare the
following dependency in your project's <em>pom</em> file.</p>
<pre class="prettyprint source"><dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>1.2.3</version>
</dependency></pre>
<p><span class="label notice">TRANSITIVITY</span> Note that in
addition to <em>logback-classic.jar</em>, the above declaration
will automatically pull-in <em>slf4j-api.jar</em> and
<em>logback-core.jar</em> into your project by virtue of Maven's
transitivity rules.</p>
<p>To include logback-access in your Maven project, declare the following
dependency in your project's <em>pom</em> file.</p>
<pre class="prettyprint source"><dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-access</artifactId>
<version>1.2.3</version>
</dependency></pre>
<!--
<h4>Maven "Bill of materials" (useful for large teams)</h4>
<p>To facilitate the synchronization of logback and slf4j modules,
we provide a "Bill of materials" pom file. It can be imported in
the <code>dependencyManagement</code> section of your parent
<code>pom</code> file, as shown below.
</p>
<pre class="prettyprint source"><dependencyManagement>
<dependencies>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-bom</artifactId>
<version>1.2.3</version>
<type>pom</type>
<scope>import</scope>
</dependency>
...
</dependencies>
</dependencyManagement></pre>
<p>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.</p>
<p>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.</p>
<p>After logback-bom is imported, the previous dependency declaration
becomes:</p>
<pre class="prettyprint source"><dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<!-- Look mom, no version! -->
</dependency></pre>
-->
<h2 class="doAnchor" name="optionalDeps">Optional dependencies</h2>
<h3 class="doAnchor" name="SMTP"><code>SMTPAppender</code> requires
JavaMail API</h3>
<p><code>SMTPAppender</code> related examples require the JavaMail
API version 1.4 or later. Once you <a
href="http://java.sun.com/products/javamail/downloads/index.html">download
JavaMail</a>, you need to place <em>mail.jar</em> on your class
path.</p>
<p>Here is the corresponding Maven dependency declaration for your
convenience.</p>
<pre class="prettyprint source"><!-- 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>1.4</version>
</dependency></pre>
<h3 class="doAnchor" name="groovy"><code>GEventEvaluator</code> and
<em>logback.groovy</em> configuration files require the Groovy
runtime</h3>
<p><code>GEventEvaluator</code> depends on the Groovy runtime. It
was tested with Groovy version 2.4.0. Similarly, as the
name indicates <a href="manual/groovy.html">groovy
configuration</a> files require the groovy runtime to be present on
your class path.
</p>
<p>Here is the corresponding Maven dependency declaration for your
convenience.
</p>
<pre class="prettyprint source"><dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-all</artifactId>
<version>2.4.0</version>
</dependency></pre>
<h3 class="doAnchor" name="janino">Conditional processing and
<code>JaninoEventEvaluator</code> require the Janino library</h3>
<p><a href="manual/configuration.html#conditional">Conditional
processing</a> in configuration files requires the <a
href="http://docs.codehaus.org/display/JANINO/Home"><b>Janino
library</b></a>. Moreover, the evaluator examples based on
<code>JaninoEventEvaluator</code> require Janino as well. Once you
download Janino, simply place <em>commons-compiler.jar</em> and
<em>janino.jar</em> on your application's class path.
</p>
<p><span class="label notice">Don't forget</span> As of Janino
version 2.6.0, in addition to <em>janino.jar</em>,
<em>commons-compiler.jar</em> needs to be on the class path as well.</p>
<p>Here is the corresponding Maven dependency declaration for your
convenience.
</p>
<pre class="prettyprint source"><!-- The org.codehaus.janino:commons-compiler:3.0.6 dependency -->
<!-- will be automatically pulled in by Maven's transitivity rules -->
<dependency>
<groupId>org.codehaus.janino</groupId>
<artifactId>janino</artifactId>
<version>3.0.6</version>
</dependency></pre>
<h2 class="doAnchor" name="ide">Building with an IDE</h2>
<p>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 <em>build</em> logback from your within
IDE. The Groovy dependency just mentioned is a <em>build-time</em>
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. </p>
<p><span class="label">ask for help</span> Notwithstanding the
instructions below, if you have trouble building logback from the
sources, just ask for help on the logback-dev mailing list.</p>
<h3 class="doAnchor" name="idea">Building logback with IntelliJ
IDEA</h3>
<p>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.</p>
<h3 class="doAnchor" name="eclipse">Building with Eclipse and "mvn eclipse:eclipse"</h3>
<p>Building logback under Eclipse is a little trickier. Here are
instructions for building logback under Eclipse using the maven
eclipse:eclipse plugin.
</p>
<p>The procedure outlines below assumes that M2Eclipse is not
active. If you have <code>m2eclipse</code> installed, you can
disable it by removing the Maven Nature for a given project. In
later versions of Eclipse, m2eclipse is installed by default.
</p>
<p>And without further ado here are the steps:
</p>
<ol>
<li>Ensure that the Groovy plugin for Eclipse is installed.
<ul>
<li>
<p>You first need to determine the update site appropriate
for your version of Eclipse. The list of available update
sites is available from <a
href="https://github.com/groovy/groovy-eclipse/wiki">Groovy
Eclipse Wiki</a>.
</p>
</li>
<li>In Eclipse, select Help → Intall new Software →
Work with the update site you chose in the previous step and
then Select "Groovy-Eclipse Feature".
</li>
</ul>
</li>
<li><pre>cd $LOGBACK_HOME</pre>
where $LOGBACK_HOME stands for the location where you cloned the
logback project from github </li>
<li>From the command line, run <code>mvn eclipse:eclipse</code>
in $LOGBACK_HOME</li>
<li>In Eclipse, import the logback project: Import→
General→ Existing Projects into Workspace, select
$LOGBACK_HOME folder for the import
</li>
<li>In Eclipse, clean all projects in Eclipse (Project →
Clean)
</li>
<li>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.
</li>
</ol>
<p>The above listed procedure has been last tested by the author
using Eclipse Neon on March 17th, 2017.</p>
<h3>Building with Eclipse+m2eclipse</h3>
<p>Building with Eclipse and m2eclipse is a bit more complicated
due to the use of Groovy in logback-classic.
</p>
<p>Here are the required steps:</p>
<ol>
<li>Ensure that the Groovy plugin for Eclipse is installed. See
above for instructions.</li>
<li>In Eclipse, import the logback project: Import→
Maven→ Existing Maven Projects, select
$LOGBACK_HOME folder for the import
</li>
<li>Install any discovered m2e connections,
e.g. "maven-bundle-plugin".
<p>
<a href="images/setup/discoverM2EConnectors.png">
<img src="images/setup/discoverM2EConnectors.png" alt="Click to enlarge" height="400"/>
</a>
</p>
<p>You may need to restart Eclipse.</p>.
</li>
<li>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.
</li>
<li>At this stage Eclipse may complain about
<code>GafferConfigurator</code> not being resolved. To fix these
errors, select logback-classic project properties, select "Java
Build Path" → Source → "logback-classic/src/main/groovy".
Select "Excluded" and then click on Remove.
<p>
<a href="images/setup/removeGroovyExclusions.png">
<img src="images/setup/removeGroovyExclusions.png" alt="Click to enlarge" height="400"/>
</a>
</p>
</li>
<li>
<p>Project → Clean → Clean all projects.</p>
</li>
<li>To fix the errors in the logback-examples project, you need
to instruct logback-classic to not export its Maven dependencies.
Select logback-classic project properties, select "Java
Build Path" → Order and Export and deselect "Maven Dependencies".
<p>
<a href="images/setup/deselectMavenDependenciesExport.png">
<img src="images/setup/deselectMavenDependenciesExport.png" alt="Click to enlarge" height="400"/>
</a>
</p>
</li>
<li>
<p>Project → Clean → Clean all projects.</p>
</li>
</ol>
<p><span class="label notice">Call for volunteers</span> Given that
many users prefer M2Eclipse for building projects under Eclipse
IDE, we are looking for volunteers to help simplify the steps
required for building logback with M2Eclipse.
</p>
<script src="templates/footer.js" type="text/javascript"></script>
</div>
</body>
</html>
|
