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
|
<#import "_features.html" as f>
<@f.scaffold title="Configuration system" logline="Lombok, made to order: Configure lombok features in one place for your entire project or even your workspace.">
<@f.history>
The configuration system was introduced in lombok 1.14.<br />
The <a href="#import"><code>import</code> directive</a> was added in lombok 1.18.12.<br />
The <a href="#addNullAnnotations"><code>lombok.addNullAnnotations</code> configuration key</a> was added in lombok 1.18.12.<br />
</@f.history>
<@f.overview>
<p>
You can create <code>lombok.config</code> files in any directory and put configuration directives in it. These apply to all source files in this directory and all child directories.<br />
The configuration system is particularly useful for configurable aspects of lombok which tend to be the same across an entire project, such as the name of your log variable. The configuration system can also be used to tell lombok to flag any usage of some lombok feature you don't like as a warning or even an error.
</p><p>
Usually, a user of lombok puts a <code>lombok.config</code> file with their preferences in a workspace or project root directory, with the special <code>config.stopBubbling = true</code> key to tell lombok this is your root directory. You can then create <code>lombok.config</code> files in any subdirectories (generally representing projects or source packages) with different settings.
</p><p>
An up to date list of all configuration keys supported by your version of lombok can be generated by running:
<ol class="snippet example cmd">
<li><code>java -jar lombok.jar config -g --verbose</code></li>
</ol>
The output of the <em>config</em> tool is itself a valid <code>lombok.config</code> file.<br />
The <em>config</em> tool can also be used to display the complete lombok configuration used for any given directory or source file by supplying these as arguments.
</p><p>
A sample of available configuration options (see the feature pages of the lombok features for their related config keys, as well as <code>java -jar lombok.jar config -g</code> for the complete list):
<dl>
<dt>
<code>lombok.accessors.chain</code>
</dt><dd>
If set to <code>true</code>, generated setters will 'chain' by default (They will return <code>this</code> instead of having a <code>void</code> return type).
</dd><dt>
<code>lombok.accessors.fluent</code>
</dt><dd>
If set to <code>true</code>, generated setters and getters will simply be named the same as the field name, without a <code>get</code> or <code>set</code> prefix.
</dd><dt>
<code>lombok.anyConstructor.addConstructorProperties</code>
</dt><dd>
If <code>true</code>, lombok will generate a <code>@java.beans.ConstructorProperties</code> annotation when generating constructors. Note that you'll need to depend on module 'java.desktop' if you're using jigsaw.
</dd><dt>
<code>lombok.log.fieldName</code>
</dt><dd>
The name of the generated log field (default: <code>log</code>).
</dd><dt>
<code>lombok.<em>(featureName)</em>.flagUsage</code>
</dt><dd>
Allows you to forcibly stop or discourage use of a lombok feature. Legal values for this key are <code>warning</code> or <code>error</code>. Some examples of values for <em>(featureName)</em> are: "<code>experimental</code>" (flags use of any of the <a href="/features/experimental">experimental</a> features)</li>, "<a href="/features/Builder"><code>builder</code></a>", "<a
href="/features/SneakyThrows"><code>sneakyThrows</code></a>", or "<a href="/features/experimental/ExtensionMethod"><code>extensionMethod</code></a>".
</dd>
</dl>
</p><p>
Configuration files are hierarchical: Any configuration setting applies to all source files in that directory, and all source files in subdirectories, but configuration settings closer to the source file take precedence. For example, if you have in <code>/Users/me/projects/lombok.config</code> the following:
<ol class="snippet example oneliner">
<li><code>lombok.log.fieldName = foobar</code></li>
</ol>
and in <code>/Users/me/projects/MyProject/lombok.config</code> you have:
<ol class="snippet example oneliner">
<li><code>lombok.log.fieldName = xyzzy</code></li>
</ol>
Then the various <a ng-click="toFeature('log')"><code>@Log</code></a> annotations will use <code>foobar</code> instead of the default <code>log</code> as a field name to generate in all your projects, except for your project in <code>/Users/me/projects/MyProject</code>, where <code>xyzzy</code> is used instead.
</p><p>
To restore a configuration key set by a parent config file back to the default, the <code>clear</code> option can be used. For example, if a parent configuration file has configured all use of <code>val</code> to emit a warning, you can turn off the warnings for a subdirectory by including in it a <code>lombok.config</code> file with:
<ol class="snippet example oneliner">
<li><code>clear lombok.val.flagUsage</code></li>
</ol>
</p><p>
Some configuration keys take lists. For lists, use <code>+=</code> to add an entry. You can remove a single item from the list (useful to undo a parent configuration file's setting) with <code>-=</code>. For example:
<ol class="snippet example oneliner">
<li><code>lombok.accessors.prefix += m_</code></li>
</ol>
</p><p>
Comments can be included in <code>lombok.config</code> files; any line that starts with <code>#</code> is considered a comment.
</p>
</@f.overview>
<@f.featureSection>
<@f.main.h3 title="Global config keys" />
<p>
These configuration keys have an effect on many or all lombok features, or on the configuration system itself.
</p><p>
To stop lombok from looking at parent directories for more configuration files, the special key:
<ol class="snippet example oneliner">
<li><code>config.stopBubbling = true</code></li>
</ol>
can be included. We suggest you put this in the root of your workspace directory.
</p><p id="addNullAnnotations">
Lombok can add nullity annotations (usually called <code>@NonNull</code> and <code>@Nullable</code>) whenever it makes sense to do so; think of generated <a href="ToString"><code>toString</code></a> and <a href="with"><code>withX</code> methods (these never return null), or the parameter of a generated <a href="EqualsAndHashCode"><code>equals</code></a> method, which is allowed to be null, and requires such an annotation if you've set up your IDE for strict null checks as well as 'parameters are non-null by default'. There are many such libraries; you must tell lombok which one to use. By default, no such annotations are added. Enable this feature with:
<ol class="snippet example oneLiner">
<li><code>lombok.addNullAnnotations = <em><flavor></em></code></li>
</ol>
Many <em>flavors</em> are available: <code>javax</code> (=JSR305; not recommended), <code>eclipse</code>, <code>jetbrains</code>, <code>netbeans</code>, <code>androidx</code>, <code>android.support</code> (deprecated within android), <code>checkerframework</code> (recommended), <code>findbugs</code>, <code>spring</code>, <code>jml</code>, or define your own via <code>CUSTOM:fully.qualified.NonNullAnnotation:fully.qualified.NullableAnnotation</code>; if your nullity annotation is solely of the type use style (it annotates types, such as eclipse's and checkerframework's offerings, versus annotating methods and parameters), the format is <code>CUSTOM:TYPE_USE:nonnullanno:nullableanno</code>.<br />
<em>This feature was added in lombok v1.18.12</em>.<br />
</p><p>
Lombok can be configured to add <code>@lombok.Generated</code> annotations to all generated nodes where possible; useful for JaCoCo (which has built in support),
or other style checkers and code coverage tools:
<ol class="snippet example oneliner">
<li><code>lombok.addLombokGeneratedAnnotation = true</code></li>
</ol>
</p><p>
Lombok can add the <code>@SuppressFBWarnings</code> annotation which is useful if you want to run <a href="http://findbugs.sourceforge.net/">FindBugs</a> on your class files. To enable this feature, make sure findbugs is on the classpath when you compile, and add the following config key:
<ol class="snippet example oneliner">
<li><code>lombok.extern.findbugs.addSuppressFBWarnings = true</code></li>
</ol>
</p>
</@f.featureSection>
<@f.featureSection>
<@f.main.h3 title="Config keys that can affect any source file" />
<p>
These config keys can make lombok affect source files even if they have 0 lombok annotations in them.<br />
<ol class="snippet example">
<li><code>lombok.fieldDefaults.defaultPrivate = true</code></li>
<li><code>lombok.fieldDefaults.defaultFinal = true</code></li>
</ol>
Turning either of these options on means lombok will make <em>every</em> field in <em>every</em> source file final and/or private unless it has an explicit access modifier or annotation to suppress this. <a href="experimental/FieldDefaults">See the <code>@FieldDefaults</code> documentation for more</a>.
</p>
</@f.featureSection>
<@f.featureSection>
<@f.main.h3 id="import" title="Importing the configuration from a different file" />
<p>
At the top of a configuration file it is possible to import other configuration files. Imported files don't have to be called <code>lombok.config</code> and can have any file extension (or even none).<br />
<ol class="snippet example">
<li><code>import ../configuration/model.config</code></li>
</ol>
The location of an imported file is resolved relative to the file that imports it.
</p><p>
For shared projects, it makes sense to always use relative paths. For individuals, it is also possible to use absolute paths.<br />
<ol class="snippet example">
<li><code># Linux</code></li>
<li><code>import /etc/lombok/model.config</code></li>
<li><code># Windows</code></li>
<li><code>import d:/lombok/model.config</code></li>
</ol>
</p><p>
Configuration files can import multiple configuration files as long as they are specified before any configuration key.
The system behaves as if the contents of the imported file are at the location of the <code>import</code> declaration.
</p><p>
The way the configuration system works is that duplicate entries are effectively ignored. It is a last-wins. Lombok will only
process a configuration file once when resolving a specific value. This allows you to import the same files from different
configuration files, and even create loops without any problems.
</p><p>
It is also possible to import files from <code>.jar</code> and <code>.zip</code> files.<br />
<ol class="snippet example">
<li><code># Use 'lombok.config' from the root of the archive.</code></li>
<li><code>import ../deps/lombok-config.jar</code></li>
<li><code># Use a given file in the archive.</code></li>
<li><code>import ../deps/lombok-config.zip!base/model.config</code></li>
</ol>
Configuration files inside archives can import other configuration files, provided that they are in the same archive.
</p><p>
When importing files, it is possible to use environment variables.<br />
<ol class="snippet example">
<li><code># Environment variables are names surrounded by angle brackets (<, >).</code></li>
<li><code># They are replaced by System.getenv(name), if present.</code></li>
<li><code>import <JAVA_PROJECTS>/shared.config</code></li>
<li><code># A tilde (~) at the start gets replaced by System.getProperty("user.home", "~").</code></li>
<li><code>import ~/my.config</code></li>
</ol>
As with absolute paths, this is more useful for individuals than for shared projects.
</p><p>
<em>This feature was added in lombok v1.18.12.</em>
</p>
</@f.featureSection>
</@f.scaffold>
|
