diff options
9 files changed, 141 insertions, 33 deletions
diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/README.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/README.md index 73a7348d5aca..3fad28ad232f 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/README.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/README.md @@ -15,4 +15,4 @@ particular order): Todo - Per-feature docs - Feature flagging -- Best practices
\ No newline at end of file +- Best practices & patterns
\ No newline at end of file diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/changes.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/changes.md index fbf326eadcd5..9aa5f4ffcd78 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/changes.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/changes.md @@ -102,5 +102,5 @@ AIDL interfaces and constants. Currently, all AIDL files, and classes under the Launcher uses. If the new code doesn't fall into those categories, they can be added explicitly in the Shell's -[Android.bp](frameworks/base/libs/WindowManager/Shell/Android.bp) file under the +[Android.bp](/libs/WindowManager/Shell/Android.bp) file under the `wm_shell_util-sources` filegroup.
\ No newline at end of file diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md index 6c01d962adc9..7070dead9957 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/dagger.md @@ -21,16 +21,16 @@ developers to jump into a few select files and understand how different componen (especially as products override components). The module dependency tree looks a bit like: -- [WMShellConcurrencyModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellConcurrencyModule.java) +- [WMShellConcurrencyModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellConcurrencyModule.java) (provides threading-related components) - - [WMShellBaseModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellBaseModule.java) + - [WMShellBaseModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellBaseModule.java) (provides components that are likely common to all products, ie. DisplayController, Transactions, etc.) - - [WMShellModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellModule.java) + - [WMShellModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellModule.java) (phone/tablet specific components only) - - [TvPipModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvPipModule.java) + - [TvPipModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvPipModule.java) (PIP specific components for TV) - - [TvWMShellModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvWMShellModule.java) + - [TvWMShellModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/TvWMShellModule.java) (TV specific components only) - etc. @@ -43,7 +43,7 @@ In some rare cases, there are base components that can change behavior depending product it runs on. If there are hooks that can be added to the component, that is the preferable approach. -The alternative is to use the [@DynamicOverride](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/DynamicOverride.java) +The alternative is to use the [@DynamicOverride](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/DynamicOverride.java) annotation to allow the product module to provide an implementation that the base module can reference. This is most useful if the existence of the entire component is controlled by the product and the override implementation is optional (there is a default implementation). More diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/debugging.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/debugging.md index f9ea1d4e2a07..438aa768165e 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/debugging.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/debugging.md @@ -29,30 +29,78 @@ building to check the log state (is enabled) before printing the print format st ### Kotlin Protolog tool does not yet have support for Kotlin code (see [b/168581922](https://b.corp.google.com/issues/168581922)). -For logging in Kotlin, use the [KtProtoLog](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/util/KtProtoLog.kt) +For logging in Kotlin, use the [KtProtoLog](/libs/WindowManager/Shell/src/com/android/wm/shell/util/KtProtoLog.kt) class which has a similar API to the Java ProtoLog class. ### Enabling ProtoLog command line logging -Run these commands to enable protologs for both WM Core and WM Shell to print to logcat. +Run these commands to enable protologs (in logcat) for WM Core ([list of all core tags](/core/java/com/android/internal/protolog/ProtoLogGroup.java)): ```shell -adb shell wm logging enable-text NEW_FEATURE -adb shell wm logging disable-text NEW_FEATURE +adb shell wm logging enable-text TAG +adb shell wm logging disable-text TAG +``` + +And these commands to enable protologs (in logcat) for WM Shell ([list of all shell tags](/libs/WindowManager/Shell/src/com/android/wm/shell/protolog/ShellProtoLogGroup.java)): +```shell +adb shell dumpsys activity service SystemUIService WMShell protolog enable-text TAG +adb shell dumpsys activity service SystemUIService WMShell protolog enable-text TAG ``` ## Winscope Tracing The Winscope tool is extremely useful in determining what is happening on-screen in both WindowManager and SurfaceFlinger. Follow [go/winscope](http://go/winscope-help) to learn how to -use the tool. +use the tool. This trace will contain all the information about the windows/activities/surfaces on +screen. + +## WindowManager/SurfaceFlinger hierarchy dump + +A quick way to view the WindowManager hierarchy without a winscope trace is via the wm dumps: +```shell +adb shell dumpsys activity containers +``` + +Likewise, the SurfaceFlinger hierarchy can be dumped for inspection by running: +```shell +adb shell dumpsys SurfaceFlinger +# Search output for "Layer Hierarchy" +``` + +## Tracing global SurfaceControl transaction updates -In addition, there is limited preliminary support for Winscope tracing componetns in the Shell, -which involves adding trace fields to [wm_shell_trace.proto](frameworks/base/libs/WindowManager/Shell/proto/wm_shell_trace.proto) -file and ensure it is updated as a part of `WMShell#writeToProto`. +While Winscope traces are very useful, it sometimes doesn't give you enough information about which +part of the code is initiating the transaction updates. In such cases, it can be helpful to get +stack traces when specific surface transaction calls are made, which is possible by enabling the +following system properties for example: +```shell +# Enabling +adb shell setprop persist.wm.debug.sc.tx.log_match_call setAlpha # matches the name of the SurfaceControlTransaction method +adb shell setprop persist.wm.debug.sc.tx.log_match_name com.android.systemui # matches the name of the surface +adb reboot +adb logcat -s "SurfaceControlRegistry" + +# Disabling logging +adb shell setprop persist.wm.debug.sc.tx.log_match_call \"\" +adb shell setprop persist.wm.debug.sc.tx.log_match_name \"\" +adb reboot +``` + +It is not necessary to set both `log_match_call` and `log_match_name`, but note logs can be quite +noisy if unfiltered. -Tracing can be started via the shell command (to be added to the Winscope tool as needed): +## Tracing activity starts in the app process + +It's sometimes useful to know when to see a stack trace of when an activity starts in the app code +(ie. if you are repro'ing a bug related to activity starts). You can enable this system property to +get this trace: ```shell -adb shell cmd statusbar tracing start -adb shell cmd statusbar tracing stop +# Enabling +adb shell setprop persist.wm.debug.start_activity true +adb reboot +adb logcat -s "Instrumentation" + +# Disabling +adb shell setprop persist.wm.debug.start_activity \"\" +adb reboot ``` ## Dumps @@ -69,6 +117,21 @@ If information should be added to the dump, either: - Update `WMShell` if you are dumping SysUI state - Inject `ShellCommandHandler` into your Shell class, and add a dump callback +## Shell commands + +It can be useful to add additional shell commands to drive and test specific interactions. + +To add a new command for your feature, inject a `ShellCommandHandler` into your class and add a +shell command handler in your controller. + +```shell +# List all available commands +adb shell dumpsys activity service SystemUIService WMShell help + +# Run a specific command +adb shell dumpsys activity service SystemUIService WMShell <cmd> <args> ... +``` + ## Debugging in Android Studio If you are using the [go/sysui-studio](http://go/sysui-studio) project, then you can debug Shell diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/overview.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/overview.md index a88ef6aea2ec..b489fe8ea1a9 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/overview.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/overview.md @@ -19,25 +19,24 @@ Currently, the WMShell library is used to drive the windowing experience on hand ## Where does the code live -The core WMShell library code is currently located in the [frameworks/base/libs/WindowManager/Shell](frameworks/base/libs/WindowManager/Shell) +The core WMShell library code is currently located in the [frameworks/base/libs/WindowManager/Shell](/libs/WindowManager/Shell) directory and is included as a part dependency of the host SystemUI apk. ## How do I build the Shell library -The library can be built directly by running (using [go/makepush](http://go/makepush)): +The library can be built directly by running: ```shell -mp :WindowManager-Shell +m WindowManager-Shell ``` But this is mainly useful for inspecting the contents of the library or verifying it builds. The -various targets can be found in the Shell library's [Android.bp](frameworks/base/libs/WindowManager/Shell/Android.bp) +various targets can be found in the Shell library's [Android.bp](/libs/WindowManager/Shell/Android.bp) file. Normally, you would build it as a part of the host SystemUI, for example via commandline: ```shell # Phone SystemUI variant -mp sysuig -# Building Shell & SysUI changes along w/ framework changes -mp core services sysuig +m SystemUI +adevice update ``` Or preferably, if you are making WMShell/SysUI only changes (no other framework changes), then diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/patterns/TEMPLATE.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/patterns/TEMPLATE.md new file mode 100644 index 000000000000..0e20a8ec275c --- /dev/null +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/patterns/TEMPLATE.md @@ -0,0 +1,30 @@ +# Pattern (one line description) + +### What this pattern solves + +Give detailed information about the problem that this pattern addresses, include when it +should/should not be used. + +### How it works + +Give a high level overview of how this pattern works technically with sufficient links for the +relevant dependencies for folks to read more. + +### Code examples + +Explain how this pattern is used in code. + +File.kt: +```kotlin +fun someFunction() { + // Use this code +} +``` + +### Relevant links + +Add relevant links to other files that implement this pattern, design docs, or other important +info. + +Link 1: [More info](some_example_link) \ +Link 2: [More info](some_example_link)
\ No newline at end of file diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/sysui.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/sysui.md index d6302e640ba7..30ff6691f503 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/sysui.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/sysui.md @@ -80,4 +80,6 @@ adb shell dumpsys activity service SystemUIService WMShell # Run a specific command adb shell dumpsys activity service SystemUIService WMShell help adb shell dumpsys activity service SystemUIService WMShell <cmd> <args> ... -```
\ No newline at end of file +``` + +More detail can be found in [Debugging in the Shell](debugging.md) section.
\ No newline at end of file diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/testing.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/testing.md index 8a80333facc4..98af930c4486 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/testing.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/testing.md @@ -5,7 +5,7 @@ ## Unit tests New WM Shell unit tests can be added to the -[Shell/tests/unittest](frameworks/base/libs/WindowManager/Shell/tests/unittest) directory, and can +[Shell/tests/unittest](/libs/WindowManager/Shell/tests/unittest) directory, and can be run via command line using `atest`: ```shell atest WMShellUnitTests @@ -25,10 +25,24 @@ Flicker tests are tests that perform actions and make assertions on the state in and SurfaceFlinger traces captured during the run. New WM Shell Flicker tests can be added to the -[Shell/tests/flicker](frameworks/base/libs/WindowManager/Shell/tests/flicker) directory, and can -be run via command line using `atest`: +[Shell/tests/flicker](/libs/WindowManager/Shell/tests/flicker) directory, and can be run via command line using `atest`: ```shell -atest WMShellFlickerTests +# Bubbles +atest WMShellFlickerTestsBubbles + +# PIP +atest WMShellFlickerTestsPip1 +atest WMShellFlickerTestsPip2 +atest WMShellFlickerTestsPip3 +atest WMShellFlickerTestsPipApps +atest WMShellFlickerTestsPipAppsCSuite + +# Splitscreen +atest WMShellFlickerTestsSplitScreenGroup1 +atest WMShellFlickerTestsSplitScreenGroup2 + +# Other +atest WMShellFlickerTestsOther ``` **Note**: Currently Flicker tests can only be run from the commandline and not via SysUI Studio diff --git a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/threading.md b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/threading.md index eac748894432..9d015357b60b 100644 --- a/libs/WindowManager/Shell/src/com/android/wm/shell/docs/threading.md +++ b/libs/WindowManager/Shell/src/com/android/wm/shell/docs/threading.md @@ -43,7 +43,7 @@ the product. ## Dagger setup -The threading-related components are provided by the [WMShellConcurrencyModule](frameworks/base/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellConcurrencyModule.java), +The threading-related components are provided by the [WMShellConcurrencyModule](/libs/WindowManager/Shell/src/com/android/wm/shell/dagger/WMShellConcurrencyModule.java), for example, the Executors and Handlers for the various threads that are used. You can request an executor of the necessary type by using the appropriate annotation for each of the threads (ie. `@ShellMainThread Executor`) when injecting into your Shell component. @@ -76,7 +76,7 @@ To get the SysUI main thread, you can use the `@Main` annotation. want to dedupe multiple messages - In such cases inject `@ShellMainThread Handler` or use view.getHandler() which should be OK assuming that the view root was initialized on the main Shell thread -- **Never use Looper.getMainLooper()** +- <u>**Never</u> use Looper.getMainLooper()** - It's likely going to be wrong, you can inject `@Main ShellExecutor` to get the SysUI main thread ### Testing |