You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
91 lines
3.1 KiB
91 lines
3.1 KiB
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
|