Added documentation (and a minor tidbit of support) for android.

3 files changed, 281 insertions, 0 deletions

diff --git a/src/core/lombok/core/PublicApiCreatorApp.java b/src/core/lombok/core/PublicApiCreatorApp.java
new file mode 100644
index 00000000..24bcf83d
--- /dev/null
+++ b/src/core/lombok/core/PublicApiCreatorApp.java
@@ -0,0 +1,188 @@
+/*
+ * Copyright (C) 2012 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.
+ */
+package lombok.core;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.util.ArrayList;
+import java.util.Enumeration;
+import java.util.List;
+import java.util.jar.JarEntry;
+import java.util.jar.JarFile;
+import java.util.jar.JarOutputStream;
+import java.util.zip.ZipEntry;
+
+import lombok.Lombok;
+import lombok.installer.IdeFinder;
+import lombok.patcher.inject.LiveInjector;
+
+import org.mangosdk.spi.ProviderFor;
+
+@ProviderFor(LombokApp.class)
+public class PublicApiCreatorApp extends LombokApp {
+	@Override public String getAppName() {
+		return "publicApi";
+	}
+	
+	@Override public String getAppDescription() {
+		return "Creates a small lombok-api.jar with the annotations and other public API\n" +
+				"classes of all lombok features. This is primarily useful to include in your\n" +
+				"android projects.";
+	}
+	
+	@Override public int runApp(List<String> rawArgs) throws Exception {
+		String loc = ".";
+		switch (rawArgs.size()) {
+		case 0: break;
+		case 1: loc = rawArgs.get(0); break;
+		default:
+			System.err.println("Supply 1 path to specify the directory where lombok-api.jar will be created. No path means the current directory is used.");
+			return 1;
+		}
+		
+		File out = new File(loc, "lombok-api.jar");
+		int errCode = 0;
+		try {
+			errCode = writeApiJar(out);
+		} catch (Exception e) {
+			System.err.println("ERROR: Creating " + canonical(out) + " failed: ");
+			e.printStackTrace();
+			return 1;
+		}
+		
+		return errCode;
+	}
+	
+	/**
+	 * Returns a File object pointing to our own jar file. Will obviously fail if the installer was started via
+	 * a jar that wasn't accessed via the file-system, or if its started via e.g. unpacking the jar.
+	 */
+	private static File findOurJar() {
+		return new File(LiveInjector.findPathJar(IdeFinder.class));
+	}
+	
+	private int writeApiJar(File outFile) throws Exception {
+		File selfRaw = findOurJar();
+		if (selfRaw == null) {
+			System.err.println("The publicApi option only works if lombok is a jar.");
+			return 2;
+		}
+		
+		List<String> toCopy = new ArrayList<String>();
+		JarFile self = new JarFile(selfRaw);
+		try {
+			Enumeration<JarEntry> entries = self.entries();
+			
+			while (entries.hasMoreElements()) {
+				JarEntry entry = entries.nextElement();
+				String name = entry.getName();
+				if (!name.startsWith("lombok/")) continue;
+				if (name.endsWith("/package-info.class")) continue;
+				if (!name.endsWith(".class")) continue;
+				
+				String subName = name.substring(7, name.length() - 6);
+				int firstSlash = subName.indexOf('/');
+				if (firstSlash == -1) {
+					// direct member of the lombok package.
+					toCopy.add(name);
+					continue;
+				}
+				String topPkg = subName.substring(0, firstSlash);
+				if ("extern".equals(topPkg) || "experimental".equals(topPkg)) {
+					toCopy.add(name);
+				}
+			}
+		} finally {
+			self.close();
+		}
+		
+		if (toCopy.isEmpty()) {
+			System.out.println("Not generating lombok-api.jar: No lombok api classes required!");
+			return 1;
+		}
+		
+		OutputStream out = new FileOutputStream(outFile);
+		boolean success = false;
+		try {
+			JarOutputStream jar = new JarOutputStream(out);
+			for (String resourceName : toCopy) {
+				InputStream in = Lombok.class.getResourceAsStream("/" + resourceName);
+				try {
+					if (in == null) {
+						throw new Fail(String.format("api class %s cannot be found", resourceName));
+					}
+					writeIntoJar(jar, resourceName, in);
+				} finally {
+					if (in != null) in.close();
+				}
+			}
+			jar.close();
+			out.close();
+			
+			System.out.println("Successfully created: " + canonical(outFile));
+			
+			return 0;
+		} catch (Throwable t) {
+			try { out.close();} catch (Throwable ignore) {}
+			if (!success) outFile.delete();
+			if (t instanceof Fail) {
+				System.err.println(t.getMessage());
+				return 1;
+			} else if (t instanceof Exception) {
+				throw (Exception)t;
+			} else if (t instanceof Error) {
+				throw (Error)t;
+			} else {
+				throw new Exception(t);
+			}
+		}
+	}
+	
+	private void writeIntoJar(JarOutputStream jar, String resourceName, InputStream in) throws IOException {
+		jar.putNextEntry(new ZipEntry(resourceName));
+		byte[] b = new byte[65536];
+		while (true) {
+			int r = in.read(b);
+			if (r == -1) break;
+			jar.write(b, 0, r);
+		}
+		jar.closeEntry();
+		in.close();
+	}
+	
+	private static class Fail extends Exception {
+		Fail(String message) {
+			super(message);
+		}
+	}
+	
+	private static String canonical(File out) {
+		try {
+			return out.getCanonicalPath();
+		} catch (Exception e) {
+			return out.getAbsolutePath();
+		}
+	}
+}
diff --git a/website/download.html b/website/download.html
index f3bc54c5..749cd99b 100644
--- a/website/download.html
+++ b/website/download.html
@@ -62,6 +62,9 @@
 				<tr><td class="platform">Javadoc</td>
 				<td class="instruction">First delombok your code then run javadoc on the result. <a href="features/delombok.html">More&hellip;</a></td></tr>
 				
+				<tr><td class="platform">Android</td>
+				<td class="instruction">The proper way to use lombok with android is somewhat complicated but possible. <a href="setup/android.html">More&hellip;</a></td></tr>
+				
 				<tr><td class="platform">GWT</td>
 				<td class="instruction">Lombok works with GWT. <a href="setup/gwt.html">More&hellip;</a></td></tr>
 				
diff --git a/website/setup/android.html b/website/setup/android.html
new file mode 100644
index 00000000..bbcc9c66
--- /dev/null
+++ b/website/setup/android.html
@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+<html><head>
+	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+	<script src="../logi/jQuery-all.js" type="text/javascript"></script>
+	<link rel="stylesheet" type="text/css" href="../logi/reset.css" />
+	<link rel="stylesheet" type="text/css" href="../index.css" />
+	<link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" />
+	<meta name="description" content="Spice up your java" />
+	<title>Project Lombok</title>
+	<!--[if lt IE 7]><script type="text/javascript" src="../logi/iepngfix_tilebg.js"></script><![endif]--> 
+</head><body>
+	<a id="forkMe" href="http://github.com/rzwitserloot/lombok"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
+	<div class="meat">
+		<h1><a href="/">Project Lombok</a> - android instructions</h1>
+		<div id="buttonBar" class="buttonBar">
+			<a class="button" href="../features/index.html">
+				<img src="../icon_overview.png" />
+				<span>Feature Overview</span>
+			</a>
+			<a class="button" href="http://groups.google.com/group/project-lombok">
+				<img src="../icon_discussion.png" />
+				<span>Discuss / Help</span>
+			</a>
+			<a class="button" href="http://wiki.github.com/rzwitserloot/lombok/contributing">
+				<img src="../icon_contribute.png" />
+				<span>Contribute</span>
+			</a>
+			<a class="button" href="http://code.google.com/p/projectlombok/issues/list">
+				<img src="../icon_bugs.png" />
+				<span>Report an issue</span>
+			</a>
+			<div class="downloadContainer">
+				<a class="downloadLink" id="downloadLink" href="../download.html">
+					<img src="../icon_download.png" />
+					<span>Download!</span>
+				</a>
+				<div class="versionInfo">
+					Version: @VERSION@ | <a href="../changelog.html">changelog</a>
+				</div>
+			</div>
+		</div>
+		<div class="downloadHelp">
+			<p>
+			Android development with lombok is possible. Lombok should be a compile-time only dependency, as otherwise
+			the entirety of lombok will end up in your DEX files, wasting precious space on android devices. Also, errors will occur due
+			to the native libraries present in lombok.jar itself. Unfortunately, android does not (yet) understand the concept of a
+			compile-time-only dependency, so you need to mess with your build files to make it work.
+			</p><p>
+			The instructions listed below are excerpts from <a href="https://github.com/excilys/androidannotations/wiki/Cookbook">The
+			AndroidAnnotations project cookbook</a>. You may wish to refer to that documentation for complete instructions; lombok is just
+			the equivalent to <code>androidannotations-VERSION.jar</code>; there is no <code>-api</code> aspect.
+			</p>
+			<h3>Eclipse</h3>
+			<div>
+				In eclipse, create a 'lightweight' lombok jar that contains only the annotations by running:
+				<pre>
+java -jar lombok.jar publicApi</pre>
+				Then, add this jar to your android project, and, as usual, install lombok into eclipse.
+			</div>
+			<h3>Ant</h3>
+			<div>
+				<ul>
+					<li>Find <code>build.xml</code> in <code>${ANDROID_SDK_ROOT}/tools/ant/build.xml</code> and copy the <code>-compile</code> target into the paste buffer.
+					<li>Copy this to the <code>build.xml</code> of your own project, right before the <code>&lt;import file="${sdk.dir}/tools/ant/build.xml"&gt;</code> line.
+					<li>Create a <code>compile-libs</code> directory in your own project and copy the complete <code>lombok.jar</code> to it.
+					<li>Now modify the <code>&lt;classpath&gt;</code> entry inside the <code>&lt;javac&gt;</code> task in the <code>-compile</code> target you just copied:<br />
+						add <code>&lt;fileset dir="compile-libs" includes="*.jar" /&gt;</code> to it.
+				</ul>
+			</div>
+			<h3>Maven</h3>
+			<div>
+				You should be able to just follow the normal <a href="../mavenrepo/index.html">lombok with maven instructions</a>.<br />
+			</div>
+		<div class="endBar">
+		</div>
+		<div class="footer">
+			<a href="../credits.html" class="creditsLink">credits</a> | Copyright &copy; 2009-2011 The Project Lombok Authors, licensed under the <a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.
+		</div>
+	</div>
+	<script type="text/javascript">
+		var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+		document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+	</script>
+	<script type="text/javascript">
+		try {
+			var pageTracker = _gat._getTracker("UA-9884254-1");
+			pageTracker._trackPageview();
+		} catch(err) {}
+	</script>
+</body></html>