From 22e9c25db63426c542ae0a655f29b69180bd92f7 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 10 Apr 2018 00:23:36 +0200 Subject: [PATCH] =?UTF-8?q?[website]=20Added=20a=20section=20on=20contribu?= =?UTF-8?q?ting=20to=20lombok,=20with=20documentation=20on=20how=20lombok?= =?UTF-8?q?=E2=80=99s=20execution=20path=20works.=20See=20pull=20request?= =?UTF-8?q?=20#71?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- website/extra/htaccess | 10 ++++- website/templates/_scaffold.html | 2 +- .../{ => contributing}/contributing.html | 2 +- website/templates/contributing/index.html | 17 +++++++ .../contributing/lombok-execution-path.html | 45 +++++++++++++++++++ 5 files changed, 72 insertions(+), 4 deletions(-) rename website/templates/{ => contributing}/contributing.html (98%) create mode 100644 website/templates/contributing/index.html create mode 100644 website/templates/contributing/lombok-execution-path.html diff --git a/website/extra/htaccess b/website/extra/htaccess index db3393af..2d5b6b2a 100644 --- a/website/extra/htaccess +++ b/website/extra/htaccess @@ -22,8 +22,6 @@ RewriteRule ^all-versions$ /all-versions.html [L,END] RewriteRule ^all-versions(\.html)?$ /all-versions [NC,R=301] RewriteRule ^disable-checked-exceptions$ /disable-checked-exceptions.html [L,END] RewriteRule ^disable-checked-exceptions(\.html)?$ /disable-checked-exceptions [NC,R=301] -RewriteRule ^contributing$ /contributing.html [L,END] -RewriteRule ^contributing(\.html)?$ /contributing [NC,R=301] RewriteRule ^supporters$ /supporters.html [L,END] RewriteRule ^supporters(.html)?$ /supporters [NC,R=301] RewriteRule ^order-license-info$ /order-license-info.html [L,END] @@ -31,6 +29,14 @@ RewriteRule ^order-?license-?info(.html)?$ /order-license-info [NC,R=301] RewriteRule ^order-license$ /order-license.html [L,END] RewriteRule ^order-?license(.html)?$ /order-license [NC,R=301] +RewriteRule ^contributing/index$ /contributing/index.html [L,END] +RewriteRule ^contributing(\.html)?$ /contributing/index [NC,R=301] +RewriteRule ^contributing/index(\.html)?$ /contributing/index [NC,R=301] +RewriteRule ^contributing/contributing$ /contributing/contributing.html [L,END] +RewriteRule ^contributing/contributing(\.html)?$ /contributing/contributing [NC,R=301] +RewriteRule ^contributing/lombok-execution-path$ /contributing/lombok-execution-path.html [L,END] +RewriteRule ^contributing/lombok-execution-path(\.html)?$ /contributing/lombok-execution-path [NC,R=301] + <#list setupPages as pg> RewriteRule ^setup/${pg?no_esc}$ /setup/${pg?no_esc}.html [L,END] RewriteRule ^setup/${pg?no_esc}(\.html)?$ /setup/${pg?no_esc} [NC,R=301] diff --git a/website/templates/_scaffold.html b/website/templates/_scaffold.html index e3096d7d..7acfb6b6 100644 --- a/website/templates/_scaffold.html +++ b/website/templates/_scaffold.html @@ -102,7 +102,7 @@ ga('send', 'pageview');
  • diff --git a/website/templates/contributing.html b/website/templates/contributing/contributing.html similarity index 98% rename from website/templates/contributing.html rename to website/templates/contributing/contributing.html index 16d68f32..8da9b827 100644 --- a/website/templates/contributing.html +++ b/website/templates/contributing/contributing.html @@ -1,4 +1,4 @@ -<#import "/_scaffold.html" as main> +<#import "../_scaffold.html" as main> <@main.scaffold title="Contribute">
    diff --git a/website/templates/contributing/index.html b/website/templates/contributing/index.html new file mode 100644 index 00000000..4f6a1bca --- /dev/null +++ b/website/templates/contributing/index.html @@ -0,0 +1,17 @@ +<#import "../_scaffold.html" as main> + +<@main.scaffold title="Documentation for being a lombok developer"> +
    +
    + <@main.h1 title="Documentation for lombok developers" /> +
    +
    + <@main.feature title="contributing" href="contributing"> + Want to contribute to Project Lombok? Start by reading this introduction. + + <@main.feature title="execution path" href="lombok-execution-path"> + Discusses how lombok ends up being invoked, and how it gets around to transforming code being compiled / edited. + +
    +
    + diff --git a/website/templates/contributing/lombok-execution-path.html b/website/templates/contributing/lombok-execution-path.html new file mode 100644 index 00000000..1fa2f697 --- /dev/null +++ b/website/templates/contributing/lombok-execution-path.html @@ -0,0 +1,45 @@ +<#import "../_scaffold.html" as main> + +<@main.scaffold title="Lombok Execution Path"> +
    +
    + <@main.h1 title="Lombok Execution Path" /> +
    + <@main.h1 title="Javac: Launching as annotation processor" /> +
    +

    + With javac (and netbeans, maven, gradle, and most other build systems), lombok runs as an annotation processor. +

    + Lombok is on the classpath, and javac will load every META-INF/services/javax.annotation.processing.Processor file on the classpath it can find, reading each line and loading that class, then executing it as an annotation processor. lombok.jar has this file, it lists lombok.launch.AnnotationProcessorHider$AnnotationProcessor as entry. +

    + This class is not actually visible (it is public, but its outer class (AnnotationProcessorHider) is package private, making it invisible to java-the-language), however, it is considered visible for the purposes of java-the-VM and therefore it will run. This convoluted trick is used to ensure that anybody who develops with lombok on the classpath doesn't get lombok's classes or lombok's dependencies injected into their 'namespace' (for example, if you add lombok to your project, your IDE will not start suggesting lombok classes for auto-complete dialogs). +

    + The lombok.launch.AnnotationProcessorHider$AnnotationProcessor class is loaded by javac, instantiated, and init() is called on it. This class starts lombok's ShadowClassLoader; it finds the jar file it is in, then will start loading classes from this jar file. It looks not for files ending in .class like normal loaders, it looks for files ending in .SCL.lombok instead (this too is for the purpose of hiding lombok's classes from IDEs and such). Via this classloader, the real annotation processor is launched, which is class lombok.core.AnnotationProcessor. +

    + The lombok.core.AnnotationProcessor is also a delegating processor. It can delegate to one of 2 sub-processors based on the environment lombok finds itself in: If it's javac, class lombok.javac.apt.LombokProcessor is used (and if the plexus compiler framework is used, which can be the case when compiling with javac, some extra code runs to patch lombok into its modular classloading architecture). If it's ecj (eclipse's compiler, which means we're either running inside eclipse itself, or being invoked as annotation processor for ecj, the standalone eclipse compiler), errors/warnings are injected into the compilation process to tell the user they should use different parameters to use lombok in eclipse/ecj. +

    + lombok.javac.apt.LombokProcessor is the 'real' annotation processor that does the work of transforming your code. +

    + code transformation is fundamentally a cyclic concept: To generate some code you want to know about the code (which annotations are in it, for example), but when you generate new code, interpreting it means we start over. The same applies to lombok itself: Some of lombok's transformations add methods which then have an effect on other lombok transformations. Because of that, lombok divides up the handlers into 'levels'. All handlers at the highest level are executed, then a new annotation round is forced (which integrates generated stuff into the symbol tables and such), and then the handlers at the next level are executed. These levels are indicated via the @HandlerPriority annotation. You force javac to run another round by generating a file. We don't actually want to generate any files, so we generate a dummy file and patch the javac filer to not actually save lombok-generated dummy files anywhere. The various HandleX classes, which apply the actual lombok transformations, are stored in HandlerLibrary which uses SPI to discover the handle classes. +

    +
    + <@main.h1 title="Eclipse/ECJ: Launching as agent" /> +
    +

    + With ecj and eclipse, lombok starts as an 'agent'. That's a bit like a debugger: It lets lombok inspect raw class bytecode before the JVM actually loads these classes, and lombok will modify this code in order to ensure that ecj/eclipse involves lombok in the compilation process. +

    + The patching of classes is done by the code in the src/eclipseAgent sourcedir. Note that the patching code has to patch equinox, the eclipse module system, to ensure lombok and the java compilation module (The 'JDT' module, in eclipse parlance) can see each other. +

    + A bunch of ad-hoc fixes to issues (such as the eclipse format-my-code feature needing a few tactical bytecode patches to ensure it doesn't mess up formatting source) are applied, but the main 'run lombok as part of the compilation process' hook injected into ecj/eclipse leads to the lombok.eclipse.TransformEclipseAST class, which can be considered the entrypoint. Unless you want to mess with how lombok is loaded into eclipse/ecj, start there. +

    + Each HandleX class is discovered via SPI and lombok will invoke the handle classes as needed. Handle classes find lombok annotations and apply the desired transformations. The handlers are in the lombok.eclipse.handlers package from the src/core sourcedir. +

    +
    + <@main.h1 title="VSCode and IntelliJ: Launching as a plugin" /> +
    +

    + Lombok support in these two IDEs is taken care of by plugins for these IDEs. +

    +
    +
    +