Skip to content

Latest commit

 

History

History
178 lines (141 loc) · 10.1 KB

code.md

File metadata and controls

178 lines (141 loc) · 10.1 KB

The architecture of Browser/ChromeOS code

Overview

We want to have clean code, good architecture, and clear ownership to ensure everybody can efficiently deliver high quality products. Toward this goal, this document discusses how code in the Chromium git repository is and should be architected between the browser and ChromeOS code.

Background

Originally, ChromeOS was just the Linux Chrome browser with a few extra additions for UI system management. As such, and to keep the system requirements very low, the entire ChromeOS UI was built into the Chrome “browser” process. Over time, ChromeOS has gotten substantially more sophisticated and capable. Many important services run in separate processes, services, or VMs, but most of the UI still runs in the main browser process.

The Lacros project aims to separate the Linux processes and the software releases between the browser and the OS shell. But Lacros does not by itself move any code: Lacros only converts what would otherwise be abstract C++ interfaces and internal APIs to IPC calls. This document deals with the code layout and abstractions which is independent from Lacros.

Definitions

  • Browser: General term referring to a process with web browsing capabilities.

  • Ash: The ChromeOS system UI. In this document, this term is used broadly to include most of the non-browser UI features including the app launcher, the system tray and notifications, the window manager, the system compositor, and the login UI.

  • Lacros: The ChromeOS-specific browser that does not include Ash. This is similar to the Linux browser but with ChromeOS-specific features and integrations.

  • Ash Browser: The “classic” (non-Lacros) ChromeOS software that includes Ash and the browser in one process.

  • Browser code: Code required to build a browser. This includes platform-specific integrations with the host OS rather than just the cross-platform parts. For ChromeOS, this includes many important ChromeOS browser features but does not include anything considered “Ash.”

  • OS code: Any ChromeOS-specific code that isn’t “browser code.” This is mostly Ash when referring to code in the Chromium repository.

  • Shared code: Code used in both browser and OS code including //base, //mojo, //ui, and some components.

Desired state

This section describes the long-term architectural goal rather than the current state or the current requirements. See below for what to do for current work.

The desired end-state is that “browser code” (including ChromeOS-specific browser features) and “OS code” have a clear separation. Communication between these layers should be done using well-defined APIs. Function calls in the code happen “down” the stack from the browser to the OS, and any calls “up” from the OS to the browser happen via events, observers, and callbacks configured by the browser layers.

Shared code like //views may have ChromeOS-specific parts and take contributions from anyone, but the Browser and OS teams should agree that the code is appropriate for such sharing.

In this desired state:

  • The //chrome directory is for the implementation of the Chrome browser, including Lacros. It should not have any OS code in it (for example, //chrome/browser/ash is undesirable) and OS code should not call directly into //chrome code outside of the above-mentioned callbacks.

  • The //content directory is the API for building a web browser. Even though Ash does use web technology for rendering many things, it is not itself a web browser and there should be no OS code in this directory or calling directly into it.

  • Browser code should only call into OS code through well-defined APIs (“crosapi”). In addition to addressing the practical cross-process requirements of Lacros, this provides a conceptual separation between browser and OS concerns.

Not all parts of the product fit neatly into the browser and OS layers, with extensions and apps being big examples. How web page embedding should be done from Ash is an area of active design and there is not currently good guidance for this. In these less well-defined areas, work toward as clear a separation as practical given the current state and the long-term requirements of that component.

Current policies

New features should be designed to adhere to the “desired state” as closely as practical. However, it is currently not possible to implement all functionality in Ash according to that state:

  • Some functionality (e.g., the Profile class) is only available in //chrome, and there is no clear alternative to use.

  • Legacy code still has significant //chrome dependencies and has not been migrated away from this state.

Thus, we must be pragmatic about implementing Ash features in the meantime, using the following guidance:

  • Any new Ash functionality should add its core functionality outside of //chrome.

    • In this context, "core" functionality includes the primary business logic of a feature.
    • Guidance on where this code should exist:
      • Ash-only code which is not system UI: //chromeos/ash/components
      • Ash-only system UI code: //ash
      • Lacros-only code: Match other platform code for that component (contact chrome-cros@google.com if you are unsure)
      • Shared by both Ash and Lacros:
        • UI code: //chromeos/ui
        • Non-UI code: //chromeos/components
      • Shared between ChromeOS (i.e., ash-chrome and lacros-chrome) and other platforms: //components

  • For code which must depend on //chrome, push logic down lower in the dependency graph as much as possible, and only implement a thin wrapper in //chrome. With this pattern, the code in //chrome is mostly "glue" or initialization code, which will minimize the effort required in the future to break these dependencies completely.

    • Example 1: Phone Hub's BrowserTabsModelProvider is declared in //chromeos/ash/components alongside related code logic, but BrowserTabsModelProviderImpl (in //chrome) implements the interface using a //chrome dependency.
    • Example 2: Phone Hub's PhoneHubManagerImpl is declared in //chromeos/ash/components and has dependencies outside of //chrome, but the concrete implementations of some of these components are KeyedServices requiring //chrome. In this case, PhoneHubManagerFactory instantiates PhoneHubManagerImpl in //chrome (serving as a thin wrapper around the dependencies), but the vast majority of logic is lower in the dependency graph.

  • A few common //chrome dependencies that may be able to be broken easily:

  • For any new code added in //chrome/browser/ash, a DEPS file must be created which explicitly declares //chrome dependencies. People residing in //chrome/OWNERS can help suggest alternatives to these dependencies if possible when reviewing the code which adds this new DEPS file. See b/332805865 for more details.

  • Note: Any features related specifically to the Ash browser (in Lacros-disabled mode) should stay in //chrome since this code will be deleted after Lacros is launched. For example, BrowserViewAsh implements UI specific to the ash-chrome browser, and we should not attempt to push this lower in the dependency graph.

If you need advice to help you make a decision regarding your design, please reach out to ash-chrome-refactor@google.com for feedback.

Path forward

The current policy aims to stop accumulating more undesirable OS/browser dependencies while acknowledging there is a large amount of legacy code that does not follow the guidelines. The team is moving toward the desired state using a 2-pronged approach:

  1. Eliminating OS ⇔ Browser calls: the Lacros project has been creating a clear OS API (“crosapi”) to communicate between the Lacros browser and Ash.

  2. Removing Ash code from //chrome: The go/ash-chrome-refactor project seeks to refactor Ash code in //chrome and decouple it from browser code as much as possible. This project, which will introduce a C++ based glue layer, has a long time horizon. Although its long-term goals are clear, the project is only on its early milestones at this stage.