AI 147013: am: CL 147012 A readme describing the usage and limitations of MkStubs.

Original author: raphael
  Merged from: //branches/cupcake/...

Automated import of CL 147013

tools/mkstubs/README.txt

@@ -0,0 +1,90 @@
+2009/04/20.
+
+-------
+1- Goal
+-------
+
+MkStub is small tool that takes a given JAR and filters all the private stuff we don't want to
+expose, e.g.:
+- remove all private members.
+- only include a subset of classes.
+- exclude specific classes, fields or methods.
+
+Each method body is replaced by the bytecode for 'throw new RuntimeException("stub");'.
+
+
+--------
+2- Usage
+--------
+
+To control it, you give it patterns like this:
+
+  +foo  => accepts all items which signature is exactly "foo"
+  +foo* => accepts all items which signature starts by "foo"
+  -bar  => rejects all items which signature is exactly "bar"
+  -bar* => rejects all items which signature starts by "bar"
+
+Signatures are defined by:
+- a package name, e.g. com.android.blah
+- a dot followed by a class name
+- a # followed by a field or method name
+- an internal "Java method signature" that define parameters types and return value. 
+
+Examples of signatures:
+ com.android.blah
+ com.android.blah.MyClass
+ com.android.blah.MyClass$MyInnerClass
+ com.android.blah.MyClass#mPrivateField
+ com.android.blah.MyClass#getInternalStuff
+ com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V
+
+An example of configuration file:
+ +com.android.blah
+ -com.android.blah.MyClass$MyInnerClass
+ -com.android.blah.MyClass#mPrivateField
+ -com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V
+
+This would include only the indicated package yet would totally exclude the inner class
+and the specific field and the method with the exact given signature.
+
+
+
+To invoke MkStub, the syntax is:
+
+  $ java -jar mkstubs input.jar output.jar [@configfile -pattern +pattern ...]
+    
+
+
+--------------------
+3- Known Limitations
+--------------------
+
+Most of the following limitations exist solely because of the short development time and
+because the tool was designed to solve one task and not just to be super generic. That means
+any limitation here can be easily lifted.
+
+- The generated constructors are not proper. They do not invoke the matching super()
+  before the generated throw exception. Any attempt to load such a class should trigger
+  an error from the byte code verifier or the class loader.
+
+- We do not currently check whether a class or method uses only included types.
+  Suggestion: if type x.y.z is excluded, then any field, annotation, generic type,
+  method parameter or return value that uses that type should generate a fatal error.
+
+- We do not filter out private classes. Their .class will still be present in the
+  output (and stubbed), unless they are explicitly excluded.
+  This is not orthogonal to the fact that private fields and methods are automatically
+  excluded.
+
+- Private fields and methods are automatically excluded. There is no command line
+  switch to prevent that.
+
+- The stubbed source is always generated. For example if the output jar name is
+  given as ~/somedir/myfinal.jar, there will be a directory created at
+  ~/somedir/myfinal.jar_sources that will contain the equivalent Java sources.
+  There is not command line switch to prevent that.
+
+- There is no attempt to match features or behavior with DroidDoc.
+
+-- 
+end