diff options
Diffstat (limited to 'website2/templates/features/configuration.html')
| -rw-r--r-- | website2/templates/features/configuration.html | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/website2/templates/features/configuration.html b/website2/templates/features/configuration.html new file mode 100644 index 00000000..db3fc736 --- /dev/null +++ b/website2/templates/features/configuration.html @@ -0,0 +1,93 @@ +<#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. + </@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: + <div class="snippet example"> + <code>java -jar lombok.jar config -g --verbose</code> + </div> + 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.suppressConstructorProperties</code> + </dt><dd> + If <code>true</code>, lombok will not generate a <code>@java.beans.ConstructorProperties</code> annotation when generating constructors. This is particularly useful for GWT and Android development. + </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: + <div class="snippet example"> + <code>lombok.log.fieldName = foobar</code> + </div> + and in <code>/Users/me/projects/MyProject/lombok.config</code> you have: + <div class="snippet example"> + <code>lombok.log.fieldName = xyzzy</code> + </div> + 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: + <div class="snippet example"> + <code>clear lombok.val.flagUsage</code> + </div> + </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: + <div class="snippet example"> + <code>lombok.accessors.prefix += m_</code> + </div> + </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> + <h3>Global config keys</h3> + + <p> + To stop lombok from looking at parent directories for more configuration files, the special key: + <div class="snippet example"> + <code>config.stopBubbling = true</code> + </div> + can be included. We suggest you put this in the root of your workspace directory. + </p><p> + Lombok normally adds <code>@javax.annotation.Generated</code> annotations to all generated nodes where possible. You can stop this with: + <div class="snippet example"> + <code>lombok.addGeneratedAnnotation = false</code> + </div> + </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: + <div class="snippet example"> + <code>lombok.extern.findbugs.addSuppressFBWarnings = true</code> + </div> + </p> + </@f.featureSection> +</@f.scaffold> |