README.md - cobalt - Git at Google

 # Cobalt

 ## Overview

 Cobalt is a lightweight application container (i.e. an application runtime, like
 a JVM or the Flash Player) that is compatible with a subset of the W3C HTML5
 specifications. If you author a single-page web application (SPA) that complies
 with the Cobalt Subset of W3C standards, it will run as well as possible on all
 the devices that Cobalt supports.


 ## Motivation

 The Cobalt Authors originally maintained a port of Chromium called H5VCC, the
 HTML5 Video Container for Consoles, ported to each of the major game consoles,
 designed to run our HTML5-based video browse and play application. This took a
 long time to port to each platform, consisted of 9 million lines of C++ code
 (before we touched it), was dangerous to modify without unintended consequences,
 and was thoroughly designed for a resource-rich, multi-process environment
 (e.g. a desktop, laptop, or modern smartphone).

 After wrestling with this for several years, we imagined an environment that was
 not designed for traditional scrolling web content, but was intended to be a
 runtime environment for rich client applications built with the same
 technologies -- HTML, CSS, JavaScript -- and designed from the ground-up to run
 on constrained, embedded, Living Room Consumer Electronics (CE) devices, such as
 Game Consoles, Set-Top Boxes (e.g. Cable, Satellite), OTT devices (e.g. Roku,
 Apple TV, Chromecast, Fire TV), Blu-ray Disc Players, and Smart TVs.

 These constraints (not intended to be a canonical list) make this device
 spectrum vastly different from the desktop computer environment targeted by
 Chromium, FireFox, and IE:

   * **Limited Memory.** All except the very latest, expensive CE devices have a
     very small amount of memory available for applications. This usually is
     somewhere in the ballpark of 200MB-500MB, including graphics and media
     memory, as opposed to multiple gigabytes of CPU memory (and more gigabytes
     of GPU memory) in modern desktop and laptop computers, and mobile devices.
   * **Slow CPUs.** Most CE devices have much slower CPUs than what is available
     on even a budget desktop computer. Minor performance concerns can be greatly
     exaggerated, which seriously affects priorities.
   * **Fewer cores.** CE System-on-a-Chip (SoC) processors often do not have as
     many processor cores as we are used to in modern computers.
   * **Minimal GPU.** Not all CE devices have a monster GPU to throw shaders at
     to offload CPU work. As CE devices now have a standard GPU (though not
     nearly as powerful as even a laptop), OpenGL ES 2.0 is now required
     by Cobalt.
   * **Sometimes No JIT.** Many CE devices are dealing with "High-Value Content,"
     and, as such, are very sensitive to security concerns. Ensuring that
     writable pages are not executable is a strong security protocol that can
     prevent a wide spectrum of attacks. But, as a side effect, this also means
     no ability to JIT.
   * **Heterogenous Development Environments.** This is slowly evening out, but
     all CE devices run on custom hardware, often with proprietary methods of
     building, packaging, deploying, and running programs. Almost all CE devices
     have ARM processors instead of the more familiar x86. Sometimes the
     toolchain doesn't support contemporary C++11/14 features. Sometimes the OS
     isn't POSIX, or it tries to be, but it is only partially implemented.
     Sometimes the program entry point is in another language or architecture
     that requires a "trampoline" over to native binary code.
   * **No navigation.** The point of a Single-Page Application is that you don't
     go through the HTTP page dance every time you switch screens. It's slow, and
     provides poor user feedback, not to mention a jarring transition. Instead,
     one loads data from an XMLHttpRequest (XHR), and then updates one's DOM to
     reflect the new data. AJAX! Web 2.0!!
   * **No scrolling.** Well, full-screen, 10-foot UI SPA apps might scroll, but
     not like traditional web pages, with scroll bars and a mouse
     wheel. Scrolling is generally built into the app very carefully, with
     support for a Directional Pad and a focus cursor.


 ## Architecture

 The Cobalt Authors forked H5VCC, removed most of the Chromium code -- in
 particular WebCore and the Chrome Renderer and Compositor -- and built up from
 scratch an implementation of a simplified subset of HTML, the CSS Box Model for
 layout, and the Web APIs that were really needed to build a full-screen SPA
 browse and play application.

 The Cobalt technology stack has these major components, roughly in a high-level
 application to a low-level platform order:

   * **Web Implementation** - This is where the W3C standards are implemented,
     ultimately producing an annotated DOM tree that can be passed into the
     Layout Engine to produce a Render Tree.
   * **JavaScript Engine** - We have, perhaps surprisingly, *not* written our own
     JavaScript Engine from scratch. Because of the JITing constraint, we have to
     be flexible with which engine(s) we work with. We have a bindings layer that
     interfaces with the JS Engine so that application script can interface with
     natively-backed objects (like DOM elements).
   * **Layout Engine** - The Layout Engine takes an annotated DOM Document
     produced by the Web Implementation and JavaScript Engine working together,
     and calculates a tree of rendering commands to send to the renderer (i.e. a
     Render Tree). It caches intermediate layout artifacts so that subsequent
     incremental layouts can be sped up.
   * **Renderer/Skia** - The Renderer walks a Render Tree produced by the Layout
     Engine, rasterizes it using the third-party graphics library Skia, and swaps
     it to the front buffer. This is accomplished using Hardware Skia on OpenGL
     ES 2.0. Note that the renderer runs in a different thread from the Layout
     Engine, and can interpolate animations that do not require re-layout. This
     decouples rendering from Layout and JavaScript, allowing for smooth,
     consistent animations on platforms with a variety of capabilities.
   * **Net / Media** - These are Chromium's Network and Media engines. We are
     using them directly, as they don't cause any particular problems with the
     extra constraints listed above.
   * **Base** - This is Chromium's "Base" library, which contains a wide variety
     of useful things used throughout Cobalt, Net, and Media. Cobalt uses a
     combination of standard C++ containers (e.g. vector, string) and Base as the
     foundation library for all of its code.
   * **Other Third-party Libraries** - Most of these are venerable, straight-C,
     open-source libraries that are commonly included in other open-source
     software. Mostly format decoders and parsers (e.g. libpng, libxml2,
     zlib). We fork these from Chromium, as we want them to be the most
     battle-tested versions of these libraries.
   * **Starboard/Glimp/ANGLE** - **Starboard** is the Cobalt porting
     interface. One major difference between Cobalt and Chromium is that we have
     created a hard straight-C porting layer, and ported ALL of the compiled
     code, including Base and all third-party libraries, to use it instead of
     directly using POSIX standard libraries, which are not consistent, even on
     modern systems (see Android, Windows, MacOS X, and iOS). Additionally,
     Starboard includes APIs that haven't been effectively standardized across
     platforms, such as display Window creation, Input events, and Media
     playback. **Glimp** is an OpenGL ES 2.0 implementation framework, built by
     the Cobalt team directly on Starboard, designed to adapt proprietary 3D APIs
     to GLES2. **ANGLE** Is a third-party library that adapts DirectX to GLES2,
     similar to Glimp, but only for DirectX.

 ## The Cobalt Subset

 > Oh, we got both kinds of HTML tags,\
 > we got `<span>` and `<div>`! \
 > We even have CSS Flexbox now, hooray!

 See the [Cobalt Subset
 specification](https://cobalt.dev/development/reference/supported-features.html)
 for more details on which tags, properties, and Web APIs are supported in
 Cobalt.

 ## Interesting Source Locations

 All source locations are specified relative to `src/` (this directory).

   * `base/` - Chromium's Base library. Contains common utilities, and a light
     platform abstraction, which has been superceded in Cobalt by Starboard.
   * `net/` - Chromium's Network library. Contains enough infrastructure to
     support the network needs of an HTTP User-Agent (like Chromium or Cobalt),
     an HTTP server, a DIAL server, and several abstractions for networking
     primitives. Also contains SPDY and QUIC implementations.
   * `cobalt/` - The home of all Cobalt application code. This includes the Web
     Implementation, Layout Engine, Renderer, and some other Cobalt-specific
     features.
       * `cobalt/build/` - The core build generation system, `gyp_cobalt`, and
         configurations for supported platforms. (NOTE: This should eventually be
         mostly moved into `starboard/`.)
       * `cobalt/doc/` - Contains a wide range of detailed information and guides
         on Cobalt features, functionality and best practices for Cobalt
         development.
       * `cobalt/media/` - Chromium's Media library. Contains all the code that
         parses, processes, and manages buffers of video and audio data. It
         send the buffers to the SbPlayer implementation for playback.
   * `starboard/` - Cobalt's porting layer. Please see Starboard's
     [`README.md`](starboard/README.md) for more detailed information about
     porting Starboard (and Cobalt) to a new platform.
   * `third_party/` - Where all of Cobalt's third-party dependencies live. We
     don't mean to be perjorative, we love our third-party libraries! This
     location is dictated by Google OSS release management rules...
       * `third_party/starboard/` - The location for third-party ports. This
         directory will be scanned automatically by gyp_cobalt for available
         Starboard ports.


 ## Building and Running the Code

   See the below reference port setup guides for more details:

   * [Linux](cobalt/site/docs/development/setup-linux.md)
   * [Raspi](cobalt/site/docs/development/setup-raspi.md)
   * [Android](cobalt/site/docs/development/setup-android.md)


 ## Build Types

 Cobalt has four build optimization levels, going from the slowest, least
 optimized, with the most debug information at the top (debug) to the fastest,
 most optimized, and with the least debug information at the bottom (gold):

  Type  | Optimizations | Logging | Asserts | Debug Info | Console
  :---- | :------------ | :------ | :------ | :--------- | :-------
  debug | None          | Full    | Full    | Full       | Enabled
  devel | Full          | Full    | Full    | Full       | Enabled
  qa    | Full          | Limited | None    | None       | Enabled
  gold  | Full          | None    | None    | None       | Disabled

 When building for release, you should always use a gold build for the final
 product.

 ## Origin of this Repository

 This is a fork of the chromium repository at http://git.chromium.org/git/chromium.git
	# Cobalt

	## Overview

	Cobalt is a lightweight application container (i.e. an application runtime, like
	a JVM or the Flash Player) that is compatible with a subset of the W3C HTML5
	specifications. If you author a single-page web application (SPA) that complies
	with the Cobalt Subset of W3C standards, it will run as well as possible on all
	the devices that Cobalt supports.


	## Motivation

	The Cobalt Authors originally maintained a port of Chromium called H5VCC, the
	HTML5 Video Container for Consoles, ported to each of the major game consoles,
	designed to run our HTML5-based video browse and play application. This took a
	long time to port to each platform, consisted of 9 million lines of C++ code
	(before we touched it), was dangerous to modify without unintended consequences,
	and was thoroughly designed for a resource-rich, multi-process environment
	(e.g. a desktop, laptop, or modern smartphone).

	After wrestling with this for several years, we imagined an environment that was
	not designed for traditional scrolling web content, but was intended to be a
	runtime environment for rich client applications built with the same
	technologies -- HTML, CSS, JavaScript -- and designed from the ground-up to run
	on constrained, embedded, Living Room Consumer Electronics (CE) devices, such as
	Game Consoles, Set-Top Boxes (e.g. Cable, Satellite), OTT devices (e.g. Roku,
	Apple TV, Chromecast, Fire TV), Blu-ray Disc Players, and Smart TVs.

	These constraints (not intended to be a canonical list) make this device
	spectrum vastly different from the desktop computer environment targeted by
	Chromium, FireFox, and IE:

	* Limited Memory. All except the very latest, expensive CE devices have a
	very small amount of memory available for applications. This usually is
	somewhere in the ballpark of 200MB-500MB, including graphics and media
	memory, as opposed to multiple gigabytes of CPU memory (and more gigabytes
	of GPU memory) in modern desktop and laptop computers, and mobile devices.
	* Slow CPUs. Most CE devices have much slower CPUs than what is available
	on even a budget desktop computer. Minor performance concerns can be greatly
	exaggerated, which seriously affects priorities.
	* Fewer cores. CE System-on-a-Chip (SoC) processors often do not have as
	many processor cores as we are used to in modern computers.
	* Minimal GPU. Not all CE devices have a monster GPU to throw shaders at
	to offload CPU work. As CE devices now have a standard GPU (though not
	nearly as powerful as even a laptop), OpenGL ES 2.0 is now required
	by Cobalt.
	* Sometimes No JIT. Many CE devices are dealing with "High-Value Content,"
	and, as such, are very sensitive to security concerns. Ensuring that
	writable pages are not executable is a strong security protocol that can
	prevent a wide spectrum of attacks. But, as a side effect, this also means
	no ability to JIT.
	* Heterogenous Development Environments. This is slowly evening out, but
	all CE devices run on custom hardware, often with proprietary methods of
	building, packaging, deploying, and running programs. Almost all CE devices
	have ARM processors instead of the more familiar x86. Sometimes the
	toolchain doesn't support contemporary C++11/14 features. Sometimes the OS
	isn't POSIX, or it tries to be, but it is only partially implemented.
	Sometimes the program entry point is in another language or architecture
	that requires a "trampoline" over to native binary code.
	* No navigation. The point of a Single-Page Application is that you don't
	go through the HTTP page dance every time you switch screens. It's slow, and
	provides poor user feedback, not to mention a jarring transition. Instead,
	one loads data from an XMLHttpRequest (XHR), and then updates one's DOM to
	reflect the new data. AJAX! Web 2.0!!
	* No scrolling. Well, full-screen, 10-foot UI SPA apps might scroll, but
	not like traditional web pages, with scroll bars and a mouse
	wheel. Scrolling is generally built into the app very carefully, with
	support for a Directional Pad and a focus cursor.


	## Architecture

	The Cobalt Authors forked H5VCC, removed most of the Chromium code -- in
	particular WebCore and the Chrome Renderer and Compositor -- and built up from
	scratch an implementation of a simplified subset of HTML, the CSS Box Model for
	layout, and the Web APIs that were really needed to build a full-screen SPA
	browse and play application.

	The Cobalt technology stack has these major components, roughly in a high-level
	application to a low-level platform order:

	* Web Implementation - This is where the W3C standards are implemented,
	ultimately producing an annotated DOM tree that can be passed into the
	Layout Engine to produce a Render Tree.
	* JavaScript Engine - We have, perhaps surprisingly, not written our own
	JavaScript Engine from scratch. Because of the JITing constraint, we have to
	be flexible with which engine(s) we work with. We have a bindings layer that
	interfaces with the JS Engine so that application script can interface with
	natively-backed objects (like DOM elements).
	* Layout Engine - The Layout Engine takes an annotated DOM Document
	produced by the Web Implementation and JavaScript Engine working together,
	and calculates a tree of rendering commands to send to the renderer (i.e. a
	Render Tree). It caches intermediate layout artifacts so that subsequent
	incremental layouts can be sped up.
	* Renderer/Skia - The Renderer walks a Render Tree produced by the Layout
	Engine, rasterizes it using the third-party graphics library Skia, and swaps
	it to the front buffer. This is accomplished using Hardware Skia on OpenGL
	ES 2.0. Note that the renderer runs in a different thread from the Layout
	Engine, and can interpolate animations that do not require re-layout. This
	decouples rendering from Layout and JavaScript, allowing for smooth,
	consistent animations on platforms with a variety of capabilities.
	* Net / Media - These are Chromium's Network and Media engines. We are
	using them directly, as they don't cause any particular problems with the
	extra constraints listed above.
	* Base - This is Chromium's "Base" library, which contains a wide variety
	of useful things used throughout Cobalt, Net, and Media. Cobalt uses a
	combination of standard C++ containers (e.g. vector, string) and Base as the
	foundation library for all of its code.
	* Other Third-party Libraries - Most of these are venerable, straight-C,
	open-source libraries that are commonly included in other open-source
	software. Mostly format decoders and parsers (e.g. libpng, libxml2,
	zlib). We fork these from Chromium, as we want them to be the most
	battle-tested versions of these libraries.
	* Starboard/Glimp/ANGLE - Starboard is the Cobalt porting
	interface. One major difference between Cobalt and Chromium is that we have
	created a hard straight-C porting layer, and ported ALL of the compiled
	code, including Base and all third-party libraries, to use it instead of
	directly using POSIX standard libraries, which are not consistent, even on
	modern systems (see Android, Windows, MacOS X, and iOS). Additionally,
	Starboard includes APIs that haven't been effectively standardized across
	platforms, such as display Window creation, Input events, and Media
	playback. Glimp is an OpenGL ES 2.0 implementation framework, built by
	the Cobalt team directly on Starboard, designed to adapt proprietary 3D APIs
	to GLES2. ANGLE Is a third-party library that adapts DirectX to GLES2,
	similar to Glimp, but only for DirectX.

	## The Cobalt Subset

	> Oh, we got both kinds of HTML tags,\
	> we got `<span>` and `<div>`! \
	> We even have CSS Flexbox now, hooray!

	See the [Cobalt Subset
	specification](https://cobalt.dev/development/reference/supported-features.html)
	for more details on which tags, properties, and Web APIs are supported in
	Cobalt.

	## Interesting Source Locations

	All source locations are specified relative to `src/` (this directory).

	* `base/` - Chromium's Base library. Contains common utilities, and a light
	platform abstraction, which has been superceded in Cobalt by Starboard.
	* `net/` - Chromium's Network library. Contains enough infrastructure to
	support the network needs of an HTTP User-Agent (like Chromium or Cobalt),
	an HTTP server, a DIAL server, and several abstractions for networking
	primitives. Also contains SPDY and QUIC implementations.
	* `cobalt/` - The home of all Cobalt application code. This includes the Web
	Implementation, Layout Engine, Renderer, and some other Cobalt-specific
	features.
	* `cobalt/build/` - The core build generation system, `gyp_cobalt`, and
	configurations for supported platforms. (NOTE: This should eventually be
	mostly moved into `starboard/`.)
	* `cobalt/doc/` - Contains a wide range of detailed information and guides
	on Cobalt features, functionality and best practices for Cobalt
	development.
	* `cobalt/media/` - Chromium's Media library. Contains all the code that
	parses, processes, and manages buffers of video and audio data. It
	send the buffers to the SbPlayer implementation for playback.
	* `starboard/` - Cobalt's porting layer. Please see Starboard's
	[`README.md`](starboard/README.md) for more detailed information about
	porting Starboard (and Cobalt) to a new platform.
	* `third_party/` - Where all of Cobalt's third-party dependencies live. We
	don't mean to be perjorative, we love our third-party libraries! This
	location is dictated by Google OSS release management rules...
	* `third_party/starboard/` - The location for third-party ports. This
	directory will be scanned automatically by gyp_cobalt for available
	Starboard ports.


	## Building and Running the Code

	See the below reference port setup guides for more details:

	* [Linux](cobalt/site/docs/development/setup-linux.md)
	* [Raspi](cobalt/site/docs/development/setup-raspi.md)
	* [Android](cobalt/site/docs/development/setup-android.md)


	## Build Types

	Cobalt has four build optimization levels, going from the slowest, least
	optimized, with the most debug information at the top (debug) to the fastest,
	most optimized, and with the least debug information at the bottom (gold):

	Type \| Optimizations \| Logging \| Asserts \| Debug Info \| Console
	:---- \| :------------ \| :------ \| :------ \| :--------- \| :-------
	debug \| None \| Full \| Full \| Full \| Enabled
	devel \| Full \| Full \| Full \| Full \| Enabled
	qa \| Full \| Limited \| None \| None \| Enabled
	gold \| Full \| None \| None \| None \| Disabled

	When building for release, you should always use a gold build for the final
	product.

	## Origin of this Repository

	This is a fork of the chromium repository at http://git.chromium.org/git/chromium.git