diff options
Diffstat (limited to 'buildScripts/info.ant.xml')
| -rw-r--r-- | buildScripts/info.ant.xml | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/buildScripts/info.ant.xml b/buildScripts/info.ant.xml new file mode 100644 index 00000000..55fea8af --- /dev/null +++ b/buildScripts/info.ant.xml @@ -0,0 +1,306 @@ +<!-- + Copyright (C) 2020 The Project Lombok Authors. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. +--> +<project name="lombok.info" basedir=".." default="quickstart"> + <target name="quickstart"> + <echo> +Dear contributor, + +For full instructions and information on what this project contains, run: + + > ant help + +If you want to get started quickly: + +1. Run `ant eclipse`. +2. Start up eclipse (https://www.eclipse.org/). +3. In the menu: File > Import... > Existing Project Into Workspace +4. Browse to this directory and import it: + (${basedir}) +5. In eclipse: Run > Debug configurations... > + then pick one of the configs named `Lombok test`. +6. Run `ant dist`. + +Have fun!</echo> + </target> + + <target name="help" description="Start here!"> + <echo> +Just want to get started quickly? Run: + + > ant quickstart + +--- + +Lombok is specced to run on a wide array of underlying platforms: + +* Any JVM from 1.6 up to the upcoming next official release. +* Javac, from 1.6 up to the upcoming next official release. +* ECJ, from ecj 4.4.2 (2015/java8) up to the upcoming next official release. +* Eclipse, from eclipse-oxygen up to the upcoming next official release. + +The build is a little more complicated to cater to these requirements. + +This build script can perform the following tasks: +* IDE + Create project files so that you can work on lombok in eclipse or intellij. + Includes creating debuggable test targets. +* compile + Turn java files into class files. +* test + Run the tests against the various combinations of VM, Javac, eclipse and ecj + we support, including finding suitable VMs to run them on. +* packaging + Create the lombok 'everything' jar, that can serve as eclipse agent, as + installer, as library you include on the classpath with javac, and which + does not inject its transitive dependencies into your project namespace. +* website + Builds the website and documentation (projectlombok.org) from templates, + including creating the version history page and changelog, and deploying + builds to the website (and the maven repo hosted there). +* p2 + We host an experimental eclipse marketplace installer. + +For more info on any of these sections, run for example `ant help.IDE`. + +If you're new to lombok, you should start with `ant help.IDE`, +then move on to `ant help.test`.</echo> + </target> + + <target name="help.IDE"> + <echo> +We strongly suggest you use eclipse to develop lombok. +Experimentally, developing with intellij is possible as well. + +IDE support consists of two features: +1. Generate project files so that this directory can be imported as project. +2. Generate debug/run launch files so you can debug lombok in your IDE. + + > ant eclipse + > ant intellij + +These commands generate project files and download all dependencies required +to develop Project Lombok in the named IDE. Run these commands first, then +import this directory as project in your IDE. + + > ant eclipse.testtarget.eclipse + > ant eclipse.testtarget.ecj + > ant eclipse.testtarget.javac + +These 3 commands generate launch targets (these appear in your debug menu), +for testing the stated platform (eclipse, ecj, or javac) and will ask you +which version of the VM and the relevant platform are to be targeted by +these tests. Note that `ant eclipse` already generates default test targets, +you don't need these unless you're specifically testing lombok behaviour on +some specific version of the JVM or a target platform. + +NB: No debug/launch targets are currently generated for intellij. +Got the know how? We'd love a contribution!</echo> + </target> + + <target name="help.compile"> + <echo> +The build compilation system is self contained and generally invoked by the +other jobs this build script can do; you rarely need to mess with it. + +The compilation is quite complicated; parts of lombok are injected into +for example eclipse at runtime via an agent mechanism. To produce the bytecode +that is to be injected, we need to compile against various different versions +of the core java libraries as well as eclipse/ecj. To make this process smooth +and fast, lombok has a 'stubs' concept: We have signature-only versions of +various classes of other libraries. We compile these first, then we compile +the rest of lombok with these stub classes on the classpath, and then we +package lombok without the stubs. + +Various bits of lombok are targeted at different versions, and therefore, +different parts of lombok are compiled with different `-release` targets. + + > ant compile + +Compiles lombok itself + + > ant compile.support + +Compiles code that isn't part of the lombok distribution, but which is used +for other jobs; For example, eclipse debug target generation, and fetching +the current lombok stable release version number on offer at +the projectlombok.org website involve java code.</echo> + </target> + + <target name="help.packaging"> + <echo> +Lombok is shipped as an 'everything' jar; it is a stand-alone java app, +with both a GUI and a command line interface, it's an agent, it's an +annotation processor, and it's a module. + +In addition, lombok is a compile-time only dependency, designed to be included +in every project a lombok user has. Therefore, we don't want any of the +lombok classes that you aren't meant to use directly to be visible, +showing up in auto-complete dialogs. Starting with JDK9, the module system's +'export' feature does a lot of this, but we also want to avoid contaminating +things on JDK8 and below. As a consequence, lombok uses a classloader system, +and most classes are included in the jar with a different name, not as +.class files, thus avoiding contaminating the namespace. + +The packaging targets take care of setting up the file rename as well as +registering all the various manifest and file entries needed so that lombok +can be an everything jar. + + > ant dist + +packages the lombok build into a single jar. + + > ant maven + > ant maven.publish + +'maven' packages the lombok build ready to upload to mavencentral (sonatype). +'maven.publish' also sends this via the lombok server to oss.sonatype.org. + +</echo> + </target> + + <target name="help.test"> + <echo> +Lombok tests need to be run against a targeted platform. + + > ant test.javacCurrent + > ant test.javac6 + > ant test.javac8 + > ant test.javac11 + > ant test.javac14 + +This runs the test suite that tests lombok on javac, as well as testing +the delombok feature. + +`javacCurrent` runs the tests on the JVM running this build: ${ant.java.version} + +`javac6` and `javac8` are run on the JVM running this build, by downloading +the complete java runtime classes from those versions, including javac, and +using module limits to exclude your VM's own javac. + +You _DO NOT_ need an installed JDK1.6 or JDK1.8 to run these. + +`javac11`, `javac14`, etc require that you have a JDK of that version +installed on your system. The build will automatically find such a JDK in most +cases; alternatively, the system will ask you to provide a path to them. +The tests are then run by invoking that VM to run them. + +You can force a particular VM by making a file named `jvm.locations`, and putting +in it, for example: + + j11 = /Library/Java/JavaVirtualMachines/jdk-11.jdk/Contents/Home + +Or just enter the path your VM installation when prompted, and the build will +automatically create this file for you to remember your choice. + + > ant test.eclipse-oxygen + > ant test.eclipse-202006 + +This runs the test suite that tests lombok on eclipse/ecj. + +The tests are run on your current VM (${ant.java.version}), fetching +the relevant bits of the chosen eclipse release to test against. + + > ant test + +Runs the 'default' targets for all supported platforms. This should catch +most problems. + + > ant test.broad + +Runs tests against a selection of versions designed to catch virtually all +problems. Doesn't quite test _every_ supported combination. + + > ant test.compile + +Compiles the test suite; generally invoked by the other test targets; +you don't need to explicitly invoke this yourself.</echo> + </target> + + <target name="help.website"> + <echo> +This build also builds the website, which is a static site generated via +freemarker templates. Parts of the site build also involve other custom +software, such as building the 'all available versions' page by checking +the available versions on the live website, compiling markdown +(as used by the changelog) into html, and generated color-coded syntax +in HTML for the example snippets. + + > ant changelog.build + +Turns the changelog at doc/changelog.markdown into +build/website/changelog.html. + + > ant website.build + > ant website.pack + > ant website.publish + +'build' Builds the website (by for example applying freemarker templates) into +build/website. +'pack' bzips this up, ready to ship to the server. +'publish' sends this to the server and runs a script to deploy. + + > ant latest-changes.build + +Makes a changelog variant that lists only the newest changes; it is included +in the distribution for convenience. + + > ant javadoc.build + > ant javadoc.pack + > ant javadoc.publish + +'build' Builds the javadoc into build/api. +'pack' bzips this up, ready to ship to the server. +'publish' sends this to the server and runs a script to deploy. + + > ant edge.pack + > ant edge.publish + +'pack' creates a bzip with all relevant files needed to deploy a new edge +release to the server: A fresh build of the lombok everything jar, plus the +maven repo update so that the edge release can be fetched as a maven dep, +and an update to the download-edge page listing the latest changes included +in the edge release. + +'publish' sends this to the server, runs a script server-side to deploy the +content, and updates a git tag on success.</echo> + </target> + + <target name="help.p2"> + <echo> +This is still an experimental feature. + +We ship lombok as an eclipse plugin. The plugin isn't much of a plugin; the +install script of the plugin fulfills the same role as lombok's installer +(which is: add a line configuring lombok as an agent during eclipse bootup), +and the uninstall script removes it. + + > ant eclipsep2.build + > ant eclipsep2.pack + > ant eclipsep2.publish + +'build' generates the various files required to appear as an eclipse plugin, +and makes the jar(s). +'pack' makes a bzip ready to ship to a server. +'publish' ships it and runs a script server-side to put these files in the +right place; requires SSH access to the server.</echo> + </target> +</project> |