Home | History | Annotate | only in /development/tools/mkstubs
Up to higher level directory
NameDateSize
.classpath15-Nov-2011503
.gitignore15-Nov-20115
.project15-Nov-2011383
Android.mk15-Nov-2011848
manifest.txt15-Nov-201137
README.txt15-Nov-20113.1K
src/15-Nov-2011
tests/15-Nov-2011

README.txt

      1 2009/04/20.
      2 
      3 -------
      4 1- Goal
      5 -------
      6 
      7 MkStub is small tool that takes a given JAR and filters all the private stuff we don't want to
      8 expose, e.g.:
      9 - remove all private members.
     10 - only include a subset of classes.
     11 - exclude specific classes, fields or methods.
     12 
     13 Each method body is replaced by the bytecode for 'throw new RuntimeException("stub");'.
     14 
     15 
     16 --------
     17 2- Usage
     18 --------
     19 
     20 To control it, you give it patterns like this:
     21 
     22   +foo  => accepts all items which signature is exactly "foo"
     23   +foo* => accepts all items which signature starts by "foo"
     24   -bar  => rejects all items which signature is exactly "bar"
     25   -bar* => rejects all items which signature starts by "bar"
     26 
     27 Signatures are defined by:
     28 - a package name, e.g. com.android.blah
     29 - a dot followed by a class name
     30 - a # followed by a field or method name
     31 - an internal "Java method signature" that define parameters types and return value. 
     32 
     33 Examples of signatures:
     34  com.android.blah
     35  com.android.blah.MyClass
     36  com.android.blah.MyClass$MyInnerClass
     37  com.android.blah.MyClass#mPrivateField
     38  com.android.blah.MyClass#getInternalStuff
     39  com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V
     40 
     41 An example of configuration file:
     42  +com.android.blah
     43  -com.android.blah.MyClass$MyInnerClass
     44  -com.android.blah.MyClass#mPrivateField
     45  -com.android.blah.MyClass#getInternalStuff(Ljava/lang/String;I)V
     46 
     47 This would include only the indicated package yet would totally exclude the inner class
     48 and the specific field and the method with the exact given signature.
     49 
     50 
     51 
     52 To invoke MkStub, the syntax is:
     53 
     54   $ java -jar mkstubs input.jar output.jar [@configfile -pattern +pattern ...]
     55     
     56 
     57 
     58 --------------------
     59 3- Known Limitations
     60 --------------------
     61 
     62 Most of the following limitations exist solely because of the short development time and
     63 because the tool was designed to solve one task and not just to be super generic. That means
     64 any limitation here can be easily lifted.
     65 
     66 - The generated constructors are not proper. They do not invoke the matching super()
     67   before the generated throw exception. Any attempt to load such a class should trigger
     68   an error from the byte code verifier or the class loader.
     69 
     70 - We do not currently check whether a class or method uses only included types.
     71   Suggestion: if type x.y.z is excluded, then any field, annotation, generic type,
     72   method parameter or return value that uses that type should generate a fatal error.
     73 
     74 - We do not filter out private classes. Their .class will still be present in the
     75   output (and stubbed), unless they are explicitly excluded.
     76   This is not orthogonal to the fact that private fields and methods are automatically
     77   excluded.
     78 
     79 - Private fields and methods are automatically excluded. There is no command line
     80   switch to prevent that.
     81 
     82 - The stubbed source is always generated. For example if the output jar name is
     83   given as ~/somedir/myfinal.jar, there will be a directory created at
     84   ~/somedir/myfinal.jar_sources that will contain the equivalent Java sources.
     85   There is not command line switch to prevent that.
     86 
     87 - There is no attempt to match features or behavior with DroidDoc.
     88 
     89 -- 
     90 end
     91