| Raphael Moll | 6aa2c49 | 2009-04-20 15:41:59 -0700 | [diff] [blame] | 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 |