From 22e9c25db63426c542ae0a655f29b69180bd92f7 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Tue, 10 Apr 2018 00:23:36 +0200 Subject: [website] Added a section on contributing to lombok, with documentation on how lombok’s execution path works. See pull request #71 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- website/templates/contributing/contributing.html | 40 +++++++++++++++++++ website/templates/contributing/index.html | 17 ++++++++ .../contributing/lombok-execution-path.html | 45 ++++++++++++++++++++++ 3 files changed, 102 insertions(+) create mode 100644 website/templates/contributing/contributing.html create mode 100644 website/templates/contributing/index.html create mode 100644 website/templates/contributing/lombok-execution-path.html (limited to 'website/templates/contributing') diff --git a/website/templates/contributing/contributing.html b/website/templates/contributing/contributing.html new file mode 100644 index 00000000..8da9b827 --- /dev/null +++ b/website/templates/contributing/contributing.html @@ -0,0 +1,40 @@ +<#import "../_scaffold.html" as main> + +<@main.scaffold title="Contribute"> +
+
+ <@main.h1 title="Contributing to Project Lombok's development" /> +
+ You can choose to become a project lombok licensee or support us on patreon. +
+
+ <@main.h1 title="How to work on Project Lombok yourself" /> +
+ Project Lombok is being developed via the lombok git repository on github. +
+

+ If you want to start development on lombok, clone the repository and run ant eclipse or ant intellij, then open the working directory as a project in eclipse / intellij. Because the main contributors of lombok all use eclipse, that'll probably work a little more smoothly. +

+ To produce a lombok jar, run ant dist; in general run ant -p; there's lots of stuff there, including downloading various versions of java runtimes to run the test suite against, and building this website. +

+
+ <@main.h2 title="Adding your own handlers and annotations to Lombok" /> +
+

+ If you want to extend lombok, we advise that you fork lombok and add handlers directly into the same place and package that lombok's handlers are in (lombok.javac.handlers and lombok.eclipse.handlers) – lombok does some fancy footwork to ensure various modular class loading systems don't interface with finding the lombok classes, but that system is not (currently) easily expanded to include separate jars. +

+
+ <@main.h2 title="Contributing to Project Lombok" /> +
+

+ To create new features and add them to project lombok itself, send us pull requests via github. However, before you start, discuss the feature or fix you'd like to contribute, preferably via the Project Lombok Forum. If you're going to add a new feature, make sure to post 2 snippets (one with the annotation, the other with what that would generate), similar to how the feature pages list 'with lombok' and 'without lombok' variants. +

+ We've considered many designs and features amongst ourselves and with the community, and often there are complications or interesting design choices that have already been mentioned. We'd like to share them with you before you set out. +

+ Pull requests for new features that haven't been discussed are unlikely to be accepted. Of course, if you've already built a proof of concept implementation prior to bringing a new idea to the forum, we'll take it that much more seriously. +

+ Happy coding! +

+
+
+ 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. +

+
+
+ -- cgit