Merge "Update layoutlib create README [DO NOT MERGE]" into klp-modular-dev
This commit is contained in:
Deepanshu Gupta
committed by
Android (Google) Code Review
Android (Google) Code Review
commit
0ca0853c52
@@ -4,46 +4,45 @@
|
||||
- Description -
|
||||
---------------
|
||||
|
||||
Layoutlib_create generates a JAR library used by the Eclipse graphical layout editor
|
||||
to perform layout.
|
||||
Layoutlib_create generates a JAR library used by the Eclipse graphical layout editor to perform
|
||||
layout.
|
||||
|
||||
|
||||
- Usage -
|
||||
---------
|
||||
|
||||
./layoutlib_create path/to/android.jar destination.jar
|
||||
./layoutlib_create destination.jar path/to/android1.jar path/to/android2.jar
|
||||
|
||||
|
||||
- Design Overview -
|
||||
-------------------
|
||||
|
||||
Layoutlib_create uses the "android.jar" containing all the Java code used by Android
|
||||
as generated by the Android build, right before the classes are converted to a DEX format.
|
||||
Layoutlib_create uses a few jars from the framework containing the Java code used by Android as
|
||||
generated by the Android build, right before the classes are converted to a DEX format.
|
||||
|
||||
The Android JAR can't be used directly in Eclipse:
|
||||
- it contains references to native code (which we want to avoid in Eclipse),
|
||||
- some classes need to be overridden, for example all the drawing code that is
|
||||
replaced by Java 2D calls in Eclipse.
|
||||
- some of the classes that need to be changed are final and/or we need access
|
||||
to their private internal state.
|
||||
These jars can't be used directly in Eclipse as:
|
||||
- they contains references to native code (which we want to avoid in Eclipse),
|
||||
- some classes need to be overridden, for example all the drawing code that is replaced by Java 2D
|
||||
calls in Eclipse.
|
||||
- some of the classes that need to be changed are final and/or we need access to their private
|
||||
internal state.
|
||||
|
||||
Consequently this tool:
|
||||
- parses the input JAR,
|
||||
- modifies some of the classes directly using some bytecode manipulation,
|
||||
- filters some packages and removes those we don't want in the output JAR,
|
||||
- injects some new classes,
|
||||
- generates a modified JAR file that is suitable for the Android plugin
|
||||
for Eclipse to perform rendering.
|
||||
- generates a modified JAR file that is suitable for the Android plugin for Eclipse to perform
|
||||
rendering.
|
||||
|
||||
The ASM library is used to do the bytecode modification using its visitor pattern API.
|
||||
|
||||
The layoutlib_create is *NOT* generic. There is no configuration file. Instead all the
|
||||
configuration is done in the main() method and the CreateInfo structure is expected to
|
||||
change with the Android platform as new classes are added, changed or removed.
|
||||
The layoutlib_create is *NOT* generic. There is no configuration file. Instead all the configuration
|
||||
is done in the main() method and the CreateInfo structure is expected to change with the Android
|
||||
platform as new classes are added, changed or removed.
|
||||
|
||||
The resulting JAR is used by layoutlib_bridge (a.k.a. "the bridge"), also part of the
|
||||
platform, that provides all the necessary missing implementation for rendering graphics
|
||||
in Eclipse.
|
||||
The resulting JAR is used by layoutlib_bridge (a.k.a. "the bridge"), also part of the platform, that
|
||||
provides all the necessary missing implementation for rendering graphics in Eclipse.
|
||||
|
||||
|
||||
|
||||
@@ -58,97 +57,96 @@ The tool works in two phases:
|
||||
- Analyzer
|
||||
----------
|
||||
|
||||
The goal of the analyzer is to create a graph of all the classes from the input JAR
|
||||
with their dependencies and then only keep the ones we want.
|
||||
The goal of the analyzer is to create a graph of all the classes from the input JAR with their
|
||||
dependencies and then only keep the ones we want.
|
||||
|
||||
To do that, the analyzer is created with a list of base classes to keep -- everything
|
||||
that derives from these is kept. Currently the one such class is android.view.View:
|
||||
since we want to render layouts, anything that is sort of a view needs to be kept.
|
||||
To do that, the analyzer is created with a list of base classes to keep -- everything that derives
|
||||
from these is kept. Currently the one such class is android.view.View: since we want to render
|
||||
layouts, anything that is sort of a view needs to be kept.
|
||||
|
||||
The analyzer is also given a list of class names to keep in the output.
|
||||
This is done using shell-like glob patterns that filter on the fully-qualified
|
||||
class names, for example "android.*.R**" ("*" does not matches dots whilst "**" does,
|
||||
and "." and "$" are interpreted as-is).
|
||||
In practice we almost but not quite request the inclusion of full packages.
|
||||
The analyzer is also given a list of class names to keep in the output. This is done using
|
||||
shell-like glob patterns that filter on the fully-qualified class names, for example "android.*.R**"
|
||||
("*" does not matches dots whilst "**" does, and "." and "$" are interpreted as-is). In practice we
|
||||
almost but not quite request the inclusion of full packages.
|
||||
|
||||
The analyzer is also given a list of classes to exclude. A fake implementation of these
|
||||
classes is injected by the Generator.
|
||||
The analyzer is also given a list of classes to exclude. A fake implementation of these classes is
|
||||
injected by the Generator.
|
||||
|
||||
With this information, the analyzer parses the input zip to find all the classes.
|
||||
All classes deriving from the requested bases classes are kept.
|
||||
All classes which name matched the glob pattern are kept.
|
||||
The analysis then finds all the dependencies of the classes that are to be kept
|
||||
using an ASM visitor on the class, the field types, the method types and annotations types.
|
||||
Classes that belong to the current JRE are excluded.
|
||||
With this information, the analyzer parses the input zip to find all the classes. All classes
|
||||
deriving from the requested bases classes are kept. All classes whose name match the glob pattern
|
||||
are kept. The analysis then finds all the dependencies of the classes that are to be kept using an
|
||||
ASM visitor on the class, the field types, the method types and annotations types. Classes that
|
||||
belong to the current JRE are excluded.
|
||||
|
||||
The output of the analyzer is a set of ASM ClassReader instances which are then
|
||||
fed to the generator.
|
||||
The output of the analyzer is a set of ASM ClassReader instances which are then fed to the
|
||||
generator.
|
||||
|
||||
|
||||
- Generator
|
||||
-----------
|
||||
|
||||
The generator is constructed from a CreateInfo struct that acts as a config file
|
||||
and lists:
|
||||
- the classes to inject in the output JAR -- these classes are directly implemented
|
||||
in layoutlib_create and will be used to interface with the renderer in Eclipse.
|
||||
The generator is constructed from a CreateInfo struct that acts as a config file and lists:
|
||||
- the classes to inject in the output JAR -- these classes are directly implemented in
|
||||
layoutlib_create and will be used to interface with the renderer in Eclipse.
|
||||
- specific methods to override (see method stubs details below).
|
||||
- specific methods for which to delegate calls.
|
||||
- specific methods to remove based on their return type.
|
||||
- specific classes to rename.
|
||||
- specific classes to refactor.
|
||||
|
||||
Each of these are specific strategies we use to be able to modify the Android code
|
||||
to fit within the Eclipse renderer. These strategies are explained beow.
|
||||
Each of these are specific strategies we use to be able to modify the Android code to fit within the
|
||||
Eclipse renderer. These strategies are explained beow.
|
||||
|
||||
The core method of the generator is transform(): it takes an input ASM ClassReader
|
||||
and modifies it to produce a byte array suitable for the final JAR file.
|
||||
The core method of the generator is transform(): it takes an input ASM ClassReader and modifies it
|
||||
to produce a byte array suitable for the final JAR file.
|
||||
|
||||
The first step of the transformation is to implement the method delegates.
|
||||
|
||||
The TransformClassAdapter is then used to process the potentially renamed class.
|
||||
All protected or private classes are market as public.
|
||||
All classes are made non-final.
|
||||
Interfaces are left as-is.
|
||||
The TransformClassAdapter is then used to process the potentially renamed class. All protected or
|
||||
private classes are market as public. All classes are made non-final. Interfaces are left as-is.
|
||||
|
||||
If a method has a return type that must be erased, the whole method is skipped.
|
||||
Methods are also changed from protected/private to public.
|
||||
The code of the methods is then kept as-is, except for native methods which are
|
||||
replaced by a stub. Methods that are to be overridden are also replaced by a stub.
|
||||
If a method has a return type that must be erased, the whole method is skipped. Methods are also
|
||||
changed from protected/private to public. The code of the methods is then kept as-is, except for
|
||||
native methods which are replaced by a stub. Methods that are to be overridden are also replaced by
|
||||
a stub.
|
||||
|
||||
Finally fields are also visited and changed from protected/private to public.
|
||||
|
||||
The next step of the transformation is changing the name of the class in case
|
||||
we requested the class to be renamed. This uses the RenameClassAdapter to also rename
|
||||
all inner classes and references in methods and types. Note that other classes are
|
||||
not transformed and keep referencing the original name.
|
||||
The next step of the transformation is changing the name of the class in case we requested the class
|
||||
to be renamed. This uses the RenameClassAdapter to also rename all inner classes and references in
|
||||
methods and types. Note that other classes are not transformed and keep referencing the original
|
||||
name.
|
||||
|
||||
The class is then fed to RefactorClassAdapter which is like RenameClassAdapter but
|
||||
updates the references in all classes. This is used to update the references of classes
|
||||
in the java package that were added in the Dalvik VM but are not a part of the standard
|
||||
JVM. The existing classes are modified to update all references to these non-standard
|
||||
classes. An alternate implementation of these (com.android.tools.layoutlib.java.*) is
|
||||
injected.
|
||||
The class is then fed to RefactorClassAdapter which is like RenameClassAdapter but updates the
|
||||
references in all classes. This is used to update the references of classes in the java package that
|
||||
were added in the Dalvik VM but are not a part of the standard JVM. The existing classes are
|
||||
modified to update all references to these non-standard classes. An alternate implementation of
|
||||
these (com.android.tools.layoutlib.java.*) is injected.
|
||||
|
||||
The ClassAdapters are chained together to achieve the desired output. (Look at section
|
||||
2.2.7 Transformation chains in the asm user guide, link in the References.) The order of
|
||||
execution of these is:
|
||||
RenameClassAdapter and RefactorClassAdapter both inherit from AbstractClassAdapter which changes the
|
||||
class version (version of the JDK used to compile the class) to 50 (corresponding to Java 6), if the
|
||||
class was originally compiled with Java 7 (version 51). This is because we don't currently generate
|
||||
the StackMapTable correctly and Java 7 VM enforces that classes with version greater than 51 have
|
||||
valid StackMapTable. As a side benefit of this, we can continue to support Java 6 because Java 7 on
|
||||
Mac has horrible font rendering support.
|
||||
|
||||
The ClassAdapters are chained together to achieve the desired output. (Look at section 2.2.7
|
||||
Transformation chains in the asm user guide, link in the References.) The order of execution of
|
||||
these is:
|
||||
ClassReader -> [DelegateClassAdapter] -> TransformClassAdapter -> [RenameClassAdapter] ->
|
||||
RefactorClassAdapter -> ClassWriter
|
||||
|
||||
- Method stubs
|
||||
--------------
|
||||
|
||||
As indicated above, all native and overridden methods are replaced by a stub.
|
||||
We don't have the code to replace with in layoutlib_create.
|
||||
Instead the StubMethodAdapter replaces the code of the method by a call to
|
||||
OverrideMethod.invokeX(). When using the final JAR, the bridge can register
|
||||
As indicated above, all native and overridden methods are replaced by a stub. We don't have the
|
||||
code to replace with in layoutlib_create. Instead the StubMethodAdapter replaces the code of the
|
||||
method by a call to OverrideMethod.invokeX(). When using the final JAR, the bridge can register
|
||||
listeners from these overridden method calls based on the method signatures.
|
||||
|
||||
The listeners are currently pretty basic: we only pass the signature of the
|
||||
method being called, its caller object and a flag indicating whether the
|
||||
method was native. We do not currently provide the parameters. The listener
|
||||
can however specify the return value of the overridden method.
|
||||
The listeners are currently pretty basic: we only pass the signature of the method being called, its
|
||||
caller object and a flag indicating whether the method was native. We do not currently provide the
|
||||
parameters. The listener can however specify the return value of the overridden method.
|
||||
|
||||
This strategy is now obsolete and replaced by the method delegates.
|
||||
|
||||
@@ -156,97 +154,89 @@ This strategy is now obsolete and replaced by the method delegates.
|
||||
- Strategies
|
||||
------------
|
||||
|
||||
We currently have 6 strategies to deal with overriding the rendering code
|
||||
and make it run in Eclipse. Most of these strategies are implemented hand-in-hand
|
||||
by the bridge (which runs in Eclipse) and the generator.
|
||||
We currently have 6 strategies to deal with overriding the rendering code and make it run in
|
||||
Eclipse. Most of these strategies are implemented hand-in-hand by the bridge (which runs in Eclipse)
|
||||
and the generator.
|
||||
|
||||
|
||||
1- Class Injection
|
||||
|
||||
This is the easiest: we currently inject the following classes:
|
||||
- OverrideMethod and its associated MethodListener and MethodAdapter are used
|
||||
to intercept calls to some specific methods that are stubbed out and change
|
||||
their return value.
|
||||
- CreateInfo class, which configured the generator. Not used yet, but could
|
||||
in theory help us track what the generator changed.
|
||||
- AutoCloseable and Objects are part of Java 7. To enable us to still run on Java 6, new
|
||||
classes are injected. The implementation for these classes has been taken from
|
||||
Android's libcore (platform/libcore/luni/src/main/java/java/...).
|
||||
- Charsets, IntegralToString and UnsafeByteSequence are not part of the standard JAVA VM.
|
||||
They are added to the Dalvik VM for performance reasons. An implementation that is very
|
||||
close to the original (which is at platform/libcore/luni/src/main/java/...) is injected.
|
||||
Since these classees were in part of the java package, where we can't inject classes,
|
||||
all references to these have been updated (See strategy 4- Refactoring Classes).
|
||||
- OverrideMethod and its associated MethodListener and MethodAdapter are used to intercept calls to
|
||||
some specific methods that are stubbed out and change their return value.
|
||||
- CreateInfo class, which configured the generator. Not used yet, but could in theory help us track
|
||||
what the generator changed.
|
||||
- AutoCloseable and Objects are part of Java 7. To enable us to still run on Java 6, new classes are
|
||||
injected. The implementation for these classes has been taken from Android's libcore
|
||||
(platform/libcore/luni/src/main/java/java/...).
|
||||
- Charsets, IntegralToString and UnsafeByteSequence are not part of the standard JAVA VM. They are
|
||||
added to the Dalvik VM for performance reasons. An implementation that is very close to the
|
||||
original (which is at platform/libcore/luni/src/main/java/...) is injected. Since these classees
|
||||
were in part of the java package, where we can't inject classes, all references to these have been
|
||||
updated (See strategy 4- Refactoring Classes).
|
||||
|
||||
|
||||
2- Overriding methods
|
||||
|
||||
As explained earlier, the creator doesn't have any replacement code for
|
||||
methods to override. Instead it removes the original code and replaces it
|
||||
by a call to a specific OveriddeMethod.invokeX(). The bridge then registers
|
||||
a listener on the method signature and can provide an implementation.
|
||||
As explained earlier, the creator doesn't have any replacement code for methods to override. Instead
|
||||
it removes the original code and replaces it by a call to a specific OveriddeMethod.invokeX(). The
|
||||
bridge then registers a listener on the method signature and can provide an implementation.
|
||||
|
||||
This strategy is now obsolete and replaced by the method delegates.
|
||||
See strategy 5 below.
|
||||
This strategy is now obsolete and replaced by the method delegates (See strategy 6- Method
|
||||
Delegates).
|
||||
|
||||
|
||||
3- Renaming classes
|
||||
|
||||
This simply changes the name of a class in its definition, as well as all its
|
||||
references in internal inner classes and methods.
|
||||
Calls from other classes are not modified -- they keep referencing the original
|
||||
class name. This allows the bridge to literally replace an implementation.
|
||||
This simply changes the name of a class in its definition, as well as all its references in internal
|
||||
inner classes and methods. Calls from other classes are not modified -- they keep referencing the
|
||||
original class name. This allows the bridge to literally replace an implementation.
|
||||
|
||||
An example will make this easier: android.graphics.Paint is the main drawing
|
||||
class that we need to replace. To do so, the generator renames Paint to _original_Paint.
|
||||
Later the bridge provides its own replacement version of Paint which will be used
|
||||
by the rest of the Android stack. The replacement version of Paint can still use
|
||||
(either by inheritance or delegation) all the original non-native code of _original_Paint
|
||||
if it so desires.
|
||||
An example will make this easier: android.graphics.Paint is the main drawing class that we need to
|
||||
replace. To do so, the generator renames Paint to _original_Paint. Later the bridge provides its own
|
||||
replacement version of Paint which will be used by the rest of the Android stack. The replacement
|
||||
version of Paint can still use (either by inheritance or delegation) all the original non-native
|
||||
code of _original_Paint if it so desires.
|
||||
|
||||
Some of the Android classes are basically wrappers over native objects and since
|
||||
we don't have the native code in Eclipse, we need to provide a full alternate
|
||||
implementation. Sub-classing doesn't work as some native methods are static and
|
||||
we don't control object creation.
|
||||
Some of the Android classes are basically wrappers over native objects and since we don't have the
|
||||
native code in Eclipse, we need to provide a full alternate implementation. Sub-classing doesn't
|
||||
work as some native methods are static and we don't control object creation.
|
||||
|
||||
This won't rename/replace the inner static methods of a given class.
|
||||
|
||||
|
||||
4- Refactoring classes
|
||||
|
||||
This is very similar to the Renaming classes except that it also updates the reference in
|
||||
all classes. This is done for classes which are added to the Dalvik VM for performance
|
||||
reasons but are not present in the Standard Java VM. An implementation for these classes
|
||||
is also injected.
|
||||
This is very similar to the Renaming classes except that it also updates the reference in all
|
||||
classes. This is done for classes which are added to the Dalvik VM for performance reasons but are
|
||||
not present in the Standard Java VM. An implementation for these classes is also injected.
|
||||
|
||||
|
||||
5- Method erasure based on return type
|
||||
|
||||
This is mostly an implementation detail of the bridge: in the Paint class
|
||||
mentioned above, some inner static classes are used to pass around
|
||||
attributes (e.g. FontMetrics, or the Style enum) and all the original implementation
|
||||
is native.
|
||||
This is mostly an implementation detail of the bridge: in the Paint class mentioned above, some
|
||||
inner static classes are used to pass around attributes (e.g. FontMetrics, or the Style enum) and
|
||||
all the original implementation is native.
|
||||
|
||||
In this case we have a strategy that tells the generator that anything returning, for
|
||||
example, the inner class Paint$Style in the Paint class should be discarded and the
|
||||
bridge will provide its own implementation.
|
||||
In this case we have a strategy that tells the generator that anything returning, for example, the
|
||||
inner class Paint$Style in the Paint class should be discarded and the bridge will provide its own
|
||||
implementation.
|
||||
|
||||
|
||||
6- Method Delegates
|
||||
|
||||
This strategy is used to override method implementations.
|
||||
Given a method SomeClass.MethodName(), 1 or 2 methods are generated:
|
||||
a- A copy of the original method named SomeClass.MethodName_Original().
|
||||
The content is the original method as-is from the reader.
|
||||
This step is omitted if the method is native, since it has no Java implementation.
|
||||
b- A brand new implementation of SomeClass.MethodName() which calls to a
|
||||
non-existing static method named SomeClass_Delegate.MethodName().
|
||||
The implementation of this 'delegate' method is done in layoutlib_brigde.
|
||||
This strategy is used to override method implementations. Given a method SomeClass.MethodName(), 1
|
||||
or 2 methods are generated:
|
||||
a- A copy of the original method named SomeClass.MethodName_Original(). The content is the original
|
||||
method as-is from the reader. This step is omitted if the method is native, since it has no Java
|
||||
implementation.
|
||||
b- A brand new implementation of SomeClass.MethodName() which calls to a non-existing static method
|
||||
named SomeClass_Delegate.MethodName(). The implementation of this 'delegate' method is done in
|
||||
layoutlib_brigde.
|
||||
|
||||
The delegate method is a static method.
|
||||
If the original method is non-static, the delegate method receives the original 'this'
|
||||
as its first argument. If the original method is an inner non-static method, it also
|
||||
receives the inner 'this' as the second argument.
|
||||
The delegate method is a static method. If the original method is non-static, the delegate method
|
||||
receives the original 'this' as its first argument. If the original method is an inner non-static
|
||||
method, it also receives the inner 'this' as the second argument.
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user