tree: b38b0984f631f47e48bb3c39afceddfb89bfe5d5 [path history] [tgz]
  1. accelerators/
  2. accessibility/
  3. animation/
  4. app_list/
  5. app_menu/
  6. ash_strings_grd/
  7. assistant/
  8. autoclick/
  9. components/
  10. contained_shell/
  11. content/
  12. dbus/
  13. detachable_base/
  14. display/
  15. drag_drop/
  16. events/
  17. first_run/
  18. frame/
  19. high_contrast/
  20. highlighter/
  21. host/
  22. ime/
  23. keyboard/
  24. laser/
  25. lock_screen_action/
  26. login/
  27. magnifier/
  28. media/
  29. metrics/
  30. multi_device_setup/
  31. multi_user/
  32. perftests/
  33. policy/
  34. public/
  35. resources/
  36. rotator/
  37. session/
  38. shelf/
  39. shell/
  40. sticky_keys/
  41. strings/
  42. system/
  43. test/
  44. tooltips/
  45. touch/
  46. tray_action/
  47. utility/
  48. voice_interaction/
  49. wallpaper/
  50. wayland/
  51. wm/
  52. ws/
  53. app_launch_unittest.cc
  54. ash_export.h
  55. ash_service.cc
  56. ash_service.h
  57. ash_service_unittest.cc
  58. ash_strings.grd
  59. ash_unittests_manifest.json
  60. bluetooth_devices_observer.cc
  61. bluetooth_devices_observer.h
  62. BUILD.gn
  63. cancel_mode.cc
  64. cancel_mode.h
  65. cast_config_controller.cc
  66. cast_config_controller.h
  67. cursor_unittest.cc
  68. debug.cc
  69. debug.h
  70. DEPS
  71. dip_unittest.cc
  72. disconnected_app_handler.cc
  73. disconnected_app_handler.h
  74. extended_desktop_unittest.cc
  75. focus_cycler.cc
  76. focus_cycler.h
  77. focus_cycler_unittest.cc
  78. login_status.h
  79. main.cc
  80. manifest.json
  81. media_controller.cc
  82. media_controller.h
  83. mojo_interface_factory.cc
  84. mojo_interface_factory.h
  85. mojo_test_interface_factory.cc
  86. mojo_test_interface_factory.h
  87. multi_profile_uma.cc
  88. multi_profile_uma.h
  89. mus_property_mirror_ash_unittest.cc
  90. network_connect_delegate_mus.cc
  91. network_connect_delegate_mus.h
  92. new_window_controller.cc
  93. new_window_controller.h
  94. note_taking_controller.cc
  95. note_taking_controller.h
  96. OWNERS
  97. PRESUBMIT.py
  98. README.md
  99. root_window_controller.cc
  100. root_window_controller.h
  101. root_window_controller_unittest.cc
  102. root_window_settings.cc
  103. root_window_settings.h
  104. scoped_animation_disabler.cc
  105. scoped_animation_disabler.h
  106. scoped_root_window_for_new_windows.cc
  107. scoped_root_window_for_new_windows.h
  108. screen_util.cc
  109. screen_util.h
  110. screen_util_unittest.cc
  111. screenshot_delegate.h
  112. shell.cc
  113. shell.h
  114. shell_delegate.h
  115. shell_delegate_mash.cc
  116. shell_delegate_mash.h
  117. shell_init_params.cc
  118. shell_init_params.h
  119. shell_observer.h
  120. shell_state.cc
  121. shell_state.h
  122. shell_state_unittest.cc
  123. shell_test_api.cc
  124. shell_test_api.h
  125. shell_unittest.cc
  126. shutdown_controller.cc
  127. shutdown_controller.h
  128. shutdown_reason.cc
  129. shutdown_reason.h
  130. test_media_client.cc
  131. test_media_client.h
  132. test_screenshot_delegate.cc
  133. test_screenshot_delegate.h
  134. test_shell_delegate.cc
  135. test_shell_delegate.h
  136. window_factory.cc
  137. window_factory.h
  138. window_user_data.h
  139. window_user_data_unittest.cc
ash/README.md

Ash

Ash is the “Aura Shell”, the window manager and system UI for Chrome OS. Ash uses the views UI toolkit (e.g. views::View, views::Widget, etc.) backed by the aura native widget and layer implementations.

Ash sits below chrome in the dependency graph (i.e. it cannot depend on code in //chrome). It has a few dependencies on //content, but these are isolated in their own module in //ash/content. This allows targets like ash_unittests to build more quickly.

Tests

Most tests should be added to the ash_unittests target. Tests that rely on //content should be added to ash_content_unittests, but these should be rare.

Tests can bring up most of the ash UI and simulate a login session by deriving from AshTestBase. This is often needed to test code that depends on ash::Shell and the controllers it owns.

Test support code (TestFooDelegate, FooControllerTestApi, etc.) lives in the same directory as the class under test (e.g. //ash/foo rather than //ash/test). Test code uses namespace ash; there is no special “test” namespace.

Mash

Ash is transitioning to run as a mojo service in its own process. This change means that code in chrome cannot call into ash directly, but must use the mojo interfaces in //ash/public/interfaces.

Out-of-process Ash is referred to as “mash” (mojo ash). In-process ash is referred to as “classic ash”. Ash can run in either mode depending on the --enable-features=Mash command line flag.

In the few cases where chrome code is allowed to call into ash (e.g. code that will only ever run in classic ash) the #include lines have “// mash-ok” appended. This makes it easier to use grep to determine which parts of chrome have not yet been adapted to mash.

Ash used to support a “mus” mode that ran the mojo window service from //services/ui on a background thread in the browser process. This configuration was deprecated in April 2018.

SingleProcessMash

Before launching Mash we plan to launch SingleProcessMash. SingleProcessMash is similar to “classic ash” in that ash and the browser still live in the same process and on the same thread, but all non-ash UI code (such as browser windows) will use the WindowService over mojo. This results in exercising much of the same code as in mash, but everything is still in the process.

In SingleProcessMash mode there are two aura::Envs. Ash (Shell) creates one and the browser creates one. In order to ensure the right one is used do the following:

. When creating a Widget set the parent and/or context. If you don't need a specific parent (container), more often than not using a context of Shell::GetRootWindowForNewWindows() is what you want. . If you are creating aura::Windows directly, use the ash::window_factory. . If you need access to aura::Env, get it from Shell. Shell always returns the right one, regardless of mode.

See https://docs.google.com/document/d/11ha_KioDdXe4iZS2AML1foKnCJlNKm7Q1hFr6VW8dV4/edit for more details.

Mash Tests

ash_unittests has some tests specific to Mash, but in general Ash code should not need to do anything special for Mash. AshTestBase offers functions that simulate a remote client (such as the browser) creating a window.

To enable browser_tests to run in Mash use “--enable-features=Mash”. As Mash is still a work in progress not all tests pass. A filter file is used on the bots to exclude failing tests (testing/buildbot/filters/mash.browser_tests.filter).

To simulate what the bots run (e.g. to check if you broke an existing test that works under mash) you can run:

browser_tests --enable-features=Mash --test-launcher-filter-file=testing/buildbot/filters/mash.browser_tests.filter

Any new feature you add (and its tests) should work under mash. If your test cannot pass under mash due to some dependency being broken you may add the test to the filter file. Make sure there is a bug for the underlying issue and cite it in the filter file.

Prefs

Ash supports both per-user prefs and device-wide prefs. These are called “profile prefs” and “local state” to match the naming conventions in chrome. Ash also supports “signin screen” prefs, bound to a special profile that allows users to toggle features like spoken feedback at the login screen.

Local state prefs are loaded asynchronously during startup. User prefs are loaded asynchronously after login, and after adding a multiprofile user. Code that wants to observe prefs must wait until they are loaded. See ShellObserver::OnLocalStatePrefServiceInitialized() and SessionObserver::OnActiveUserPrefServiceChanged(). All PrefService objects exist for the lifetime of the login session, including the signin prefs.

Pref names are in //ash/public/cpp so that code in chrome can also use the names. Prefs are registered in the classes that use them because those classes have the best knowledge of default values.

All PrefService instances in ash are backed by the mojo preferences service. This means an update to a pref is asynchronous between code in ash and code in chrome. For example, if code in chrome changes a pref value then immediately calls a C++ function in ash, that ash function may not see the new value yet. (This pattern only happens in the classic ash configuration; code in chrome cannot call directly into the ash process in the mash config.)

Prefs are either “owned” by ash or by chrome browser. New prefs used by ash should be owned by ash. See NightLightController and LogoutButtonTray for examples of ash-owned prefs. See //services/preferences/README.md for details of pref ownership and “foreign” prefs.

Historical notes

Ash shipped on Windows for a couple years to support Windows 8 Metro mode. Windows support was removed in 2016.