# Technical Documentation: BrowserWorks/waterfox > ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/BrowserWorks/waterfox) ### Overview (README.md) # Waterfox Waterfox is a customisable browser based on Mozilla Firefox. This repository contains Mozilla platform code, Waterfox product code, branding, features, packaging, and release files. ## Building Waterfox uses the Mozilla build system. The usual `./mach` entry points apply: ```sh ./mach bootstrap ./mach build ./mach package ./mach test --auto ``` ## Contributing Most Firefox development documentation still applies to this tree. Use the Firefox Source Docs for the shared Mozilla build system, testing tools, and platform code. ## Resources - [Waterfox website](https://www.waterfox.net/) - [Firefox Source Docs](https://firefox-source-docs.mozilla.org/) --- ### Metrics Index (`docs/metrics/index.md`) # Metrics The metrics collected by Firefox using the [Glean SDK](https://mozilla.github.io/glean/book/index.html) are documented in [The Glean Dictionary](https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/). --- ### Performance Index (`docs/performance/index.md`) # Performance This page explains how to optimize the performance of the Firefox code base. The [test documentation](/testing/perfdocs/index.rst) explains how to test for performance in Firefox. The [profiler documentation](/tools/profiler/index.rst) explains how to use the Gecko profiler. ```{toctree} :hidden: :glob: * memory/* ``` ## General Performance references * Tips on generating valid performance metrics by [benchmarking](Benchmarking.md) * [GPU Performance](GPU_performance.md) Tips for reducing impacts on browser performance in front-end code. * [Automated Performance testing and Sheriffing](automated_performance_testing_and_sheriffing.md) Information on automated performance testing and sheriffing at Mozilla. * [Performance best practices for Firefox front-end engineers](bestpractices.md) Tips for reducing impacts on browser performance in front-end code. * [Reporting a performance problem](reporting_a_performance_problem.md) A user friendly guide to reporting a performance problem. A development environment is not required. * [Scroll Linked Effects](scroll-linked_effects.md) Information on scroll-linked effects, their effect on performance, related tools, and possible mitigation techniques. ## Memory profiling and leak detection tools * The [Developer Tools Memory panel](memory/memory.md) supports taking heap snapshots, diffing them, computing dominator trees to surface "heavy retainers", and recording allocation stacks. * [About:memory](memory/about_colon_memory.md) about:memory is the easiest-to-use tool for measuring memory usage in Mozilla code, and is the best place to start. It also lets you do other memory-related operations like trigger GC and CC, dump GC & CC logs, and dump DMD reports. about:memory is built on top of Firefox's [memory reporting](memory/memory_reporting.md) infrastructure. * [DMD](memory/dmd.md) is a tool that identifies shortcomings in about:memory's measurements, and can also do multiple kinds of general heap profiling. * [AWSY](memory/awsy.md) (are we slim yet?) is a memory usage and regression tracker. * [Bloatview](memory/bloatview.md) prints per-class statistics on allocations and refcounts, and provides gross numbers on the amount of memory being leaked broken down by class. It is used as part of Mozilla's continuous integration testing. * [Refcount Tracing and Balancing](memory/refcount_tracing_and_balancing.md) are ways to track down leaks caused by incorrect uses of reference counting. They are slow and not particular easy to use, and thus most suitable for use by expert developers. * [GC and CC Logs](memory/gc_and_cc_logs.md) * [LogAlloc](https://searchfox.org/firefox-main/source/memory/replace/logalloc/README) is a tool that dumps a log of memory allocations in Gecko. That log can then be replayed against Firefox's default memory allocator independently or through another replace-malloc library, allowing the testing of other allocators under the exact same workload. * [See also the documentation on Leak-hunting strategies and tips.](memory/leak_hunting_strategies_and_tips.md) ## Profiling and performance tools * [JIT Profiling with perf](jit_profiling_with_perf.md) Using perf to collect JIT profiles. * [JIT Profiling with samply](jit_profiling_with_samply.md) Using samply to collect JIT profiles * [Profiling with simpleperf](profiling_with_simpleperf.md) `simpleperf` is the Android equivalent of Linux's `perf` * [Profiling with Instruments](profiling_with_instruments.md) How to use Apple's Instruments tool to profile Mozilla code. * [Profiling with xperf](profiling_with_xperf.md) How to use Microsoft's Xperf tool to profile Mozilla code. * [Profiling with Concurrency Visualizer](profiling_with_concurrency_visualizer.md) How to use Visual Studio's Concurrency Visualizer tool to profile Mozilla code. * [Profiling with Zoom](profiling_with_zoom.md) Zoom is a profiler for Linux done by the people who made Shark. * [Adding a new telemetry probe](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/start/adding-a-new-probe.html) Information on how to add a new measurement to the Telemetry performance-reporting system ## Power Profiling * [An overview of power profiling](power_profiling_overview.md). It includes details about hardware, what can be measured, and recommended approaches. It should be the starting point for anybody new to power profiling. * **(Mac, Linux)** [tools/power/rapl](tools_power_rapl.md) is a command-line utility in the Mozilla codebase that uses the Intel RAPL interface to gather direct power estimates for the package, cores, GPU and memory. * **(Mac-only)** [powermetrics](powermetrics.md) is a command-line utility that gathers and displays a wide range of global and per-process measurements, including CPU usage, GPU usage, and various wakeups frequencies. * **(All-platforms)** [TimerFirings](timerfirings_logging.md) logging is a built-in logging mechanism that prints data on every time fired. * **(Mac-only)** [Activity Monitor and top](activity_monitor_and_top.md) The battery status menu, Activity Monitor and top are three related Mac tools that have major flaws but often consulted by users, and so are worth understanding. * **(Windows, Mac and Linux)** [Intel Power Gadget](intel_power_gadget.md) Intel Power Gadget provides real-time graphs for package and processor RAPL estimates. It also provides an API through which those estimates can be obtained. * **(Linux only)** [perf](perf.md) perf is a powerful command-line utility that can measure many different things, including energy estimates and high-context measurements of things such as wakeups. * **(Linux-only)** [turbostat](turbostat.md) is a command-line utility that gathers and displays various power-related measurements, with a focus on per-CPU measurements such as frequencies and C-states. * **(Linux-only)** [powertop](https://01.org/powertop) is an interactive command-line utility that gathers and displays various power-related measurements. ## Performance Metrics * [PerfStats](perfstats.md) - A framework for low-overhead collection of internal performance metrics. --- ### Performance Power Profiling Overview (`docs/performance/power_profiling_overview.md`) # Power profiling This article covers important background information about power profiling, with an emphasis on Intel processors used in desktop and laptop machines. It serves as a starting point for anybody doing power profiling for the first time. ## Basic physics concepts In physics, *[power](https://en.wikipedia.org/wiki/Power_%28physics%29)* is the rate of doing *[work](https://en.wikipedia.org/wiki/Work_%28physics%29 "Work (physics)")*. It is equivalent to an amount of *[energy](https://en.wikipedia.org/wiki/Energy_%28physics%29 "Energy (physics)"){.mw-redirect}* consumed per unit time. In SI units, energy is measured in Joules, and power is measured in Watts, which is equivalent to Joules per second. Although power is an instantaneous concept, in practice measurements of it are determined in a non-instantaneous fashion, i.e. by dividing an energy amount by a non-infinitesimal time period. Strictly speaking, such a computation gives the *average power* but this is often referred to as just the *power* when context makes it clear. In the context of computing, a fully-charged mobile device battery (as found in a laptop or smartphone) holds a certain amount of energy, and the speed at which that stored energy is depleted depends on the power consumption of the mobile device. That in turn depends on the software running on the device. Web browsers are popular applications and can be power-intensive, and therefore can significantly affect battery life. As a result, it is worth optimizing (i.e. reducing) the power consumption caused by Firefox and Firefox OS. ## Intel processor basics ### Processor layout The following diagram (from the [Intel Power Governor documentation)](https://software.intel.com/en-us/articles/intel-power-governor) shows how machines using recent Intel processors are constructed. The important points are as follows. - The processor has one or more *packages*. These are part of the actual processor that you buy from Intel. Client processors (e.g. Core i3/i5/i7) have one package. Server processors (e.g. Xeon) typically have two or more packages. - Each package contains multiple *cores*. - Each core typically has [hyper-threading](https://en.wikipedia.org/wiki/Hyper-threading), which means it contains two logical *CPUs*. - The part of the package outside the cores is called the [*uncore* or *system agent*](https://en.wikipedia.org/wiki/Uncore)*.* It includes various components including the L3 cache, memory controller, and, for processors that have one, the integrated GPU. - RAM is separate from the processor. ### C-states Intel processors have aggressive power-saving features. The first is the ability to switch frequently (thousands of times per second) between active and idle states, and there are actually several different kinds of idle states. These different states are called *[C-states](https://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface#Processor_states).* C0 is the active/busy state, where instructions are being executed. The other states have higher numbers and reflect increasing deeper idle states. The deeper an idle state is, the less power it uses, but the longer it takes to wake up from. Note: the [ACPI standard](https://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface) specifies four states, C0, C1, C2 and C3. Intel maps these to processor-specific states such as C0, C1, C2, C6 and C7. and many tools report C-states using the latter names. The exact relationship is confusing, and chapter 13 of the [Intel optimization manual](http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html) has more details. The important thing is that C0 is always the active state, and for the idle states a higher number always means less power consumption. The other thing to note about C-states is that they apply both to cores and the entire package --- i.e. if all cores are idle then the entire package can also become idle, which reduces power consumption even further. The fraction of time that a package or core spends in an idle C-state is called the *C-state residency*. This is a misleading term --- the active state, C0, is also a C-state --- but one that is nonetheless common. Intel processors have model-specific registers (MSRs) containing measurements of how much time is spent in different C-states, and tools such as [powermetrics](powermetrics.md) (Mac), powertop and [turbostat](turbostat.md) (Linux) can expose this information. A *wakeup* occurs when a core or package transitions from an idle state to the active state. This happens when the OS schedules a process to run due to some kind of event. Common causes of wakeups include scheduled timers going off and blocked I/O system calls receiving data. Maintaining C-state residency is crucial to keep power consumption low, and so reducing wakeup frequency is one of the best ways to reduce power consumption. One consequence of the existence of C-states is that observations made during power profiling --- even more than with other kinds of profiling --- can disturb what is being observed. For example, the Gecko Profiler takes samples at 1000Hz using a timer. Each of these samples can trigger a wakeup, which consumes power and obscures Firefox's natural wakeup patterns. For this reason, integrating power measurements into the Gecko Profiler is unlikely to be useful, and other power profiling tools typically use much lower sampling rates (e.g. 1Hz.) ### P-states Intel processors also support multiple *P-states*. P0 is the state where the processor is operating at maximum frequency and voltage, and higher-numbered P-states operate at a lower frequency and voltage to reduce power consumption. Processors can have dozens of P-states, but the transitions are controlled by the hardware and OS and so P-states are of less interest to application developers than C-states. ## Power and power-related measurements There are several kinds of power and power-related measurements. Some are global (whole-system) and some are per-process. The following sections list them from best to worst. ### Power measurements The best measurements are measured in joules and/or watts, and are taken by measuring the actual hardware in some fashion. These are global (whole-system) measurements that are affected by running programs but also by other things such as (for laptops) how bright the monitor backlight is. - Devices such as ammeters give the best results, but these can be expensive and difficult to set up. - A cruder technique that works with mobile machines and devices is to run a program for a long time and simply time how long it takes for the battery to drain. The long measurement times required are a disadvantage, though. ### Power estimates The next best measurements come from recent (Sandy Bridge and later) Intel processors that implement the *RAPL* (Running Average Power Limit) interface that provides MSRs containing energy consumption estimates for up to four *power planes* or *domains* of a machine, as seen in the diagram above. - PKG: The entire package. - PP0: The cores. - PP1: An uncore device, usually the GPU (not available on all processor models.) - DRAM: main memory (not available on all processor models.) The following relationship holds: PP0 + PP1 \<= PKG. DRAM is independent of the other three domains. These values are computed using a power model that uses processor-internal counts as inputs, and they have been [verified](http://www.computer.org/csdl/proceedings/ispass/2013/5776/00/06557170.pdf) as being fairly accurate. They are also updated frequently, at approximately 1,000 Hz, though the variability in their update latency means that they are probably only accurate at lower frequencies, e.g. up to 20 Hz or so. See section 14.9 of Volume 3 of the [Intel Software Developer's Manual](http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html) for more details about RAPL. Tools that can take RAPL readings include the following. - `tools/power/rapl`: all planes; Linux and Mac. - [Intel Power Gadget](intel_power_gadget.md): PKG and PP0 planes; Windows, Mac and Linux. - [powermetrics](powermetrics.md): PKG plane; Mac. - [perf](perf.md): all planes; Linux. - [turbostat](turbostat.md): PKG, PP0 and PP1 planes; Linux. Of these, [tools/power/rapl](tools_power_rapl.md) is generally the easiest and best to use because it reads all power planes, it's a command line utility, and it doesn't measure anything else. ### Proxy measurements The next best measurements are proxy measurements, i.e. measurements of things that affect power consumption such as CPU activity, GPU activity, wakeup frequency, C-state residency, disk activity, and network activity. Some of these are measured on a global basis, and some can be measured on a per-process basis. Some can also be measured via instrumentation within Firefox itself. The correlation between each proxy measure and power consumption is hard to know and can vary greatly. When used carefully, however, they can still be useful. This is because they can often be measured in a more fine-grained fashion than power measurements and estimates, which is vital for gaining insight into how a program can reduce power consumption. Most profiling tools provide at least some proxy measurements. ### Hybrid proxy measurements These are combinations of proxy measurements. The combinations are semi-arbitrary, they amplify the unreliability of proxy measurements, and unlike non-hybrid proxy measurements, they don't have a clear physical meaning. Avoid them. The most notable example of a hybrid proxy measurement is the ["Energy Impact" used by OS X's Activity [Monitor](activity_monitor_and_top.md#What-does-Energy-Impact-measure). ## Ways to user power-related measurements ### Low-context measurements Most power-related measurements are global or per-process. Such low-context measurements are typically good for understand *if* power consumption is good or bad, but in the latter case they often don't provide much insight into why the problem is occurring, which part of the code is at fault, or how it can be fixed. Nonetheless, they can still help improve understanding of a problem by using *differential profiling*. - Compare browsers to see if Firefox is doing better or worse than another browser on a particular workload. - Compare different versions of Firefox to see if Firefox has improved or worsened over time on a particular workload. This can identify specific changes that caused regressions, for example. - Compare different configurations of Firefox to see if a particular feature is affecting things. - Compare different workloads. This can be particularly useful if the workloads only vary slightly. For example, it can be useful to gradually remove elements from a web page and see how the power-related measurements change. Even just switching a tab from the foreground to the background can make a difference. ### High-context measurements A few power-related measurements can be obtained in a high-context fashion, e.g. with stack traces that clearly pinpoint specific parts of the code as being responsible. - Standard performance profiling tools that measure CPU usage or proxies of CPU usage (such as instruction counts) typically provide high-context measurements. This is useful because high CPU usage typically causes high power consumption. - Some tools can provide high-context wakeup measurements: [dtrace](dtrace.md) (on Mac) and [perf](perf.md) (on Linux.) - Source-level instrumentation, such as [TimerFirings logging](timerfirings_logging.md), can identify which timers are firing frequently. ## Power profiling how-to This section aims to put together all the above information and provide a set of strategies for finding, diagnosing and fixing cases of high power consumption. - First of all, all measurements are best done on a quiet machine that is running little other than the program of interest. Global measurements in particular can be completely skewed and unreliable if this is not the case. - Find or confirm a test case where Firefox's power consumption is high. "High" can most easily be gauged by comparing against other browsers. Use power measurements or estimates (e.g. via [tools/power/rapl](tools_power_rapl.md), or `mach power` on Mac, or [Intel Power Gadget](intel_power_gadget.md) on Windows) for the comparisons. Avoid lower-quality measurements, especially Activity Monitor's "Energy Impact". - Try using differential profiling to narrow down the cause. - Try turning hardware acceleration on or off; e10s on or off; Flash on or off. - Try putting the relevant tab in the foreground vs. in the background. - If the problem manifests on a particular website, try saving a local copy of the site and then manually removing HTML elements to see if a particular page feature is causing the problem - Many power problems are caused by either high CPU usage or high wakeup frequency. Use one of the low-context tools to determine if this is the case (e.g. on Mac use [powermetrics](powermetrics.md).) If so, follow that up by using a tool that gives high-context measurements, which hopefully will identify the cause of the problem. - For high CPU usage, many profilers can be used: Firefox's dev tools profiler, the Gecko Profiler, or generic performance profilers. - For high wakeup counts, use [dtrace](dtrace.md) or [perf](perf.md) or [TimerFirings logging](timerfirings_logging.md). - On Mac workloads that use graphics, Activity Monitor's "Energy" tab can tell you if the high-performance GPU is being used, which uses more power than the integrated GPU. - If neither CPU usage nor wakeup frequency identifies the problem, more ingenuity may be needed. Looking at other measurements (C-state residency, GPU usage, etc.) may be helpful. - Animations are sometimes the cause of high power consumption. The [animation inspector](/devtools-user/page_inspector/how_to/work_with_animations/index.rst#animation-inspector) in the Firefox Devtools can identify them. Alternatively, [here is an explanation](https://bugzilla.mozilla.org/show_bug.cgi?id=1190721#c10) of how one developer diagnosed two animation-related problems the hard way (which required genuine platform expertise). - The approximate cause of power problems often isn't that hard to find. Fixing them is often the hard part. Good luck. - If you do fix a problem by improving a proxy measurement, you should verify that it also improves a power measurement or estimate. That way you know the fix had a genuine effect. ## Further reading Chapter 13 of the [Intel optimization manual](http://www.intel.com/content/www/us/en/architecture-and-technology/64-ia-32-architectures-optimization-manual.html) has many details about optimizing for power consumption. Section 13.5 ("Tuning Software for Intelligent Power Consumption") in particular is worth reading. --- ### Rust Components Index (`docs/rust-components/index.md`) # Rust Components This section is meant to make it easier to use and implement cross-platform components written in Rust. ```{toctree} :titlesonly: :maxdepth: 2 Topic Guides API References Developing Rust Components uniffi-bindgen-gecko-js developers guide ``` --- ### Testing Rust Code Index (`docs/testing-rust-code/index.md`) # Testing & Debugging Rust Code This page explains how to test and debug Rust code in Firefox. The [build documentation](/build/buildsystem/rust.rst) explains how to add new Rust code to Firefox. The [code documentation](/writing-rust-code/index.md) explains how to write and work with Rust code in Firefox. ## Testing Mozilla crates Rust code will naturally be tested as part of system tests such as Mochitests. This section describes the two methods for unit testing of individual Rust crates. Which method should be used depends on the circumstances. ### Rust tests If a Mozilla crate has "normal" Rust tests (i.e. `#[test]` functions that run with `cargo test`), you can add the crate's name to `RUST_TESTS` in [toolkit/library/rust/moz.build](https://searchfox.org/firefox-main/source/toolkit/library/rust/moz.build). (Cargo features can be activated for Rust tests by adding them to `RUST_TEST_FEATURES` in the same file.) Rust tests are run with `./mach rusttests`. They run on automation in a couple of `rusttests` jobs, but not on all platforms. Rust tests have one major restriction: they cannot link against Gecko symbols. Therefore, Rust tests cannot be used for crates that use Gecko crates like `nsstring` and `xpcom`. It's also possible to use `RUST_TESTS` in a different `moz.build` file. See `testing/geckodriver/moz.build` and the [geckodriver testing docs] for an example. [geckodriver testing docs]: /testing/geckodriver/Testing.md ### GTests Another way to unit test a Mozilla crate is by writing a GTest that uses FFI to call into Rust code. This requires the following steps. - Create a new test crate whose name is the same as the name of crate being tested, with a `-gtest` suffix. - Add to the test crate a Rust file, a C++ file containing GTest `TEST()` functions that use FFI to call into the Rust file, a `Cargo.toml` file that references the Rust file, and a `moz.build` file that references the C++ file. - Add an entry to the `[dependencies]` section in [toolkit/library/gtest/rust/Cargo.toml](https://searchfox.org/firefox-main/source/toolkit/library/gtest/rust/Cargo.toml). - Add an `extern crate` entry to [toolkit/library/gtest/rust/lib.rs](https://searchfox.org/firefox-main/source/toolkit/library/gtest/rust/lib.rs). See [xpcom/rust/gtest/nsstring/](https://searchfox.org/firefox-main/source/xpcom/rust/gtest/nsstring) for a simple example. (Note that the `moz.build` file is in the parent directory for that crate.) A Rust GTest can be run like any other GTest via `./mach gtest`, using the C++ `TEST()` functions as the starting point. Unlike Rust tests, GTests can be used when linking against Gecko symbols is required. ## Testing third-party crates In general we don't run tests for third-party crates. The assumption is that these crates are sufficiently well-tested elsewhere. ## Debugging Rust code In theory, Rust code is debuggable much like C++ code, using standard tools like `gdb`, `rr`, and the Microsoft Visual Studio Debugger. In practice, the experience can be worse, because shortcomings such as the following can occur. - Inability to print local variables, even in non-optimized builds. - Inability to call generic functions. - Missing line numbers and stack frames. - Printing of basic types such as `Option` and `Vec` is sometimes sub-optimal. If you see a warning "Missing auto-load script at offset 0 in section `.debug_gdb_scripts`" when starting `gdb`, the `rust-gdb` wrapper may give better results. ## Logging from Rust code ### Rust logging The `RUST_LOG` environment variable (from the `env_logger` crate) can be used to enable logging to stderr from Rust code in Firefox. The logging macros from the `log` crate can be used. In order of importance, they are: `error!`, `warn!`, `info!`, `debug!`, `trace!`. For example, to show all log messages of `info` level or higher, run: ``` RUST_LOG=info firefox ``` Module-level logging can also be specified, see the [documentation] for the `env_logger` crate for details. To restrict logging to child processes, use `RUST_LOG_CHILD` instead of `RUST_LOG`. [documentation]: https://docs.rs/env_logger/ ### Gecko logging Rust logging can also be forwarded to the [Gecko logger] for capture via `MOZ_LOG` and `MOZ_LOG_FILE`. [Gecko logger]: /xpcom/logging.rst - When parsing modules from `MOZ_LOG`, modules containing `::` are considered to be Rust modules. To log everything in a top-level module like `neqo_transport`, specify it as `neqo_transport::*`. For example: ``` MOZ_LOG=timestamp,sync,nsHostResolver:5,neqo_transport::*:5,proxy:5 firefox ``` - When logging from a submodule the `::*` is allowed but isn't necessary. So these two lines are equivalent: ``` MOZ_LOG=timestamp,sync,neqo_transport::recovery:5 firefox MOZ_LOG=timestamp,sync,neqo_transport::recovery::*:5 firefox ``` - `debug!` and `trace!` logs will not appear in non-debug builds. This is due to our use of the `release_max_level_info` feature in the `log` crate. - When using both `MOZ_LOG` and `RUST_LOG`, modules that are specified in `MOZ_LOG` will not appear in `RUST_LOG`. --- ### Update Infrastructure Index (`docs/update-infrastructure/index.md`) # Mozilla Update Infrastructure Firefox, Thunderbird, and Mozilla VPN updates rely on [backend service known as Balrog](https://github.com/mozilla-releng/balrog). Periodically, these applications check for updates by pinging an URL[^1] which contains information about both the application running, and details of the system it is running on. If Balrog finds an update based on the provided information, it returns a simple XML response with a link to the update file, and some metadata about it. # Watershed Updates Most of the time, an update will take an application directly from whatever version it is currently running to the latest version of that application. This is greatly preferred, both to save time, bandwidth, reduce restarts, and increase security by ensuring we get to the latest version of something as quickly as possible. Unfortunately, sometimes we must route through an intermediate version first, typically the version that is currently running does not provide Balrog with enough information to accurately serve a correct update to the latest version. These are colloquially known as "watershed" updates. (This name comes from the fact that these updates change something about the update process itself, making them a kind of "watershed moment" for updates.) At the time of writing (July, 2024), we currently have the following watershed updates in place for Firefox's release channel: * 12.0, all platforms. In this release [we added support for distinguishing the running and supported architectures in macOS builds in the update URL](https://bugzilla.mozilla.org/show_bug.cgi?id=583671). * 43.0.1, Windows only. This release was [preparation for desupporting SHA-1 hashes in our Windows builds](https://bugzilla.mozilla.org/show_bug.cgi?id=1234277). * 45.0.2, Linux only. We added support for [sending the GTK 3 version to the update URL](https://bugzilla.mozilla.org/show_bug.cgi?id=1227023). * 47.0.2, Windows only. We [added CPU instruction set information to the update URL](https://bugzilla.mozilla.org/show_bug.cgi?id=1271761) to later allow SSE1 to be deprecated. * 56.0, Windows only. We added support for [sending information about the JAWS accessibility application to the update URL](https://bugzilla.mozilla.org/show_bug.cgi?id=1402376) to avoid updating people on crashy versions of it. Additionally, we [added support for LZMA compression to the updater](https://bugzilla.mozilla.org/show_bug.cgi?id=641212) and [swapped to new MAR signing keys](https://bugzilla.mozilla.org/show_bug.cgi?id=1324498). * 57.0.4[^2], Linux & Mac only. We [added support for LZMA compression to the updater](https://bugzilla.mozilla.org/show_bug.cgi?id=641212) and [swapped to new MAR signing keys](https://bugzilla.mozilla.org/show_bug.cgi?id=1324498). (Note: Windows was not required here because they picked up this change in the above 56.0 watershed.) * 72.0.2, all platforms. This is a required version due to a [necessary two-step password database migration](https://bugzilla.mozilla.org/show_bug.cgi?id=1615382). * 109.0.1, macOS only. This updates the channel-prefs.js file (normally excluded from updates) due to [signature issues](https://bugzilla.mozilla.org/show_bug.cgi?id=1804303). * 127.0, Windows only. The issuer for our code-signing certificate changed, [requiring an updated Mozilla Maintenance Service](https://bugzilla.mozilla.org/show_bug.cgi?id=1894689). [^1]: Here is a sample URL: [^2]: While not directly related to the watershed, it is notable that due to LZMA MAR support shipping in the previous version (56.0), which was _not_ a watershed for Linux and Mac, we shipped two different sets of MARs for 57.0, 57.0.1, 57.0.2, 57.0.3, and 57.0.4: we had bz2 MARs, which builds older than 56.0 were served, and a separate set of LZMA MARs that were shipped to 56.0 and higher. More details on this can be found on [this awfully complicated spreadsheet that was produced around that time](https://docs.google.com/spreadsheets/d/1xcs9iTShJI8WBvxrz547Zr5JClqdRUYEZRMbQqdQ58I/edit#gid=0). # Desupport Updates From time to time we stop supporting a platform, hardware or library that we depend on. When we do this, we must ensure we don't update affected users to a version that they can no longer run. This can take two forms: * In the distant past, we would simply stop serving updates altogether, leaving users on their current version. * More recently, we will first move users to our `esr` channel - generally giving them another year of support before ending updates altogether. Below is a list of desupports and moves to `esr` that we've done on the Firefox release channel: * (Ancient, desupported at various old versions): Darwin 6, Darwin 7, Darwin 8, Darwin 9, Windows_95, Windows_98, Windows_NT 4, Windows_NT 5.0, Windows_NT 5.1.0, Windows_NT 5.1.1, GTK 2.0., GTK 2.1., GTK 2.2., GTK 2.3., GTK 2.4., GTK 2.5., GTK 2.6., GTK 2.7., GTK 2.8., GTK 2.9., GTK 2.10., GTK 2.11., GTK 2.12., GTK 2.13., GTK 2.14., GTK 2.15., GTK 2.16., GTK 2.17., PPC Architecture * <46.0: [Desupported GTK <3.4](https://bugzilla.mozilla.org/show_bug.cgi?id=1270358) * <49.0: Desupported [Darwin 10, 11, and 12](https://bugzilla.mozilla.org/show_bug.cgi?id=1275607) (macOS 10.6, 10.7, 10.8), [SSE and MMX instruction sets](https://bugzilla.mozilla.org/show_bug.cgi?id=1284901) * <52.0: [Moved Windows XP, Server 2003, and Vista users to esr52](https://bugzilla.mozilla.org/show_bug.cgi?id=1318922) * <53.0: [Desupported 32-bit macOS hardware](https://bugzilla.mozilla.org/show_bug.cgi?id=1325584) * <77.0: [Moved Darwin 13, 14, and 15](https://bugzilla.mozilla.org/show_bug.cgi?id=1639199) (macOS 10.9, 10.10, and 10.11) to esr78 * <116.0: [Moved Darwin 16, 17, and 18](https://bugzilla.mozilla.org/show_bug.cgi?id=1836375) (macOS 10.12, 10.13, and 10.14) to esr115 * <116.0: [Moved Windows 7, 8, and 8.1](https://bugzilla.mozilla.org/show_bug.cgi?id=1594270) to esr115 --- ### Writing Rust Code Index (`docs/writing-rust-code/index.md`) # Writing Rust Code This page explains how to write and work with Rust code in Firefox, with an emphasis on interoperation with C++ code. The [build documentation](/build/buildsystem/rust.rst) explains how to add new Rust code to Firefox. The [test documentation](/testing-rust-code/index.md) explains how to test and debug Rust code in Firefox. ```{toctree} :titlesonly: :maxdepth: 1 :glob: * ``` --- ### Devtools Docs Contributor README (`devtools/docs/contributor/README.md`) # Firefox Developer Tools: Contributor Docs This is a guide to working on the code for Firefox Developer Tools. If you're looking for help with using the tools, see the [user docs](https://firefox-source-docs.mozilla.org/devtools-user/). For other ways to get involved, check out our [community site](https://firefox-dev.tools). --- ### Devtools Docs Contributor Architecture Overview (`devtools/docs/contributor/architecture-overview.md`) # Architecture overview Broadly speaking, the tools are divided in two parts: the server and the client. A **server** is anything that can be debugged: for example, your browser, but it could also be Firefox for Android, running on another device. The **client** is the front-end side of the tools, and it is what developers interact with when using the tools. Since these two parts are decoupled, we can connect to any server using the same client. This enables us to debug multiple types of servers, using the same protocol to communicate. You will often hear about `actors`. Each feature that can be debugged (for example, network) is exposed via an `actor`, which provides data about that specific feature. It's up to each server to implement some or all actors; the client needs to find out and decide what it can render on the front-side when it connects to the server. So when we want to debug a new feature, we might need to do work in two parts of the code: the server (perhaps implementing a new actor, or extending existing ones) and the client (to display the debugging data returned by the actor). Often, an actor will correspond to a panel. But a panel might want to get data from multiple actors. You might also hear about `the toolbox`. The toolbox is what everyone else calls `developer tools` i.e. the front-end that you see when you open the tools in your browser. --- ### Code Quality Typescript Index (`docs/code-quality/typescript/index.md`) # TypeScript In firefox-main, we are introducing the use of [TypeScript](https://www.typescriptlang.org/) to help provide type autocompletion, static analysis and type checking of our JavaScript code. :::{note} At the moment we are in the bootstrap/experimentation phase, there are various parts of infrastructure that have not yet been created, and incomplete type definitions which may cause issues for projects. Hence TypeScript is not recommended for all projects for the time being. We are currently prioritising enabling type autocompletion across the code base, before we proceed to more work on type checking. You can work towards enabling TypeScript by ensuring your code passes the [ESLint jsdoc rules](https://searchfox.org/firefox-main/search?q=jsdoc%2F&path=eslint-plugin-mozilla%2Flib%2Fconfigs&case=false®exp=false). If you are interested, please ask in the Lint and Formatting channel (#lint:mozilla.org) on Matrix. ::: ## Where TypeScript is Currently Enabled TypeScript is currently only enabled on a [limited set of directories](https://searchfox.org/firefox-main/source/tools/lint/typescript.yml). ## Editor Support VS Code has TypeScript support built-in and should work "out of the box". For other editors, see this [TypeScript Wiki Page](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support). ## Running TypeScript Locally The TypeScript linter may be run on the directories where it is enabled using: ``` ./mach lint -l typescript path/to/file # (or to the directory) ``` ## Updating Gecko Type Definitions Updating types currently happens manually, although [we are in the process of automating it](https://bugzilla.mozilla.org/show_bug.cgi?id=1975513). In the meantime, developers using TypeScript must update the type definitions [manually using some scripts](updatingTypes.md). ## Best Practices For working with TypeScript we have some [best practices](bestPractices.md) which will help to get the type definitions set up correctly. ## Frequently Asked Questions * Why does running TypeScript check and report errors in other files? * Changes in one file may impact on another, and TypeScript can detect this. * Additionally, the way that TypeScript works means that it will run across the whole project regardless, so we report all the issues that it reports. * Will my patches get backed out due to TypeScript failures? * Currently no. Whilst we have a [TypeScript Linter on CI](../lint/linters/typescript.rst) it is currently tier-3 which is hidden from the sheriffs view. * Failures will however, be reported on reviews on Phabricator. * We will promote the linter to tier-2 and tier-1 once we have more automation in place for type generation. * Why isn't this being encouraged for everyone? * As discussed in the note at the top of the page, we are still in the set-up and experimentation phase. There is a lot of infrastructure that is required to make TypeScript usable on a day to day basis. * Are we planning to allow using TypeScript files and compiling directly from TypeScript? * No. In the past we've worked to avoid processing or compilation steps, wherever possible when developing JavaScript. This helps to reduce code-test cycle times and make debugging simpler. * Whilst it is possible we could change the approach in future, it is not an objective of enabling TypeScript over the firefox-main code base. * Something isn't working as I would expect, where should I look/ask? * We have a [meta bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1945456) for TypeScript issues in firefox-main. We work through them over time, though we appreciate help as well. * See the [Getting Help](#getting-help) section. ## Getting Help The Lint & Formatting channel (#lint:mozilla.org) on Matrix is the best place to ask questions. ## Further Reading * The [TypeScript documentation](https://www.typescriptlang.org/docs/) is very useful in understanding how TypeScript works and how types may be set up. * The [JavaScript section starting here](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html), is especially useful for firefox-main development. --- ### Rust Components Api Index (`docs/rust-components/api/index.md`) # Rust components API References Choose a language to get started - [JS](./js/index.md) - [Kotlin](https://mozilla.github.io/application-services/kotlin/index.html) - [Swift](https://mozilla.github.io/application-services/swift/index.html) --- ### Rust Components Developing Rust Components Index (`docs/rust-components/developing-rust-components/index.md`) # Developing Shared Rust Components Shared Rust Components is a strategy to create a single component that provides the same functionality for Firefox Desktop, Firefox Android and Firefox iOS. This strategy was first adopted for sync in response to issues stemming from separate sync implementations for each application. Separate sync implementations lead to duplicate logic across platforms, which was difficult to maintain. Furthermore, the likelihood of errors was very high -- especially since each implementation had to sync with the other implementations. Since then more components have adopted the Rust components strategy and some non-Firefox projects have started using the components (for example nimbus-experimenter). The basic idea is to write the component in Rust then generate a set of Kotlin/Swift/JS bindings that can be consumed by the Firefox applications. Rust was chosen because it supports a large number of target platforms, including Android and iOS. The [UniFFI](https://mozilla.github.io/uniffi-rs/latest/) library was created to handle bindings generation. ## Pros and cons of adding a shared Rust component ### Pros * Less work than creating a multiple implementations. * More consistent behavior across different applications. * Better sync integrations (this follows from the last point, since behavior differences often become larger bugs when sync is involved). * Build JavaScript, Kotlin, and Swift docs from the Rust docstrings. ### Cons * More work than creating a single implementation. * Requires engineers to write and understand Rust. * Still requires some application glue code to integrate the component. Often it's trivial like [TabsStore](https://searchfox.org/firefox-main/source/services/sync/modules/TabsStore.sys.mjs), but sometimes it's larger. ### Neutral * Performance is usually similar to JavaScript/Kotlin code. FFI overhead typically negates any speedups from using Rust. ## Shared Rust component ownership Teams that write shared Rust components are responsible for maintaining their health. This includes monitoring error reports and working with application teams to maintain integrations as the application code changes. Error reports are currently only available for Android, but we will soon be extending this to all platforms. ```{toctree} :titlesonly: :maxdepth: 1 example-component uniffi logging observability threading other-desktop-specific-concerns ``` --- ### Rust Components Topic Guides Index (`docs/rust-components/topic-guides/index.md`) # Topic Guides Here are the guides on various topics related to Rust components. ```{toctree} :titlesonly: :maxdepth: 1 :glob: * ``` --- ### Rust Components Uniffi Bindgen Gecko Js Dev Guide Index (`docs/rust-components/uniffi-bindgen-gecko-js-dev-guide/index.md`) # uniffi-bindgen-gecko-js Developers Guide This section describes the internal workings of `uniffi-bindgen-gecko-js` for developers working with this code. It builds on the [UniFFI user guide](https://mozilla.github.io/uniffi-rs/latest/) internals documentation, which is recommended reading before diving into these specifics. ## UniFFI bindings pipeline `uniffi-bindgen-gecko-js` uses the bindings pipeline ([docs](https://github.com/mozilla/uniffi-rs/blob/main/docs/manual/src/internals/bindings_ir.md) [more docs](https://github.com/mozilla/uniffi-rs/blob/main/docs/manual/src/internals/bindings_ir_pipeline.md)). `uniffi-bindgen-gecko-js` is the first bindings generator to adopt this code, although we hope to eventually move all bindings to this system. This means the `uniffi-bindgen-gecko-js` code may look different than other bindings, but we hope it's only temporary. ```{toctree} :titlesonly: :maxdepth: 1 js-and-cpp-layers lifting-and-lowering rust-calls js-callback-interfaces ``` --- ### Dom Docs Push Index (`dom/docs/push/index.md`) # Push
Note
This document describes how Firefox implements the Web Push standard internally, and is intended for developers working directly on Push. If you are looking for how to consume push, please refer to the following MDN document
## High level push architecture The following sequence diagram describes the high level push architecture as observed by web application. The diagram describes the interactions between a Web application's client code running in the browser, Firefox, [Autopush](https://autopush.readthedocs.io/en/latest/) (Firefox's push server that delivers push notifications) and a third party server that sends the push notifications to Autopush The dotted lines are done by the consumer of push. ```{mermaid} sequenceDiagram participant TP as Web Application JS participant F as Firefox participant A as Autopush participant TPS as Third party Server TP->>F: subscribe(scope) activate TP activate F F->>A: subscribe(scope) using web socket activate A A->>F: URL deactivate A F->>F: Create pub/privKey Encryption pair F->>F: Persist URL, pubKey, privKey indexed using an id derived from scope F->>TP: URL + pubKey deactivate F TP-->>TPS: URL + pubKey deactivate TP TPS-->>TPS: Encrypt payload using pubKey TPS-->>A: Send encrypted payload using URL activate A A->>F: Send encrypted payload using web socket deactivate A activate F F->>F: Decrypt payload using privKey F->>F: Display Notification deactivate F ``` ## Firefox Desktop ### Flow diagram for source code The source code for push is available under [`dom/push`](https://searchfox.org/firefox-main/source/dom/push) in mozilla-central. The following flow diagram describes how different modules interact with each other to provide the push API to consumers. ```{mermaid} flowchart TD subgraph Public API W[Third party Web app]-->|imports| P[PushManager.webidl] end subgraph Browser Code P-->|Implemented by| MM MM{Main Thread?}-->|Yes| B[Push.sys.mjs] MM -->|NO| A[PushManager.cpp] B-->|subscribe,getSubscription| D[PushComponents.sys.mjs] A-->|subscribe,getSubscription| D D-->|subscribe,getSubscription| M[PushService.sys.mjs] M-->|Storage| S[PushDB.sys.mjs] M-->|Network| N[PushWebSocket.sys.mjs] F[FxAccountsPush.sys.mjs] -->|uses| D end subgraph Server N-. Send, Receive.-> O[Autopush] end subgraph Local Storage S-->|Read,Write| PP[(IndexedDB)] end ``` ### The Push Web Socket Push in Firefox Desktop communicates with Autopush using a web socket connection. The web socket connection is created as the browser initializes and is managed by the following state diagram. ```{mermaid} stateDiagram-v2 state "Shut Down" as SD state "Waiting for WebSocket to start" as W1 state "Waiting for server hello" as W2 state "Ready" as R [*] --> SD SD --> W1: beginWSSetup W1 --> W2: wsOnStart Success W2 --> R: handleHelloReply R --> R: send (subscribe) R --> R: Receive + notify observers R --> SD: wsOnStop R --> SD: sendPing Fails W1 --> SD: wsOnStart fails W2 --> SD: invalid server hello R --> [*] ``` Once the Push web socket is on the `Ready` state, it is ready to send new subscriptions to Autopush, and receive push notifications from those subscriptions. Push uses an observer pattern to notify observers of any incoming push notifications. See the [high level architecture](#high-level-push-architecture) section. ### Push Storage Push uses IndexedDB to store subscriptions for the following reasons: 1. In case the consumer attempts to re-subscribe, storage is used as a cache to serve the URL and the public key 1. In order to persist the private key, so that it can be used to decrypt any incoming push notifications The following is what gets persisted: ```{mermaid} erDiagram Subscription { string channelID "Key, Derived from scope" string pushEndpoint "Unique endpoint for this subscription" string scope "Usually the origin, unique value for internal consumers" Object p256dhPublicKey "Object representing the public key" Object p256dhPrivateKey "Object representing the private key" } ``` ## Firefox for Android See also: * [Rust Push Component](https://mozilla.github.io/application-services/book/rust-docs/push/index.html) * [Push Service Bridge HTTP Interface](https://autopush.readthedocs.io/en/latest/http.html#push-service-bridge-http-interface) * [Android Components: Push](https://github.com/mozilla/gecko-dev/blob/master/mobile/android/android-components/components/feature/push/README.md) ### Flow diagram for source code The source code for push is available under the following paths in mozilla-central: * [`dom/push/`](https://searchfox.org/firefox-main/source/dom/push/) * [`mobile/shared/components/geckoview/GeckoViewPush.sys.mjs`](mobile/shared/components/geckoview/GeckoViewPush.sys.mjs) * [`mobile/android/geckoview/src/main/java/org/mozilla/geckoview/WebPush*.java`](https://searchfox.org/firefox-main/source/mobile/android/geckoview/src/main/java/org/mozilla/geckoview/) * Under `mobile/android/android-components/components`: * [`feature/push/src/main/java/mozilla/components/feature/push/`](https://searchfox.org/firefox-main/source/mobile/android/android-components/components/feature/push/src/main/java/mozilla/components/feature/push/) * [`browser/engine-gecko/src/main/java/mozilla/components/browser/engine/gecko/webpush/`](https://searchfox.org/firefox-main/source/mobile/android/android-components/components/browser/engine-gecko/src/main/java/mozilla/components/browser/engine/gecko/webpush/) * [`concept/engine/src/main/java/mozilla/components/concept/engine/webpush`](https://searchfox.org/firefox-main/source/mobile/android/android-components/components/concept/engine/src/main/java/mozilla/components/concept/engine/webpush/) * [Rust Push Component](https://github.com/mozilla/application-services/tree/main/components/push) The following flow diagram describes how different modules interact with each other to provide the push API to consumers. ```{mermaid} flowchart TD subgraph Public API W[Third party Web app]-->|imports| P[PushManager.webidl] end subgraph Browser Code P-->|Implemented by| MM MM{Main Thread?}-->|Yes| B[Push.sys.mjs] MM -->|NO| A[PushManager.cpp] B-->|subscribe,getSubscription| D[GeckoViewPush.sys.mjs] A-->|subscribe,getSubscription| D D-->|PushSubscribe,PushGetSubscription| WPC[WebPushController.java] WPC-->|onSubscribe,onGetSubscription| WPEI[WebPushEngineIntegration.kt] WPEI-->|subscribe,getSubscription| APF[AutoPushFeature.kt] APF-->|start| PS[AbstractFirebasePushService.kt] FCM[Firebase Cloud Messaging]-->|onNewToken| PS PS-->|onNewToken| APF APF-->|subscribe,getSubscription| PRS[push/src/lib.rs] PRS-->|subscribe,get_subscription| PM[internal/push_manager.rs] PM-->|Storage| S[internal/storage/db.rs] PM-->|Network| N[internal/communications.rs] end subgraph Server N-. bridge interface.-> O[Autopush] end subgraph Local Storage S-->|Read,Write| SQL[(SQLite)] end ``` --- ### Dom Docs WebIdlBindings Index (`dom/docs/webIdlBindings/index.md`) # Web IDL bindings
Note
Need to document the setup for indexed and named setters/creators/deleters.
The [Web IDL](https://webidl.spec.whatwg.org/) bindings are generated at build time based on two things: the actual Web IDL file and a configuration file that lists some metadata about how the Web IDL should be reflected into Gecko-internal code. All Web IDL files should be placed in [`dom/webidl`](https://searchfox.org/firefox-main/source/dom/webidl/) and added to the list in the [moz.build](https://searchfox.org/firefox-main/source/dom/webidl/moz.build) file in that directory. Note that if you're adding new interfaces, then the test at `dom/tests/mochitest/general/test_interfaces.html` will most likely fail. This is a signal that you need to get a review from a [DOM peer](https://wiki.mozilla.org/Modules/All#Document_Object_Model). Resist the urge to just add your interfaces to the [moz.build](https://searchfox.org/firefox-main/source/dom/webidl/moz.build) list without the review; it will just annoy the DOM peers and they'll make you get the review anyway. The configuration file, `dom/bindings/Bindings.conf`, is basically a Python dict that maps interface names to information about the interface, called a _descriptor_. There are all sorts of possible options here that handle various edge cases, but most descriptors can be very simple. All the generated code is placed in the `mozilla::dom` namespace. For each interface, a namespace whose name is the name of the interface with `Binding` appended is created, and all the things pertaining to that interface's binding go in that namespace. There are various helper objects and utility methods in [`dom/bindings`](https://searchfox.org/firefox-main/source/dom/bindings) that are also all in the `mozilla::dom` namespace and whose headers are all exported into `mozilla/dom` (placed in `$OBJDIR/dist/include` by the build process). ## Adding Web IDL bindings to a class To add a Web IDL binding for interface `MyInterface` to a class `mozilla::dom::MyInterface` that's supposed to implement that interface, you need to do the following: 1. If your interface doesn't inherit from any other interfaces, inherit from `nsWrapperCache` and hook up the class to the cycle collector so it will trace the wrapper cache properly. Note that you may not need to do this if your objects can only be created, never gotten from other objects. If you also inherit from `nsISupports`, make sure the `nsISupports` comes before the `nsWrapperCache` in your list of parent classes. If your interface _does_ inherit from another interface, just inherit from the C++ type that the other interface corresponds to. If you do need to hook up cycle collection, it will look like this in the common case of also inheriting from nsISupports: ``` cpp // Add strong pointers your class holds here. If you do, change to using // NS_IMPL_CYCLE_COLLECTION_WRAPPERCACHE. NS_IMPL_CYCLE_COLLECTION_WRAPPERCACHE_0(MyClass) NS_IMPL_CYCLE_COLLECTING_ADDREF(MyClass) NS_IMPL_CYCLE_COLLECTING_RELEASE(MyClass) NS_INTERFACE_MAP_BEGIN_CYCLE_COLLECTION(MyClass) NS_WRAPPERCACHE_INTERFACE_MAP_ENTRY NS_INTERFACE_MAP_ENTRY(nsISupports) NS_INTERFACE_MAP_END ``` 1. If your class doesn't inherit from a class that implements `GetParentObject`, then add a function of that name that, for a given instance of your class, returns the same object every time (unless you write explicit code that handles your parent object changing by reparenting JS wrappers, as nodes do). The idea is that walking the `GetParentObject` chain will eventually get you to a Window, so that every Web IDL object is associated with a particular Window. For example, `nsINode::GetParentObject` returns the node's owner document. The return type of `GetParentObject` doesn't matter other than it must either singly-inherit from `nsISupports` or have a corresponding [`ToSupports`](https://searchfox.org/firefox-main/search?q=ToSupports&path=&case=true®exp=false) method that can produce an `nsISupports` from it. (This allows the return value to be implicitly converted to a [`ParentObject`](https://searchfox.org/firefox-main/search?q=ParentObject&path=&case=true®exp=false) instance by the compiler via one of that class's non-explicit constructors.) If many instances of `MyInterface` are expected to be created quickly, the return value of `GetParentObject` should itself inherit from `nsWrapperCache` for optimal performance. Returning null from `GetParentObject` is allowed in situations in which it's OK to associate the resulting object with a random global object for security purposes; this is not usually ok for things that are exposed to web content. Again, if you do not need wrapper caching you don't need to do this. The actual type returned from `GetParentObject` must be defined in a header included from your implementation header, so that this type's definition is visible to the binding code. 1. Add the Web IDL for `MyInterface` in `dom/webidl` and to the list in `dom/webidl/moz.build`. 1. Add an entry to `dom/bindings/Bindings.conf` that sets some basic information about the implementation of the interface. If the C++ type is not `mozilla::dom::MyInterface`, you need to set the `'nativeType'` to the right type. If the type is not in the header file one gets by replacing '::' with '/' and appending '`.h`', then add a corresponding `'headerFile'` annotation (or [`HeaderFile`](#headerfile-path-to-headerfile-h) annotation to the .webidl file). If you don't have to set any annotations, then you don't need to add an entry either and the code generator will simply assume the defaults here. Note that using a `'headerFile'` annotation is generally not recommended. If you do use it, you will need to make sure your header includes all the headers needed for your [`Func`](#func-funcname) annotations. 1. Add external interface entries to `Bindings.conf` for whatever non-Web IDL interfaces your new interface has as arguments or return values. 1. Implement a `WrapObject` override on `mozilla::dom::MyInterface` that just calls through to `mozilla::dom::MyInterface_Binding::Wrap`. Note that if your C++ type is implementing multiple distinct Web IDL interfaces, you need to choose which `mozilla::dom::MyInterface_Binding::Wrap` to call here. See `AudioContext::WrapObject`, for example. 1. Expose whatever methods the interface needs on `mozilla::dom::MyInterface`. These can be inline, virtual, have any calling convention, and so forth, as long as they have the right argument types and return types. You can see an example of what the function declarations should look like by running `mach webidl-example MyInterface`. This will produce two files in `dom/bindings` in your objdir: `MyInterface-example.h` and `MyInterface-example.cpp`, which show a basic implementation of the interface using a class that inherits from `nsISupports` and has a wrapper cache. See this [sample patch that migrates window.performance.\* to Web IDL bindings](https://hg.mozilla.org/mozilla-central/rev/dd08c10193c6).
Note
If your object can only be reflected into JS by creating it, not by retrieving it from somewhere, you can skip steps 1 and 2 above and instead add `'wrapperCache': False` to your descriptor. You will need to flag the functions that return your object as [`[NewObject]`](https://webidl.spec.whatwg.org/#NewObject) in the Web IDL. If your object is not refcounted then the return value of functions that return it should return a UniquePtr.
## C++ reflections of Web IDL constructs ### C++ reflections of Web IDL operations (methods) A Web IDL operation is turned into a method call on the underlying C++ object. The return type and argument types are determined [as described below](#c-reflections-of-webidl-constructs). In addition to those, all [methods that are allowed to throw](#throws-getterthrows-setterthrows) will get an `ErrorResult&` argument appended to their argument list. Non-static methods that use certain Web IDL types like `any` or `object` will get a `JSContext*` argument prepended to the argument list. Static methods will be passed a [`const GlobalObject&`](#globalobject) for the relevant global and can get a `JSContext*` by calling `Context()` on it. The name of the C++ method is simply the name of the Web IDL operation with the first letter converted to uppercase. Web IDL overloads are turned into C++ overloads: they simply call C++ methods with the same name and different signatures. For example, this Web IDL: ``` webidl interface MyInterface { undefined doSomething(long number); double doSomething(MyInterface? otherInstance); [Throws] MyInterface doSomethingElse(optional long maybeNumber); [Throws] undefined doSomethingElse(MyInterface otherInstance); undefined doTheOther(any something); undefined doYetAnotherThing(optional boolean actuallyDoIt = false); static undefined staticOperation(any arg); }; ``` will require these method declarations: ``` cpp class MyClass { void DoSomething(int32_t a number); double DoSomething(MyClass* aOtherInstance); already_AddRefed DoSomethingElse(Optional aMaybeNumber, ErrorResult& rv); void DoSomethingElse(MyClass& aOtherInstance, ErrorResult& rv); void DoTheOther(JSContext* cx, JS::Handle aSomething); void DoYetAnotherThing(bool aActuallyDoIt); static void StaticOperation(const GlobalObject& aGlobal, JS::Handle aSomething); } ``` ### C++ reflections of Web IDL attributes A Web IDL attribute is turned into a pair of method calls for the getter and setter on the underlying C++ object. A readonly attribute only has a getter and no setter. The getter's name is the name of the attribute with the first letter converted to uppercase. This has `Get` prepended to it if any of these conditions hold: 1. The type of the attribute is nullable. 1. The getter can throw. 1. The return value of the attribute is returned via an out parameter in the C++. The method signature for the getter looks just like an operation with no arguments and the attribute's type as the return type. The setter's name is `Set` followed by the name of the attribute with the first letter converted to uppercase. The method signature looks just like an operation with an undefined return value and a single argument whose type is the attribute's type. ### C++ reflections of Web IDL constructors A Web IDL constructor is turned into a static class method named `Constructor`. The arguments of this method will be the arguments of the Web IDL constructor, with a [`const GlobalObject&`](#globalobject) for the relevant global prepended. For the non-worker case, the global is typically the inner window for the DOM Window the constructor function is attached to. If a `JSContext*` is also needed due to some of the argument types, it will come after the global. The return value of the constructor for `MyInterface` is exactly the same as that of a method returning an instance of `MyInterface`. Constructors are always allowed to throw. For example, this IDL: ``` webidl interface MyInterface { constructor(); constructor(unsigned long someNumber); }; ``` will require the following declarations in `MyClass`: ``` cpp class MyClass { // Various nsISupports stuff or whatnot static already_AddRefed Constructor(const GlobalObject& aGlobal, ErrorResult& rv); static already_AddRefed Constructor(const GlobalObject& aGlobal, uint32_t aSomeNumber, ErrorResult& rv); }; ``` ### C++ reflections of Web IDL types The exact C++ representation for Web IDL types can depend on the precise way that they're being used (e.g., return values, arguments, and sequence or dictionary members might all have different representations). Unless stated otherwise, a type only has one representation. Also, unless stated otherwise, nullable types are represented by wrapping [`Nullable<>`](#nullable-t) around the base type. In all cases, optional arguments which do not have a default value are represented by wrapping [`const Optional<>&`](#optional-t) around the representation of the argument type. If the argument type is a C++ reference, it will also become a [`NonNull<>`](#nonnull-t) around the actual type of the object in the process. Optional arguments which do have a default value are just represented by the argument type itself, set to the default value if the argument was not in fact passed in. Variadic Web IDL arguments are treated as a [`const Sequence<>&`](#sequence-t) around the actual argument type. Here's a table, see the specific sections below for more details and explanations. | Web IDL Type | Argument Type | Return Type | Dictionary/Member Type | | -------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | any | `JS::Handle` | `JS::MutableHandle` | `JS::Value` | | boolean | `bool` | `bool` | `bool` | | byte | `int8_t` | `int8_t` | `int8_t` | | ByteString | `const nsACString&` | `nsCString&` _(outparam)_
`nsACString&` _(outparam)_ | `nsCString` | | Date | | | `mozilla::dom::Date` | | DOMString | `const nsAString&` | [`mozilla::dom::DOMString&`](#domstring-c) _(outparam)_
`nsAString&` _(outparam)_
`nsString&` _(outparam)_ | `nsString` | | UTF8String | `const nsACString&` _(outparam)_ | `nsACString&` | `nsCString` | | double | `double` | `double` | `double` | | float | `float` | `float` | `float` | | interface:
non-nullable | `Foo&` | `already_addRefed` | [`OwningNonNull`](#owningnonnull-t) | | interface:
nullable | `Foo*` | `already_addRefed`
`Foo*` | `RefPtr` | | long | `int32_t` | `int32_t` | `int32_t` | | long long | `int64_t` | `int64_t` | `int64_t` | | object | `JS::Handle` | `JS::MutableHandle` | `JSObject*` | | octet | `uint8_t` | `uint8_t` | `uint8_t` | | sequence | [`const Sequence&`](#sequence-t) | `nsTArray&` _(outparam)_ | | | short | `int16_t` | `int16_t` | `int16_t` | | unrestricted double | `double` | `double` | `double` | | unrestricted float | `float` | `float` | `float` | | unsigned long | `uint32_t` | `uint32_t` | `uint32_t` | | unsigned long long | `uint64_t` | `uint64_t` | `uint64_t` | | unsigned short | `uint16_t` | `uint16_t` | `uint16_t` | | USVString | `const nsAString&` | [`mozilla::dom::DOMString&`](#domstring-c) _(outparam)_
`nsAString&` _(outparam)_
`nsString&` _(outparam)_ | `nsString` | #### `any` `any` is represented in three different ways, depending on use: - `any` arguments become `JS::Handle`. They will be in the compartment of the passed-in JSContext. - `any` return values become a `JS::MutableHandle` out param appended to the argument list. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. The return value is allowed to be in any compartment; bindings will wrap it into the context compartment as needed. - `any` dictionary members and sequence elements become `JS::Value`. The dictionary members and sequence elements are guaranteed to be marked by whomever puts the sequence or dictionary on the stack, using `SequenceRooter` and `DictionaryRooter`. Methods using `any` always get a `JSContext*` argument. For example, this Web IDL: ``` webidl interface Test { attribute any myAttr; any myMethod(any arg1, sequence arg2, optional any arg3); }; ``` will correspond to these C++ function declarations: ``` cpp void MyAttr(JSContext* cx, JS::MutableHandle retval); void SetMyAttr(JSContext* cx, JS::Handle value); void MyMethod(JSContext* cx, JS::Handle arg1, const Sequence& arg2, const Optional>& arg3, JS::MutableHandle retval); ``` #### `boolean` The `boolean` Web IDL type is represented as a C++ `bool`. For example, this Web IDL: ``` webidl interface Test { attribute boolean myAttr; boolean myMethod(optional boolean arg); }; ``` will correspond to these C++ function declarations: ``` cpp bool MyAttr(); void SetMyAttr(bool value); bool MyMethod(const Optional& arg); ``` #### Integer types Integer Web IDL types are mapped to the corresponding C99 stdint types. For example, this Web IDL: ``` webidl interface Test { attribute short myAttr; long long myMethod(unsigned long? arg); }; ``` will correspond to these C++ function declarations: ``` cpp int16_t MyAttr(); void SetMyAttr(int16_t value); int64_t MyMethod(const Nullable& arg); ``` #### Floating point types Floating point Web IDL types are mapped to the C++ type of the same name. So `float` and `unrestricted float` become a C++ `float`, while `double` and `unrestricted double` become a C++ `double`. For example, this Web IDL: ``` webidl interface Test { float myAttr; double myMethod(unrestricted double? arg); }; ``` will correspond to these C++ function declarations: ``` cpp float MyAttr(); void SetMyAttr(float value); double MyMethod(const Nullable& arg); ``` #### `DOMString` Strings are reflected in three different ways, depending on use: - String arguments become `const nsAString&`. - String return values become a [`mozilla::dom::DOMString&`](#domstring-c) out param appended to the argument list. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. Note that this allows callees to declare their methods as taking an `nsAString&` or `nsString&` if desired. - Strings in sequences, dictionaries, owning unions, and variadic arguments become `nsString`. Nullable strings are represented by the same types as non-nullable ones, but the string will return true for `DOMStringIsNull()`. Returning null as a string value can be done using `SetDOMStringToNull` on the out param if it's an `nsAString` or calling `SetNull()` on a `DOMString`. For example, this Web IDL: ``` webidl interface Test { DOMString myAttr; [Throws] DOMString myMethod(sequence arg1, DOMString? arg2, optional DOMString arg3); }; ``` will correspond to these C++ function declarations: ``` cpp void GetMyAttr(nsString& retval); void SetMyAttr(const nsAString& value); void MyMethod(const Sequence& arg1, const nsAString& arg2, const Optional& arg3, nsString& retval, ErrorResult& rv); ``` #### `USVString` `USVString` is reflected just like `DOMString`. #### `UTF8String` `UTF8String` is a string with guaranteed-valid UTF-8 contents. It is not a standard in the Web IDL spec, but its observables are the same as those of `USVString`. It is a good fit for when the specification allows a `USVString`, but you want to process the string as UTF-8 rather than UTF-16. It is reflected in three different ways, depending on use: - Arguments become `const nsACString&`. - Return values become an `nsACString&` out param appended to the argument list. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. - In sequences, dictionaries owning unions, and variadic arguments it becomes `nsCString`. Nullable `UTF8String`s are represented by the same types as non-nullable ones, but the string will return true for `IsVoid()`. Returning null as a string value can be done using `SetIsVoid()` on the out param. #### `ByteString` `ByteString` is reflected in three different ways, depending on use: - `ByteString` arguments become `const nsACString&`. - `ByteString` return values become an `nsCString&` out param appended to the argument list. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. - `ByteString` in sequences, dictionaries, owning unions, and variadic arguments becomes `nsCString`. Nullable `ByteString` are represented by the same types as non-nullable ones, but the string will return true for `IsVoid()`. Returning null as a string value can be done using `SetIsVoid()` on the out param. #### `object` `object` is represented in three different ways, depending on use: - `object` arguments become `JS::Handle`. They will be in the compartment of the passed-in JSContext. - `object` return values become a `JS::MutableHandle` out param appended to the argument list. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. The return value is allowed to be in any compartment; bindings will wrap it into the context compartment as needed. - `object` dictionary members and sequence elements become `JSObject*`. The dictionary members and sequence elements are guaranteed to be marked by whoever puts the sequence or dictionary on the stack, using `SequenceRooter` and `DictionaryRooter`. Methods using `object` always get a `JSContext*` argument. For example, this Web IDL: ``` webidl interface Test { object myAttr; object myMethod(object arg1, object? arg2, sequence arg3, optional object arg4, optional object? arg5); }; ``` will correspond to these C++ function declarations: ``` cpp void GetMyAttr(JSContext* cx, JS::MutableHandle retval); void SetMyAttr(JSContext* cx, JS::Handle value); void MyMethod(JSContext* cx, JS::Handle arg1, JS::Handle arg2, const Sequence& arg3, const Optional>& arg4, const Optional>& arg5, JS::MutableHandle retval); ``` #### Interface types There are four kinds of interface types in the Web IDL bindings. Callback interfaces are used to represent script objects that browser code can call into. External interfaces are used to represent objects that have not been converted to the Web IDL bindings yet. Web IDL interfaces are used to represent Web IDL binding objects. "SpiderMonkey" interfaces are used to represent objects that are implemented natively by the JavaScript engine (e.g., typed arrays). ##### Callback interfaces Callback interfaces are represented in C++ as objects inheriting from [`mozilla::dom::CallbackInterface`](#callbackinterface), whose name, in the `mozilla::dom` namespace, matches the name of the callback interface in the Web IDL. The exact representation depends on how the type is being used. - Nullable arguments become `Foo*`. - Non-nullable arguments become `Foo&`. - Return values become `already_AddRefed` or `Foo*` as desired. The pointer form is preferred because it results in faster code, but it should only be used if the return value was not addrefed (and so it can only be used if the return value is kept alive by the callee until at least the binding method has returned). - Web IDL callback interfaces in sequences, dictionaries, owning unions, and variadic arguments are represented by `RefPtr` if nullable and [`OwningNonNull`](#owningnonnull-t) otherwise. If the interface is a single-operation interface, the object exposes two methods that both invoke the same underlying JS callable. The first of these methods allows the caller to pass in a `this` object, while the second defaults to `undefined` as the `this` value. In either case, the `this` value is only used if the callback interface is implemented by a JS callable. If it's implemented by an object with a property whose name matches the operation, the object itself is always used as `this`. If the interface is not a single-operation interface, it just exposes a single method for every IDL method/getter/setter. The signatures of the methods correspond to the signatures for throwing IDL methods/getters/setters with an additional trailing `mozilla::dom::CallbackObject::ExceptionHandling aExceptionHandling` argument, defaulting to `eReportExceptions`. If `aReportExceptions` is set to `eReportExceptions`, the methods will report JS exceptions before returning. If `aReportExceptions` is set to `eRethrowExceptions`, JS exceptions will be stashed in the `ErrorResult` and will be reported when the stack unwinds to wherever the `ErrorResult` was set up. For example, this Web IDL: ``` webidl callback interface MyCallback { attribute long someNumber; short someMethod(DOMString someString); }; callback interface MyOtherCallback { // single-operation interface short doSomething(Node someNode); }; interface MyInterface { attribute MyCallback foo; attribute MyCallback? bar; }; ``` will lead to these C++ class declarations in the `mozilla::dom` namespace: ``` cpp class MyCallback : public CallbackInterface { int32_t GetSomeNumber(ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); void SetSomeNumber(int32_t arg, ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); int16_t SomeMethod(const nsAString& someString, ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); }; class MyOtherCallback : public CallbackInterface { public: int16_t DoSomething(nsINode& someNode, ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); template int16_t DoSomething(const T& thisObj, nsINode& someNode, ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); }; ``` and these C++ function declarations on the implementation of `MyInterface`: ``` cpp already_AddRefed GetFoo(); void SetFoo(MyCallback&); already_AddRefed GetBar(); void SetBar(MyCallback*); ``` A consumer of MyCallback would be able to use it like this: ``` cpp void SomeClass::DoSomethingWithCallback(MyCallback& aCallback) { ErrorResult rv; int32_t number = aCallback.GetSomeNumber(rv); if (rv.Failed()) { // The error has already been reported to the JS console; you can handle // things however you want here. return; } // For some reason we want to catch and rethrow exceptions from SetSomeNumber, say. aCallback.SetSomeNumber(2*number, rv, eRethrowExceptions); if (rv.Failed()) { // The exception is now stored on rv. This code MUST report // it usefully; otherwise it will assert. } } ``` ##### External interfaces External interfaces are represented in C++ as objects that XPConnect knows how to unwrap to. This can mean XPCOM interfaces (whether declared in XPIDL or not) or it can mean some type that there's a castable native unwrapping function for. The C++ type to be used should be the `nativeType` listed for the external interface in the [`Bindings.conf`](#bindings-conf-details) file. The exact representation depends on how the type is being used. - Arguments become `nsIFoo*`. - Return values can be `already_AddRefed` or `nsIFoo*` as desired. The pointer form is preferred because it results in faster code, but it should only be used if the return value was not addrefed (and so it can only be used if the return value is kept alive by the callee until at least the binding method has returned). - External interfaces in sequences, dictionaries, owning unions, and variadic arguments are represented by `RefPtr`. ##### Web IDL interfaces Web IDL interfaces are represented in C++ as C++ classes. The class involved must either be refcounted or must be explicitly annotated in `Bindings.conf` as being directly owned by the JS object. If the class inherits from `nsISupports`, then the canonical `nsISupports` must be on the primary inheritance chain of the object. If the interface has a parent interface, the C++ class corresponding to the parent must be on the primary inheritance chain of the object. This guarantees that a `void*` can be stored in the JSObject which can then be `reinterpret_cast` to any of the classes that correspond to interfaces the object implements. The C++ type to be used should be the `nativeType` listed for the interface in the [`Bindings.conf`](#bindings-conf-details) file, or `mozilla::dom::InterfaceName` if none is listed. The exact representation depends on how the type is being used. - Nullable arguments become `Foo*`. - Non-nullable arguments become `Foo&`. - Return values become `already_AddRefed` or `Foo*` as desired. The pointer form is preferred because it results in faster code, but it should only be used if the return value was not addrefed (and so it can only be used if the return value is kept alive by the callee until at least the binding method has returned). - Web IDL interfaces in sequences, dictionaries, owning unions, and variadic arguments are represented by `RefPtr` if nullable and [`OwningNonNull`](#owningnonnull-t) otherwise. For example, this Web IDL: ``` webidl interface MyInterface { attribute MyInterface myAttr; undefined passNullable(MyInterface? arg); MyInterface? doSomething(sequence arg); MyInterface doTheOther(sequence arg); readonly attribute MyInterface? nullableAttr; readonly attribute MyInterface someOtherAttr; readonly attribute MyInterface someYetOtherAttr; }; ``` Would correspond to these C++ function declarations: ``` cpp already_AddRefed MyAttr(); void SetMyAttr(MyClass& value); void PassNullable(MyClass* arg); already_AddRefed doSomething(const Sequence>& arg); already_AddRefed doTheOther(const Sequence>& arg); already_Addrefed GetNullableAttr(); MyClass* SomeOtherAttr(); MyClass* SomeYetOtherAttr(); // Don't have to return already_AddRefed! ``` ##### "SpiderMonkey" interfaces Typed array, array buffer, and array buffer view arguments are represented by the objects in [`TypedArray.h`](#typed-arrays-arraybuffers-array-buffer-views). For example, this Web IDL: ``` webidl interface Test { undefined passTypedArrayBuffer(ArrayBuffer arg); undefined passTypedArray(ArrayBufferView arg); undefined passInt16Array(Int16Array? arg); } ``` will correspond to these C++ function declarations: ``` cpp void PassTypedArrayBuffer(const ArrayBuffer& arg); void PassTypedArray(const ArrayBufferView& arg); void PassInt16Array(const Nullable& arg); ``` Typed array return values become a `JS::MutableHandle` out param appended to the argument list. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. The return value is allowed to be in any compartment; bindings will wrap it into the context compartment as needed. Typed arrays store a `JSObject*` and hence need to be rooted properly. On-stack typed arrays can be declared as `RootedTypedArray` (e.g. `RootedTypedArray`). Typed arrays on the heap need to be traced. #### Dictionary types A dictionary argument is represented by a const reference to a struct whose name is the dictionary name in the `mozilla::dom` namespace. The struct has one member for each of the dictionary's members with the same name except the first letter uppercased and prefixed with "m". The members that are required or have default values have types as described under the corresponding Web IDL type in this document. The members that are not required and don't have default values have those types wrapped in [`Optional<>`](#optional-t). Dictionary return values are represented by an out parameter whose type is a non-const reference to the struct described above, with all the members that have default values preinitialized to those default values. Note that optional dictionary arguments are always forced to have a default value of an empty dictionary by the IDL parser and code generator, so dictionary arguments are never wrapped in `Optional<>`. If necessary, dictionaries can be directly initialized from a `JS::Value` in C++ code by invoking their `Init()` method. Consumers doing this should declare their dictionary as `RootedDictionary`. When this is done, passing in a null `JSContext*` is allowed if the passed-in `JS::Value` is `JS::NullValue()`. Likewise, a dictionary struct can be converted to a `JS::Value` in C++ by calling `ToJSValue` with the dictionary as the second argument. If `Init()` or `ToJSValue()` returns false, they will generally set a pending exception on the JSContext; reporting those is the responsibility of the caller. For example, this Web IDL: ``` text dictionary Dict { long foo = 5; DOMString bar; }; interface Test { undefined initSomething(optional Dict arg = {}); }; ``` will correspond to this C++ function declaration: ``` cpp void InitSomething(const Dict& arg); ``` and the `Dict` struct will look like this: ``` cpp struct Dict { bool Init(JSContext* aCx, JS::Handle aVal, const char* aSourceDescription = "value"); Optional mBar; int32_t mFoo; } ``` Note that the dictionary members are sorted in the struct in alphabetical order. ##### API for working with dictionaries There are a few useful methods found on dictionaries and dictionary members that you can use to quickly determine useful things. - **member.WasPassed()** - as the name suggests, was a particular member passed? (e.g., `if (arg.foo.WasPassed() { /* do nice things!*/ }`) - **dictionary.IsAnyMemberPresent()** - great for checking if you need to do anything. (e.g., `if (!arg.IsAnyMemberPresent()) return; // nothing to do`) - **member.Value()** - getting the actual data/value of a member that was passed. (e.g., `mBar.Assign(args.mBar.value())`) Example implementation using all of the above: ``` cpp void MyInterface::InitSomething(const Dict& aArg){ if (!aArg.IsAnyMemberPresent()) { return; // nothing to do! } if (aArg.mBar.WasPassed() && !mBar.Equals(aArg.mBar.value())) { mBar.Assign(aArg.mBar.Value()); } } ``` #### Enumeration types Web IDL enumeration types are represented as C++ enum classes. The values of the C++ enum are named by taking the strings in the Web IDL enumeration, replacing all non-alphanumerics with underscores, and uppercasing the first letter, with a special case for the empty string, which becomes the value `_empty`. For a Web IDL enum named `MyEnum`, the C++ enum is named `MyEnum` and placed in the `mozilla::dom` namespace, while the values are placed in the `mozilla::dom::MyEnum` namespace. The type of the enum class is automatically selected to be the smallest unsigned integer type that can hold all the values. In practice, this is always uint8_t, because Web IDL enums tend to not have more than 255 values. For example, this Web IDL: ``` webidl enum MyEnum { "something", "something-else", "", "another" }; ``` would lead to this C++ enum declaration: ``` cpp enum class MyEnum : uint8_t { Something, Something_else, _empty, Another }; ``` `mozilla::dom::GetEnumString` is a templated helper function declared in [`BindingUtils.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingUtils.h) and exported to `mozilla/dom/BindingUtils.h` that can be used to convert an enum value to its corresponding string value. It returns a `const nsCString&` containing the string value. `mozilla::dom::StringToEnum` is a templated helper function in [`BindingUtils.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingUtils.h) and exported to `mozilla/dom/BindingUtils.h` that can be used to convert a string to the corresponding enum value. It needs to be supplied with the enum class as a template argument, and returns a `mozilla::Maybe`. If the string value passed to it as an argument is not one of the string values for the enum then it returns `mozilla::Nothing()`, else it returns the right enum value in the `mozilla::Maybe`. `mozilla::dom::WebIDLEnumSerializer` is a templated alias in [`BindingIPCUtils.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingIPCUtils.h) exported to `mozilla/dom/BindingIPCUtils.h` to implement an IPC serializer with the right validation for WebIDL enums. It uses a `mozilla::MaxContinuousEnumValue` that is generated for every WebIDL enum to implement the validation. `mozilla::dom::MakeWebIDLEnumeratedRange` is a templated helper function in [`BindingUtils.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingUtils.h) and exported to `mozilla/dom/BindingUtils.h` that can be used to create a `mozilla::EnumeratedRange` for a WebIDL enum. #### Callback function types Callback functions are represented as an object, inheriting from [`mozilla::dom::CallbackFunction`](#callbackfunction), whose name, in the `mozilla::dom` namespace, matches the name of the callback function in the Web IDL. If the type is nullable, a pointer is passed in; otherwise a reference is passed in. The object exposes two `Call` methods, which both invoke the underlying JS callable. The first `Call` method has the same signature as a throwing method declared just like the callback function, with an additional trailing `mozilla::dom::CallbackObject::ExceptionHandling aExceptionHandling` argument, defaulting to `eReportExceptions`, and calling it will invoke the callable with `undefined` as the `this` value. The second `Call` method allows passing in an explicit `this` value as the first argument. This second call method is a template on the type of the first argument, so the `this` value can be passed in in whatever form is most convenient, as long as it's either a type that can be wrapped by XPConnect or a Web IDL interface type. If `aReportExceptions` is set to `eReportExceptions`, the `Call` methods will report JS exceptions before returning. If `aReportExceptions` is set to `eRethrowExceptions`, JS exceptions will be stashed in the `ErrorResult` and will be reported when the stack unwinds to wherever the `ErrorResult` was set up. For example, this Web IDL: ``` webidl callback MyCallback = long (MyInterface arg1, boolean arg2); interface MyInterface { attribute MyCallback foo; attribute MyCallback? bar; }; ``` will lead to this C++ class declaration, in the `mozilla::dom` namespace: ``` cpp class MyCallback : public CallbackFunction { public: int32_t Call(MyInterface& arg1, bool arg2, ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); template int32_t Call(const T& thisObj, MyInterface& arg1, bool arg2, ErrorResult& rv, ExceptionHandling aExceptionHandling = eReportExceptions); }; ``` and these C++ function declarations in the `MyInterface` class: ``` cpp already_AddRefed GetFoo(); void SetFoo(MyCallback&); already_AddRefed GetBar(); void SetBar(MyCallback*); ``` A consumer of MyCallback would be able to use it like this: ``` cpp void SomeClass::DoSomethingWithCallback(MyCallback& aCallback, MyInterface& aInterfaceInstance) { ErrorResult rv; int32_t number = aCallback.Call(aInterfaceInstance, false, rv); if (rv.Failed()) { // The error has already been reported to the JS console; you can handle // things however you want here. return; } // Now for some reason we want to catch and rethrow exceptions from the callback, // and use "this" as the this value for the call to JS. number = aCallback.Call(*this, true, rv, eRethrowExceptions); if (rv.Failed()) { // The exception is now stored on rv. This code MUST report // it usefully; otherwise it will assert. } } ``` #### Sequences Sequence arguments are represented by [`const Sequence&`](#sequence-t), where `T` depends on the type of elements in the Web IDL sequence. Sequence return values are represented by an `nsTArray` out param appended to the argument list, where `T` is the return type for the elements of the Web IDL sequence. This comes after all IDL arguments, but before the `ErrorResult&`, if any, for the method. #### Arrays IDL array objects are not supported yet. The spec on these is likely to change drastically anyway. #### Union types Union types are reflected as a struct in the `mozilla::dom` namespace. There are two kinds of union structs: one kind does not keep its members alive (is "non-owning"), and the other does (is "owning"). Const references to non-owning unions are used for plain arguments. Owning unions are used in dictionaries, sequences, and for variadic arguments. Union return values become a non-const owning union out param. The name of the struct is the concatenation of the names of the types in the union, with "Or" inserted between them, and for an owning struct "Owning" prepended. So for example, this IDL: ``` text undefined passUnion((object or long) arg); (object or long) receiveUnion(); undefined passSequenceOfUnions(sequence<(object or long)> arg); undefined passOtherUnion((HTMLDivElement or ArrayBuffer or EventInit) arg); ``` would correspond to these C++ function declarations: ``` cpp void PassUnion(const ObjectOrLong& aArg); void ReceiveUnion(OwningObjectObjectOrLong& aArg); void PassSequenceOfUnions(const Sequence& aArg); void PassOtherUnion(const HTMLDivElementOrArrayBufferOrEventInit& aArg); ``` Union structs expose accessors to test whether they're of a given type and to get hold of the data of that type. They also expose setters that set the union as being of a particular type and return a reference to the union's internal storage where that type could be stored. The one exception is the `object` type, which uses a somewhat different form of setter where the `JSObject*` is passed in directly. For example, `ObjectOrLong` would have the following methods: ``` cpp bool IsObject() const; JSObject* GetAsObject() const; void SetToObject(JSContext*, JSObject*); bool IsLong() const; int32_t GetAsLong() const; int32_t& SetAsLong() ``` Owning unions used on the stack should be declared as a `RootedUnion`, for example, `RootedUnion`. #### `Date` Web IDL `Date` types are represented by a `mozilla::dom::Date` struct. ### C++ reflections of Web IDL declarations Web IDL declarations (maplike/setlike/iterable) are turned into a set of properties and functions on the interface they are declared on. Each has a different set of helper functions it comes with. In addition, for iterable, there are requirements for C++ function implementation by the interface developer. #### Maplike Example Interface: ``` webidl interface StringToLongMap { maplike; }; ``` The bindings for this interface will generate the storage structure for the map, as well as helper functions for accessing that structure from C++. The generated C++ API will look as follows: ``` cpp namespace StringToLongMapBinding { namespace MaplikeHelpers { void Clear(mozilla::dom::StringToLongMap* self, ErrorResult& aRv); bool Delete(mozilla::dom::StringToLongMap* self, const nsAString& aKey, ErrorResult& aRv); bool Has(mozilla::dom::StringToLongMap* self, const nsAString& aKey, ErrorResult& aRv); void Set(mozilla::dom::StringToLongMap* self, const nsAString& aKey, int32_t aValue, ErrorResult& aRv); } // namespace MaplikeHelpers } // namespace StringToLongMapBindings ``` #### Setlike Example Interface: ``` webidl interface StringSet { setlike; }; ``` The bindings for this interface will generate the storage structure for the set, as well as helper functions for accessing that structure from c++. The generated C++ API will look as follows: ``` cpp namespace StringSetBinding { namespace SetlikeHelpers { void Clear(mozilla::dom::StringSet* self, ErrorResult& aRv); bool Delete(mozilla::dom::StringSet* self, const nsAString& aKey, ErrorResult& aRv); bool Has(mozilla::dom::StringSet* self, const nsAString& aKey, ErrorResult& aRv); void Add(mozilla::dom::StringSet* self, const nsAString& aKey, ErrorResult& aRv); } // namespace SetlikeHelpers } ``` #### Iterable Unlike maplike and setlike, iterable does not have any C++ helpers, as the structure backing the iterable data for the interface is left up to the developer. With that in mind, the generated iterable bindings expect the wrapper object to provide certain methods for the interface to access. Iterable interfaces have different requirements, based on if they are single or pair value iterators. Example Interface for a single value iterator: ``` webidl interface LongIterable { iterable; getter long(unsigned long index); readonly attribute unsigned long length; }; ``` For single value iterator interfaces, we treat the interface as an [indexed getter](#indexed-getters), as required by the spec. See the [indexed getter implementation section](#indexed-getters) for more information on building this kind of structure. Example Interface for a pair value iterator: ``` webidl interface StringAndLongIterable { iterable; }; ``` The bindings for this pair value iterator interface require the following methods be implemented in the C++ object: ``` cpp class StringAndLongIterable { public: // Returns the number of items in the iterable storage size_t GetIterableLength(); // Returns key of pair at aIndex in iterable storage nsAString& GetKeyAtIndex(uint32_t aIndex); // Returns value of pair at aIndex in iterable storage uint32_t& GetValueAtIndex(uint32_t aIndex); } ``` ### Stringifiers Named stringifiers operations in Web IDL will just invoke the corresponding C++ method. Anonymous stringifiers in Web IDL will invoke the C++ method called `Stringify`. So, for example, given this IDL: ``` webidl interface FirstInterface { stringifier; }; interface SecondInterface { stringifier DOMString getStringRepresentation(); }; ``` the corresponding C++ would be: ``` cpp class FirstInterface { public: void Stringify(nsAString& aResult); }; class SecondInterface { public: void GetStringRepresentation(nsAString& aResult); }; ``` ### Legacy Callers Only anonymous legacy callers are supported, and will invoke the C++ method called `LegacyCall`. This will be passed the JS "this" value as the first argument, then the arguments to the actual operation. A `JSContext` will be passed if any of the operation arguments need it. So for example, given this IDL: ``` webidl interface InterfaceWithCall { legacycaller long (float arg); }; ``` the corresponding C++ would be: ``` cpp class InterfaceWithCall { public: int32_t LegacyCall(JS::Handle aThisVal, float aArgument); }; ``` ### Named getters If the interface has a named getter, the binding will expect several methods on the C++ implementation: - A `NamedGetter` method. This takes a property name and returns whatever type the named getter is declared to return. It also has a boolean out param for whether a property with that name should exist at all. - A `NameIsEnumerable` method. This takes a property name and returns a boolean that indicates whether the property is enumerable. - A `GetSupportedNames` method. This takes an unsigned integer which corresponds to the flags passed to the `iterate` proxy trap and returns a list of property names. For implementations of this method, the important flags is `JSITER_HIDDEN`. If that flag is set, the call needs to return all supported property names. If it's not set, the call needs to return only the enumerable ones. The `NameIsEnumerable` and `GetSupportedNames` methods need to agree on which names are and are not enumerable. The `NamedGetter` and `GetSupportedNames` methods need to agree on which names are supported. So for example, given this IDL: ``` webidl interface InterfaceWithNamedGetter { getter long(DOMString arg); }; ``` the corresponding C++ would be: ``` cpp class InterfaceWithNamedGetter { public: int32_t NamedGetter(const nsAString& aName, bool& aFound); bool NameIsEnumerable(const nsAString& aName); undefined GetSupportedNames(unsigned aFlags, nsTArray& aNames); }; ``` ### Indexed getters If the interface has a indexed getter, the binding will expect the following methods on the C++ implementation: - A `IndexedGetter` method. This takes an integer index value and returns whatever type the indexed getter is declared to return. It also has a boolean out param for whether a property with that index should exist at all. The implementation must set this out param correctly. The return value is guaranteed to be ignored if the out param is set to false. So for example, given this IDL: ``` webidl interface InterfaceWithIndexedGetter { getter long(unsigned long index); readonly attribute unsigned long length; }; ``` the corresponding C++ would be: ``` cpp class InterfaceWithIndexedGetter { public: uint32_t Length() const; int32_t IndexedGetter(uint32_t aIndex, bool& aFound) const; }; ``` ## Throwing exceptions from Web IDL methods, getters, and setters Web IDL methods, getters, and setters that are [explicitly marked as allowed to throw](#throws-getterthrows-setterthrows) have an `ErrorResult&` argument as their last argument. To throw an exception, simply call `Throw()` on the `ErrorResult&` and return from your C++ back into the binding code. In cases when the specification calls for throwing a `TypeError`, you should use `ErrorResult::ThrowTypeError()` instead of calling `Throw()`. ## Custom extended attributes Our Web IDL parser and code generator recognize several extended attributes that are not present in the Web IDL spec. ### `[AllowLarge]` Can be specified on buffer source types (`ArrayBuffer`, `ArrayBufferView`, typed arrays) to skip the default 2 GB size check. This allows incremental migration of consumers to support buffers larger than 2 GB. Can be combined with `[AllowShared]`. On the C++ side, use `ProcessData(...)` or `ProcessFixedData(...)` to access the data. ### `[Alias=propName]` This extended attribute can be specified on a method and indicates that another property with the specified name will also appear on the interface prototype object and will have the same Function object value as the property for the method. For example: ``` webidl interface MyInterface { [Alias=performSomething] undefined doSomething(); }; ``` `MyInterface.prototype.performSomething` will have the same Function object value as `MyInterface.prototype.doSomething`. Multiple `[Alias]` extended attribute can be used on the one method. `[Alias]` cannot be used on a static method, nor on methods on a global interface (such as `Window`). Aside from regular property names, the name of an alias can be [Symbol.iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator). This is specified by writing `[Alias="@@iterator"]`. ### `[BindingAlias=propName]` This extended attribute can be specified on an attribute and indicates that another property with the specified name will also appear on the interface prototype object and will call the same underlying C++ implementation for the getter and setter. This is more efficient than using the same `BinaryName` for both attributes, because it shares the binding glue code between them. The properties still have separate getter/setter functions in JavaScript, so from the point of view of web consumers it's as if you actually had two separate attribute declarations on your interface. For example: ``` webidl interface MyInterface { [BindingAlias=otherAttr] readonly attribute boolean attr; }; ``` `MyInterface.prototype.otherAttr` and `MyInterface.prototype.attr` will both exist, have separate getter/setter functions, but call the same binding glue code and implementation function on the objects implementing `MyInterface`. Multiple `[BindingAlias]` extended attributes can be used on a single attribute. ### `[BindingTemplate=(name, type, value)]` This extended attribute can be specified on an attribute, and causes the getter and setter for this attribute to forward to a common generated implementation, shared with all other attributes that have a `[BindingTemplate]` with the same value for the `name` argument. The `TemplatedAttributes` dictionary in Bindings.conf needs to contain a definition for the template with the name `name`. The argument `type::value` will be passed when calling the common generated implementation. This is aimed at very specialized use cases where an interface has a large number of attributes that all have the same type, and for which we have a native implementation that's common to all these attributes, and typically uses some id based on the attribute's name in the implementation. All the attributes that use the same template need to mostly have the same extended attributes, except form a small number that are allowed to differ (`[BindingTemplate]`, `[BindingAlias]`, `[Pure]`, [`Pref`] and [`Func`], and the annotations for whether the getter and setter throws exceptions). ### `[ChromeOnly]` This extended attribute can be specified on any method, attribute, or constant on an interface or on an interface as a whole. It can also be specified on dictionary members. Interface members flagged as `[ChromeOnly]` are only exposed in chrome Windows (and in particular, are not exposed to webpages). From the point of view of web content, it's as if the interface member were not there at all. These members _are_ exposed to chrome script working with a content object via Xrays. If specified on an interface as a whole, this functions like [`[Func]`](#func-funcname) except that the binding code will automatically check whether the caller script has the system principal (is chrome or a worker started from a chrome page) instead of calling into the C++ implementation to determine whether to expose the interface object on the global. This means that accessing a content global via Xrays will show `[ChromeOnly]` interface objects on it. If specified on a dictionary member, then the dictionary member will only appear to exist in system-privileged code. This extended attribute can be specified together with `[Func]`, and `[Pref]`. If more than one of these is specified, all conditions will need to test true for the interface or interface member to be exposed. ### `[Pref=prefname]` This extended attribute can be specified on any method, attribute, or constant on an interface or on an interface as a whole. It can also be specified on dictionary members. It takes a value, which must be the name of a boolean preference exposed from `StaticPrefs`. The `StaticPrefs` function that will be called is calculated from the value of the extended attribute, with dots replaced by underscores (`StaticPrefs::my_pref_name()` in the example below). If specified on an interface member, the interface member involved is only exposed if the preference is set to `true`. An example of how this can be used: ``` webidl interface MyInterface { attribute long alwaysHere; [Pref="my.pref.name"] attribute long onlyHereIfEnabled; }; ``` If specified on an interface as a whole, this functions like [`[Func]`](#func-funcname) except that the binding will check the value of the preference directly without calling into the C++ implementation of the interface at all. This is useful when the enable check is simple and it's desirable to keep the prefname with the Web IDL declaration. If specified on a dictionary member, the web-observable behavior when the pref is set to false will be as if the dictionary did not have a member of that name defined. That means that on the JS side no observable get of the property will happen. On the C++ side, the behavior would be as if the passed-in object did not have a property with the relevant name: the dictionary member would either be `!Passed()` or have the default value if there is a default value. > An example of how this can be used: ``` webidl [Pref="my.pref.name"] interface MyConditionalInterface { }; ``` This extended attribute can be specified together with `[ChromeOnly]`, and `[Func]`. If more than one of these is specified, all conditions will need to test true for the interface or interface member to be exposed. ### `[Func="funcname"]` This extended attribute can be specified on any method, attribute, or constant on an interface or on an interface as a whole. It can also be specified on dictionary members. It takes a value, which must be the name of a static function. If specified on an interface member, the interface member involved is only exposed if the specified function returns `true`. An example of how this can be used: ``` webidl interface MyInterface { attribute long alwaysHere; [Func="MyClass::StuffEnabled"] attribute long onlyHereIfEnabled; }; ``` The function is invoked with two arguments: the `JSContext` that the operation is happening on and the `JSObject` for the global of the object that the property will be defined on if the function returns true. In particular, in the Xray case the `JSContext` is in the caller compartment (typically chrome) but the `JSObject` is in the target compartment (typically content). This allows the method implementation to select which compartment it cares about in its checks. The above IDL would also require the following C++: ``` cpp class MyClass { static bool StuffEnabled(JSContext* cx, JSObject* obj); }; ``` If specified on an interface as a whole, then lookups for the interface object for this interface on a DOM Window will only find it if the specified function returns true. For objects that can only be created via a constructor, this allows disabling the functionality altogether and making it look like the feature is not implemented at all. If specified on a dictionary member, the web-observable behavior when the function returns false will be as if the dictionary did not have a member of that name defined. That means that on the JS side no observable get of the property will happen. On the C++ side, the behavior would be as if the passed-in object did not have a property with the relevant name: the dictionary member would either be `!Passed()` or have the default value if there is a default value. An example of how `[Func]` can be used: ``` webidl [Func="MyClass::MyConditionalInterfaceEnabled"] interface MyConditionalInterface { }; ``` In this case, the C++ function is passed a `JS::Handle`. So the C++ in this case would look like this: ``` cpp class MyClass { static bool MyConditionalInterfaceEnabled(JSContext* cx, JS::Handle obj); }; ``` Just like in the interface member case, the `JSContext` is in the caller compartment but the `JSObject` is the actual object the property would be defined on. In the Xray case that means obj is in the target compartment (typically content) and `cx` is typically chrome. This extended attribute can be specified together with `[ChromeOnly]`, and `[Pref]`. If more than one of these is specified, all conditions will need to test true for the interface or interface member to be exposed. Binding code will include the headers necessary for a `[Func]`, unless the interface is using a non-default header file. If a non-default header file is used, that header file needs to do any header inclusions necessary for `[Func]` annotations. ### `[Throws]`, `[GetterThrows]`, `[SetterThrows]` Used to flag methods or attributes as allowing the C++ callee to throw. This causes the binding generator, and in many cases the JIT, to generate extra code to handle possible exceptions. Possibly-throwing methods and attributes get an `ErrorResult&` argument. `[Throws]` applies to both methods and attributes; for attributes it means both the getter and the setter can throw. `[GetterThrows]` applies only to attributes. `[SetterThrows]` applies only to non-readonly attributes. For interfaces flagged with `[JSImplementation]`, all methods and properties are assumed to be able to throw and do not need to be flagged as throwing. ### `[DependsOn]` Used for a method or attribute to indicate what the return value depends on. Possible values are: - `Everything` This value can't actually be specified explicitly; this is the default value you get when `[DependsOn]` is not specified. This means we don't know anything about the return value's dependencies and hence can't rearrange other code that might change values around the method or attribute. - `DOMState` The return value depends on the state of the "DOM", by which we mean all objects specified via Web IDL. The return value is guaranteed to not depend on the state of the JS heap or other JS engine data structures, and is guaranteed to not change unless some function with [`[Affects=Everything]`](#affects) is executed. - `DeviceState` The return value depends on the state of the device we're running on (e.g., the system clock). The return value is guaranteed to not be affected by any code running inside Gecko itself, but we might get a new value every time the method or getter is called even if no Gecko code ran between the calls. - `Nothing` The return value is a constant that never changes. This value cannot be used on non-readonly attributes, since having a non-readonly attribute whose value never changes doesn't make sense. Values other than `Everything`, when used in combination with [`[Affects=Nothing]`](#affects), can used by the JIT to perform loop-hoisting and common subexpression elimination on the return values of IDL attributes and methods. ### `[Affects]` Used for a method or attribute getter to indicate what sorts of state can be affected when the function is called. Attribute setters are, for now, assumed to affect everything. Possible values are: - `Everything` This value can't actually be specified explicitly; this is the default value you get when `[Affects]` is not specified. This means that calling the method or getter might change any mutable state in the DOM or JS heap. - `Nothing` Calling the method or getter will have no side-effects on either the DOM or the JS heap. Methods and attribute getters with `[Affects=Nothing]` are allowed to throw exceptions, as long as they do so deterministically. In the case of methods, whether an exception is thrown is allowed to depend on the arguments, as long as calling the method with the same arguments will always either throw or not throw. The `Nothing` value, when used with `[DependsOn]` values other than `Everything`, can used by the JIT to perform loop-hoisting and common subexpression elimination on the return values of IDL attributes and methods, as well as code motion past DOM methods that might depend on system state but have no side effects. ### `[Pure]` This is an alias for `[Affects=Nothing, DependsOn=DOMState]`. Attributes/methods flagged in this way promise that they will keep returning the same value as long as nothing that has `[Affects=Everything]` executes. ### `[Constant]` This is an alias for `[Affects=Nothing, DependsOn=Nothing]`. Used to flag readonly attributes or methods that could have been annotated with `[Pure]` and also always return the same value. This should only be used when it's absolutely guaranteed that the return value of the attribute getter will always be the same from the JS engine's point of view. The spec's `[SameObject]` extended attribute is an alias for `[Constant]`, but can only be applied to things returning objects, whereas `[Constant]` can be used for any type of return value. ### `[NeedResolve]` Used to flag interfaces which have a custom resolve hook. This annotation will cause the `DoResolve` method to be called on the underlying C++ class when a property lookup happens on the object. The signature of this method is: `bool DoResolve(JSContext*, JS::Handle, JS::Handle, JS::MutableHandle)`. Here the passed-in object is the object the property lookup is happening on (which may be an Xray for the actual DOM object) and the jsid is the property name. The value that the property should have is returned in the `MutableHandle`, with `UndefinedValue()` indicating that the property does not exist. If this extended attribute is used, then the underlying C++ class must also implement a method called `GetOwnPropertyNames` with the signature `void GetOwnPropertyNames(JSContext* aCx, nsTArray& aNames, ErrorResult& aRv)`. This method will be called by the JS engine's enumerate hook and must provide a superset of all the property names that `DoResolve` might resolve. Providing names that `DoResolve` won't actually resolve is OK. ### `[HeaderFile="path/to/headerfile.h"]` Indicates where the implementation can be found. Similar to the headerFile annotation in Bindings.conf. Just like headerFile in Bindings.conf, should be avoided. ### `[JSImplementation="@mozilla.org/some-contractid;1"]` Used on an interface to provide the contractid of the [JavaScript component implementing the interface](#implementing-webidl-using-javascript). ### `[StoreInSlot]` Used to flag attributes that can be gotten very quickly from the JS object by the JIT. Such attributes will have their getter called immediately when the JS wrapper for the DOM object is created, and the returned value will be stored directly on the JS object. Later gets of the attribute will not call the C++ getter and instead use the cached value. If the value returned by the attribute needs to change, the C++ code should call the `ClearCachedFooValue` method in the namespace of the relevant binding, where `foo` is the name of the attribute. This will immediately call the C++ getter and cache the value it returns, so it needs a `JSContext` to work on. This extended attribute can only be used on attributes whose getters are [`[Pure]`](#pure) or [`[Constant]`](#constant) and which are not [`[Throws]`](#throws-getterthrows-setterthrows) or [`[GetterThrows]`](#throws-getterthrows-setterthrows). So for example, given this IDL: ``` webidl interface MyInterface { [Pure, StoreInSlot] attribute long myAttribute; }; ``` the C++ implementation of MyInterface would clear the cached value by calling `mozilla::dom::MyInterface_Binding::ClearCachedMyAttributeValue(cx, this)`. This function will return false on error and the caller is responsible for handling any JSAPI exception that is set by the failure. If the attribute is not readonly, setting it will automatically clear the cached value and reget it again before the setter returns. ### `[Cached]` Used to flag attributes that, when their getter is called, will cache the returned value on the JS object. This can be used to implement attributes whose value is a sequence or dictionary (which would otherwise end up returning a new object each time and hence not be allowed in Web IDL). Unlike [`[StoreInSlot]`](#storeinslot) this does _not_ cause the getter to be eagerly called at JS wrapper creation time; the caching is lazy. `[Cached]` attributes must be [`[Pure]`](#pure) or [`[Constant]`](#constant), because otherwise not calling the C++ getter would be observable, but are allowed to have throwing getters. Their cached value can be cleared by calling the `ClearCachedFooValue` method in the namespace of the relevant binding, where `foo` is the name of the attribute. Unlike `[StoreInSlot]` attributes, doing so will not immediately invoke the getter, so it does not need a `JSContext`. So for example, given this IDL: ``` webidl interface MyInterface { [Pure, Cached] attribute long myAttribute; }; ``` the C++ implementation of MyInterface would clear the cached value by calling `mozilla::dom::MyInterface_Binding::ClearCachedMyAttributeValue(this)`. JS-implemented Web IDL can clear the cached value by calling `this.__DOM_IMPL__._clearCachedMyAttributeValue()`. If the attribute is not readonly, setting it will automatically clear the cached value. ### `[Frozen]` Used to flag attributes that, when their getter is called, will call [`Object.freeze`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) on the return value before returning it. This extended attribute is only allowed on attributes that return sequences, dictionaries and `MozMap`, and corresponds to returning a frozen `Array` (for the sequence case) or `Object` (for the other two cases). ### `[BinaryName]` `[BinaryName]` can be specified on method or attribute to change the C++ function name that will be used for the method or attribute. It takes a single string argument, which is the name you wish the method or attribute had instead of the one it actually has. For example, given this IDL: ``` webidl interface InterfaceWithRenamedThings { [BinaryName="renamedMethod"] undefined someMethod(); [BinaryName="renamedAttribute"] attribute long someAttribute; }; ``` the corresponding C++ would be: ``` cpp class InterfaceWithRenamedThings { public: void RenamedMethod(); int32_t RenamedAttribute(); void SetRenamedAttribute(int32_t); }; ``` ### `[Deprecated="tag"]` When deprecating an interface or method, the `[Deprecated]` annotation causes the Web IDL compiler to insert code that generates deprecation warnings. This annotation can be added to interface methods or interfaces. Adding this to an interface causes a warning to be issued the first time the object is constructed, or any static method on the object is invoked. The complete list of valid deprecation tags is maintained in [nsDeprecatedOperationList.inc](https://searchfox.org/firefox-main/source/dom/base/nsDeprecatedOperationList.inc). Each new tag requires that a localized string be defined, containing the deprecation message to display. ### `[CrossOriginReadable]` Used to flag an attribute that, when read, will not have the same-origin constraint tested: it can be read from a context with a different origin. ### `[CrossOriginWrite]` Used to flag an attribute that, when written, will not have the same-origin constraint tested: it can be written from a context with a different origin. ### `[CrossOriginCallable]` Used to flag a method that, when called, will not have the same-origin constraint tested: it can be called from a context with a different origin. ### `[SecureContext]` We implement the [standard extended attribute](https://webidl.spec.whatwg.org/#SecureContext) with a few details specific to Gecko: - System principals are considered secure. - An extension poking at non-secured DOM objects will see APIs marked with `[SecureContext]`. - XPConnect sandboxes don't see `[SecureContext]` APIs, except if they're created with `isSecureContext: true`. ### `[NeedsSubjectPrincipal]`, `[GetterNeedsSubjectPrincipal]`, `[SetterNeedsSubjectPrincipal]` Used to flag a method or an attribute that needs to know the subject principal. This principal will be passed as argument. The argument will be a `nsIPrincipal&` because a subject principal is always available. `[NeedsSubjectPrincipal]` applies to both methods and attributes; for attributes it means both the getter and the setter need a subject principal. `[GetterNeedsSubjectPrincipal]` applies only to attributes. `[SetterNeedsSubjectPrincipal]` applies only to non-readonly attributes. These attributes may also be constrained to non-system principals using `[{Getter,Setter,}NeedsSubjectPrincipal=NonSystem]`. This changes the argument type to `nsIPrincipal*`, and passes `nullptr` when called with a system principal. ### `[NeedsCallerType]` Used to flag a method or an attribute that needs to know the caller type, in the `mozilla::dom::CallerType` sense. This can be safely used for APIs exposed in workers; there it will indicate whether the worker involved is a `ChromeWorker` or not. At the moment the only possible caller types are `System` (representing system-principal callers) and `NonSystem`. ### `[GenerateInit]` When set on a dictionary it will add two `Init` methods to the generated C++ class with the following signatures: ``` cpp bool Init(BindingCallContext& cx, JS::Handle val, const char* sourceDescription="Value", bool passedToJSImpl=false); bool Init(JSContext* cx_, JS::Handle val, const char* sourceDescription="Value", bool passedToJSImpl=false); ``` These methods will initialize the dictionary from `val` by following WebIDL's [JavaScript type mapping](https://webidl.spec.whatwg.org/#js-dictionary). ### `[GenerateInitFromJSON]` When set on a dictionary it will add `Init` methods to the generated C++ class with the following signatures: ``` cpp bool Init(const nsAString& aJSON); bool Init(const nsACString& aJSON); ``` This extended attribute will only have an effect if all of the types of the dictionary's members are representable in JSON (they are a string type, a primitive type that's not an unrestricted float/double, a void type, or a sequence, union, dictionary or record containing these types). The method is expected to be called with a JSON string as input. The JSON string will be parsed into a JavaScript value, and then the dictionary is initialized with this value by following WebIDL's [JavaScript type mapping](https://webidl.spec.whatwg.org/#js-dictionary). Note: As a side-effect of how this is implemented it will also add the two `Init` methods that would be added by a [`[GenerateInit]`](#generateinit) extended attribute. ### `[GenerateToJSON]` When set on a dictionary it will add `ToJSON` methods to the generated C++ class with the following signatures: ``` cpp bool ToJSON(nsAString& aJSON); bool ToJSON(nsACString& aJSON); ``` The method will generate a JSON representation of the dictionary members' values in `aJSON` by converting the dictionary to a JavaScript object by following WebIDL's [JavaScript type mapping](https://webidl.spec.whatwg.org/#js-dictionary) and then converting that object to a JSON string. The same restrictions on types applies as on [`[GenerateInitFromJSON]`](#generateinitfromjson). Note: As a side-effect of how this is implemented it will also add the `ToObjectInternal` method that would be added by a [`[GenerateConversionToJS]`](#generateconversiontojs) extended attribute. ### `[GenerateConversionToJS]` When set on a dictionary it will add a `ToObjectInternal` method to the generated C++ class with the following signature: ``` cpp bool ToObjectInternal(JSContext* cx, JS::MutableHandle rval); ``` The method will create a JavaScript object by following WebIDL's [JavaScript type mapping](https://webidl.spec.whatwg.org/#js-dictionary). ### `[GenerateEqualityOperator]` When set on a dictionary it will add an equality operator to the generated C++ class. This is only allowed on dictionaries who only have members (own or inherited) with string, primitive or enum types. ### `[Unsorted]` When set on a dictionary the dictionary's members will not be sorted in lexicographic order (which is specified by WebIDL). This should only ever be used on internal APIs that are not exposed to the Web! ### `[ReflectedHTMLAttributeReturningFrozenArray]` Used to flag a HTML reflected IDL attribute as having a `FrozenArray?` type, where `T` is either `Element` or an interface that inherits from `Element`. This should only be used to implement the algorithms for that kind of reflected IDL attributes. When this attribute's getter is called, it will cache the JS reflection of the returned value on the JS object. The C++ getter will be passed an additional `bool*` argument before the result argument. If this argument is not `null` then the implementation is supposed to set the `bool` that this argument is pointing to to whether the [attr-associated elements](https://html.spec.whatwg.org/#attr-associated-elements) and the [cached attr-associated elements](https://html.spec.whatwg.org/#cached-attr-associated-elements) are equal. If it is not `null`, and the getter sets the pointee to `true` then the cached JS value will be returned, and the result value from the C++ getter will be ignored (so there is no need to set the result's value). If it is `null`, or the getter sets the pointee to `false`, then the cached value will be set to the JS reflection of the result value from the C++ getter, and that JS value will then be returned. Note that this will not cause the JIT to directly get the cached value from the slot (as `[StoreInSlot]` or `[Cached]` would). The setter will also not clear the cached value from the slot. For example, this IDL: ``` webidl interface Element { [Frozen, ReflectedHTMLAttributeReturningFrozenArray] attribute sequence? reflectedHTMLAttribute; }; ``` will require the following declarations in `Element`: ``` cpp class Element { // … void GetReflectedHTMLAttribute( bool* aUseCachedValue, Nullable>>& aResult); void SetReflectedHTMLAttribute( const Nullable>>& aValue); }; ``` ## Helper objects The C++ side of the bindings uses a number of helper objects. ### `Nullable` `Nullable<>` is a struct declared in [`Nullable.h`](https://searchfox.org/firefox-main/source/dom/bindings/Nullable.h) and exported to `mozilla/dom/Nullable.h` that is used to represent nullable values of types that don't have a natural way to represent null. `Nullable` has an `IsNull()` getter that returns whether null is represented and a `Value()` getter that returns a `const T&` and can be used to get the value when it's not null. `Nullable` has a `SetNull()` setter that sets it as representing null and two setters that can be used to set it to a value: `void SetValue(T)` (for setting it to a given value) and `T& SetValue()` for directly modifying the underlying `T&`. ### `Optional` `Optional<>` is a struct declared in [`BindingDeclarations.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingDeclarations.h) and exported to `mozilla/dom/BindingDeclarations.h` that is used to represent optional arguments and dictionary members, but only those that have no default value. `Optional` has a `WasPassed()` getter that returns true if a value is available. In that case, the `Value()` getter can be used to get a `const T&` for the value. ### `NonNull` `NonNull` is a struct declared in [`BindingUtils.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingUtils.h) and exported to `mozilla/dom/BindingUtils.h` that is used to represent non-null C++ objects. It has a conversion operator that produces `T&`. ### `OwningNonNull` `OwningNonNull` is a struct declared in [`OwningNonNull.h`](https://searchfox.org/firefox-main/source/xpcom/base/OwningNonNull.h) and exported to `mozilla/OwningNonNull.h` that is used to represent non-null C++ objects and holds a strong reference to them. It has a conversion operator that produces `T&`. ### Typed arrays, arraybuffers, array buffer views `TypedArray.h` is exported to `mozilla/dom/TypedArray.h` and exposes structs that correspond to the various typed array types, as well as `ArrayBuffer` and `ArrayBufferView`, all in the `mozilla::dom` namespace. Each struct has a `Data()` method that returns a pointer to the relevant type (`uint8_t` for `ArrayBuffer` and `ArrayBufferView`) and a `Length()` method that returns the length in units of `*Data()`. So for example, `Int32Array` has a `Data()` returning `int32_t*` and a `Length()` that returns the number of 32-bit ints in the array. By default, the generated bindings reject typed arrays, `ArrayBuffer`, and `ArrayBufferView` objects larger than 2 GB. To allow larger buffers, use the [`[AllowLarge]`](#allowlarge) extended attribute. ### `Sequence` `Sequence<>` is a type declared in [`BindingDeclarations.h`](https://searchfox.org/firefox-main/source/dom/bindings/BindingDeclarations.h) and exported to `mozilla/dom/BindingDeclarations.h` that is used to represent sequence arguments. It's some kind of typed array, but which exact kind is opaque to consumers. This allows the binding code to change the exact definition (e.g., to use auto arrays of different sizes and so forth) without having to update all the callees. ### `CallbackFunction` `CallbackFunction` is a type declared in [CallbackFunction.h](https://searchfox.org/firefox-main/source/dom/bindings/CallbackFunction.h) and exported to `mozilla/dom/CallbackFunction.h` that is used as a common base class for all the generated callback function representations. This class inherits from `nsISupports`, and consumers must make sure to cycle-collect it, since it keeps JS objects alive. ### `CallbackInterface` `CallbackInterface` is a type declared in [CallbackInterface.h](https://searchfox.org/firefox-main/source/dom/bindings/CallbackInterface.h) and exported to `mozilla/dom/CallbackInterface.h` that is used as a common base class for all the generated callback interface representations. This class inherits from `nsISupports`, and consumers must make sure to cycle-collect it, since it keeps JS objects alive. ### `DOMString` `DOMString` is a class declared in [BindingDeclarations.h](https://searchfox.org/firefox-main/source/dom/bindings/BindingDeclarations.h) and exported to `mozilla/dom/BindingDeclarations.h` that is used for Web IDL `DOMString` return values. It has a conversion operator to `nsString&` so that it can be passed to methods that take that type or `nsAString&`, but callees that care about performance, have an `StringBuffer` available, and promise to hold on to the `StringBuffer` at least until the binding code comes off the stack can also take a `DOMString` directly for their string return value and call its `SetStringBuffer` method with the `StringBuffer` and its length. This allows the binding code to avoid extra reference-counting of the string buffer in many cases, and allows it to take a faster codepath even if it does end up having to addref the `StringBuffer`. ### `GlobalObject` `GlobalObject` is a class declared in [BindingDeclarations.h](https://searchfox.org/firefox-main/source/dom/bindings/BindingDeclarations.h) and exported to `mozilla/dom/BindingDeclarations.h` that is used to represent the global object for static attributes and operations (including constructors). It has a `Get()` method that returns the `JSObject*` for the global and a `GetAsSupports()` method that returns an `nsISupports*` for the global on the main thread, if such is available. It also has a `Context()` method that returns the `JSContext*` the call is happening on. A caveat: the compartment of the `JSContext` may not match the compartment of the global! ### `Date` `Date` is a class declared in [BindingDeclarations.h](https://searchfox.org/firefox-main/source/dom/bindings/BindingDeclarations.h) and exported to `mozilla/dom/BindingDeclarations.h` that is used to represent Web IDL Dates. It has a `TimeStamp()` method returning a double which represents a number of milliseconds since the epoch, as well as `SetTimeStamp()` methods that can be used to initialize it with a double timestamp or a JS `Date` object. It also has a `ToDateObject()` method that can be used to create a new JS `Date`. ### `ErrorResult` `ErrorResult` is a class declared in [ErrorResult.h](https://searchfox.org/firefox-main/source/dom/bindings/ErrorResult.h) and exported to `mozilla/ErrorResult.h` that is used to represent exceptions in Web IDL bindings. This has the following methods: - `Throw`: allows throwing an `nsresult`. The `nsresult` must be a failure code. - `ThrowTypeError`: allows throwing a `TypeError` with the given error message. The list of allowed `TypeError`s and corresponding messages is in [`dom/bindings/Errors.msg`](https://searchfox.org/firefox-main/source/dom/bindings/Errors.msg). - `ThrowJSException`: allows throwing a preexisting JS exception value. However, the `MightThrowJSException()` method must be called before any such exceptions are thrown (even if no exception is thrown). - `Failed`: checks whether an exception has been thrown on this `ErrorResult`. - `ErrorCode`: returns a failure `nsresult` representing (perhaps incompletely) the state of this `ErrorResult`. - `operator=`: takes an `nsresult` and acts like `Throw` if the result is an error code, and like a no-op otherwise (unless an exception has already been thrown, in which case it asserts). This should only be used for legacy code that has nsresult everywhere; we would like to get rid of this operator at some point. ## Events Simple `Event` interfaces can be automatically generated by adding the interface file to GENERATED_EVENTS_WEBIDL_FILES in the appropriate dom/webidl/moz.build file. You can also take a simple generated C++ file pair and use it to build a more complex event (i.e., one that has methods). ### Event handler attributes A lot of interfaces define event handler attributes, like: ``` webidl attribute EventHandler onthingchange; ``` If you need to implement an event handler attribute for an interface, in the definition (header file), you use the handy "IMPL_EVENT_HANDLER" macro: ``` cpp IMPL_EVENT_HANDLER(onthingchange); ``` The "onthingchange" needs to be added to the StaticAtoms.py file: ``` py Atom("onthingchange", "onthingchange") ``` The actual implementation (.cpp) for firing the event would then look something like: ``` cpp nsresult MyInterface::DispatchThingChangeEvent() { NS_NAMED_LITERAL_STRING(type, "thingchange"); EventInit init; init.mBubbles = false; init.mCancelable = false; RefPtr event = Event::Constructor(this, type, init); event->SetTrusted(true); ErrorResult rv; DispatchEvent(*event, rv); return rv.StealNSResult(); // Assuming the caller cares about the return code. } ``` ## `Bindings.conf` details Write me. In particular, need to describe at least use of `concrete`, `prefable`, and `addExternalInterface`. ### How to get a JSContext passed to a given method In some rare cases you may need a `JSContext*` argument to be passed to a C++ method that wouldn't otherwise get such an argument. To see how to achieve this, search for `implicitJSContext` in [dom/bindings/Bindings.conf](#bindings-conf-details). ## Implementing Web IDL using Javascript
Warning
Implementing Web IDL using Javascript is deprecated. New interfaces should always be implemented in C++!
It is possible to implement Web IDL interfaces in JavaScript within Gecko -- however, **this is limited to interfaces that are not exposed in Web Workers**. When the binding occurs, two objects are created: - _Content-exposed object:_ what gets exposed to the web page. - _Implementation object:_ running as a chrome-privileged script. This allows the implementation object to have various APIs that the content-exposed object does not. Because there are two types of objects, you have to be careful about which object you are creating. ### Creating JS-implemented Web IDL objects To create a JS-implemented Web IDL object, one must create both the chrome-side implementation object and the content-side page-exposed object. There are three ways to do this. #### Using the Web IDL constructor If the interface has a constructor, a content-side object can be created by getting that constructor from the relevant content window and invoking it. For example: ``` js var contentObject = new contentWin.RTCPeerConnection(); ``` The returned object will be an Xray wrapper for the content-side object. Creating the object this way will automatically create the chrome-side object using its contractID. This method is limited to the constructor signatures exposed to webpages. Any additional configuration of the object needs to be done methods on the interface. Creating many objects this way can be slow due to the createInstance overhead involved. #### Using a `_create` method A content-side object can be created for a given chrome-side object by invoking the static `_create` method on the interface. This method takes two arguments: the content window in which to create the object and the chrome-side object to use. For example: ``` js var contentObject = RTCPeerConnection._create(contentWin, new MyPeerConnectionImpl()); ``` However, if you are in a JS component, you may only be able to get to the correct interface object via some window object. In this case, the code would look more like: ``` js var contentObject = contentWin.RTCPeerConnection._create(contentWin, new MyPeerConnectionImpl()); ``` Creating the object this way will not invoke its `__init` method or `init` method. #### By returning a chrome-side object from a JS-implemented Web IDL method If a JS-implemented Web IDL method is declared as returning a JS-implemented interface, then a non-Web IDL object returned from that method will be treated as the chrome-side part of a JS-implemented WebIdL object and the content-side part will be automatically created. Creating the object this way will not invoke its `__init` method or `init` method. ### Implementing a Web IDL object in JavaScript To implement a Web IDL interface in JavaScript, first add a Web IDL file, in the same way as you would for a C++-implemented interface. To support implementation in JS, you must add an extended attribute `JSImplementation="CONTRACT_ID_STRING"` on your interface, where CONTRACT_ID_STRING is the XPCOM component contract ID of the JS implementation -- note ";1" is just a Mozilla convention for versioning APIs. Here's an example: ``` webidl [JSImplementation="@mozilla.org/my-number;1"] interface MyNumber { constructor(optional long firstNumber); attribute long value; readonly attribute long otherValue; undefined doNothing(); }; ``` Next, create an XPCOM component that implements this interface. Use the same contract ID as you specified in the Web IDL file. The class ID doesn't matter, except that it should be a newly generated one. For `QueryInterface`, you only need to implement `nsISupports`, not anything corresponding to the Web IDL interface. The name you use for the XPCOM component should be distinct from the name of the interface, to avoid confusing error messages. Web IDL attributes are implemented as properties on the JS object or its prototype chain, whereas Web IDL methods are implemented as methods on the object or prototype. Note that any other instances of the interface that you are passed in as arguments are the full web-facing version of the object, and not the JS implementation, so you currently cannot access any private data. The Web IDL constructor invocation will first create your object. If the XPCOM component implements `nsIDOMGlobalPropertyInitializer`, then the object's `init` method will be invoked with a single argument: the content window the constructor came from. This allows the JS implementation to know which content window it's associated with. The `init` method should not return anything. After this, the content-side object will be created. Then,if there are any constructor arguments, the object's `__init` method will be invoked, with the constructor arguments as its arguments. ### Static Members Static attributes and methods are not supported on JS-implemented Web IDL (see [bug 863952](https://bugzilla.mozilla.org/show_bug.cgi?id=863952)). However, with the changes in [bug 1172785](https://bugzilla.mozilla.org/show_bug.cgi?id=1172785) you can route static methods to a C++ implementation on another object using a `StaticClassOverride` annotation. This annotation includes the full, namespace-qualified name of the class that contains an implementation of the named method. The include for that class must be found in a directory based on its name. ``` webidl [JSImplementation="@mozilla.org/dom/foo;1"] interface Foo { [StaticClassOverride="mozilla::dom::OtherClass"] static Promise doSomething(); }; ``` Rather than calling into a method on the JS implementation; calling `Foo.doSomething()` will result in calling `mozilla::dom::OtherClass::DoSomething()`. ### Checking for Permissions or Preferences With JS-implemented Web IDL, the `init` method should only return undefined. If any other value, such as `null`, is returned, the bindings code will assert or crash. In other words, it acts like it has an "undefined" return type. Preference or permission checking should be implemented by adding an extended attribute to the Web IDL interface. This has the advantage that if the check fails, the constructor or object will not show up at all. For preference checking, add an extended attribute `Pref="myPref.enabled"` where `myPref.enabled` is the preference that should be checked. `SettingsLock` is an example of this. For permissions or other kinds of checking, add an extended attribute `Func="MyPermissionChecker"` where `MyPermissionChecker` is a function implemented in C++ that returns true if the interface should be enabled. This function can do whatever checking is needed. One example of this is `PushManager`. ### Example Here's an example JS implementation of the above interface. The `invisibleValue` field will not be accessible to web content, but is usable by the doNothing() method. ``` js function MyNumberInner() { this.value = 111; this.invisibleValue = 12345; } MyNumberInner.prototype = { classDescription: "Get my number XPCOM Component", contractID: "@mozilla.org/my-number;1", QueryInterface: ChromeUtils.generateQI([]), doNothing: function() {}, get otherValue() { return this.invisibleValue - 4; }, __init: function(firstNumber) { if (arguments.length > 0) { this.value = firstNumber; } } } ``` Finally, add a component and a contract and whatever other manifest stuff you need to implement an XPCOM component. ### Guarantees provided by bindings When implementing a Web IDL interface in JavaScript, certain guarantees will be provided by the binding implementation. For example, string or numeric arguments will actually be primitive strings or numbers. Dictionaries will contain only the properties that they are declared to have, and they will have the right types. Interface arguments will actually be objects implementing that interface. What the bindings will NOT guarantee is much of anything about `object` and `any` arguments. They will get cross-compartment wrappers that make touching them from chrome code not be an immediate security bug, but otherwise they can have quite surprising behavior if the page is trying to be malicious. Try to avoid using these types if possible. ### Accessing the content object from the implementation If the JS implementation of the Web IDL interface needs to access the content object, it is available as a property called `__DOM_IMPL__` on the chrome implementation object. This property only appears after the content-side object has been created. So it is available in `__init` but not in `init`. ### Determining the principal of the caller that invoked the Web IDL API This can be done by calling `Component.utils.getWebIDLCallerPrincipal()`. ### Throwing exceptions from JS-implemented APIs There are two reasons a JS implemented API might throw. The first reason is that some unforeseen condition occurred and the second is that a specification requires an exception to be thrown. When throwing for an unforeseen condition, the exception will be reported to the console, and a sanitized NS_ERROR_UNEXPECTED exception will be thrown to the calling content script, with the file/line of the content code that invoked your API. This will avoid exposing chrome URIs and other implementation details to the content code. When throwing because a specification requires an exception, you need to create the exception from the window your Web IDL object is associated with (the one that was passed to your `init` method). The binding code will then rethrow that exception to the web page. An example of how this could work: ``` js if (!isValid(passedInObject)) { throw new this.contentWindow.TypeError("Object is invalid"); } ``` or ``` js if (!isValid(passedInObject)) { throw new this.contentWindow.DOMException("Object is invalid", "InvalidStateError"); } ``` depending on which exact exception the specification calls for throwing in this situation. In some cases you may need to perform operations whose exception message you just want to propagate to the content caller. This can be done like so: ``` js try { someOperationThatCanThrow(); } catch (e) { throw new this.contentWindow.Error(e.message); } ``` ### Inheriting from interfaces implemented in C++ It's possible to have an interface implemented in JavaScript inherit from an interface implemented in C++. To do so, simply have one interface inherit from the other and the bindings code will auto-generate a C++ object inheriting from the implementation of the parent interface. The class implementing the parent interface will need a constructor that takes an `nsPIDOMWindow*` (though it doesn't have to do anything with that argument). If the class implementing the parent interface is abstract and you want to use a specific concrete class as the implementation to inherit from, you will need to add a `defaultImpl` annotation to the descriptor for the parent interface in `Bindings.conf`. The value of the annotation is the C++ class to use as the parent for JS-implemented descendants; if `defaultImpl` is not specified, the `nativeType` will be used. For example, consider this interface that we wish to implement in JavaScript: ``` webidl [JSImplementation="some-contract"] interface MyEventTarget : EventTarget { attribute EventHandler onmyevent; undefined dispatchTheEvent(); // Sends a "myevent" event to this EventTarget } ``` The implementation would look something like this, ignoring most of the XPCOM boilerplate: ``` js function MyEventTargetImpl() { } MyEventTargetImpl.prototype = { // QI to nsIDOMGlobalPropertyInitializer so we get init() called on us. QueryInterface: ChromeUtils.generateQI(["nsIDOMGlobalPropertyInitializer"]), init: function(contentWindow) { this.contentWindow = contentWindow; }, get onmyevent() { return this.__DOM_IMPL__.getEventHandler("onmyevent"); }, set onmyevent(handler) { this.__DOM_IMPL__.setEventHandler("onmyevent", handler); }, dispatchTheEvent: function() { var event = new this.contentWindow.Event("myevent"); this.__DOM_IMPL__.dispatchEvent(event); }, }; ``` The implementation would automatically support the API exposed on `EventTarget` (so, for example, `addEventListener`). Calling the `dispatchTheEvent` method would cause dispatch of an event that content script can see via listeners it has added. Note that in this case the chrome implementation is relying on some `[ChromeOnly]` methods on EventTarget that were added specifically to make it possible to easily implement event handlers. Other cases can do similar things as needed. --- ### Browser Components Pagedata Docs Index (`browser/components/pagedata/docs/index.md`) # PageDataService The page data service is responsible for collecting additional data about a page. This could include information about the media on a page, product information, etc. When enabled it will automatically try to find page data for pages that the user browses or it can be directed to asynchronously look up the page data for a url. The `PageDataService` is an EventEmitter and listeners can subscribe to its notifications via the `on` and `once` methods. The service can be enabled by setting `browser.pagedata.enabled` to true. Additional logging can be enabled by setting `browser.pagedata.log` to true. ## PageData Data Structure At a high level the page data service can collect many different kinds of data. When queried the service will respond with a `PageData` structure which holds some general information about the page, the time when the data was discovered and a map of the different types of data found. This map will be empty if no specific data was found. The key of the map is from the `PageDataSchema.DATA_TYPE` enumeration. The value is the JSON data which differs in structure depending on the data type. ``` { "url": , "date": , "siteName": , "image": , "data": , } ``` ## PageData Collection Page data is gathered in one of two ways. Page data is automatically gathered for webpages the user visits. This collection is trigged after a short delay and then updated when necessary. Any data is cached in memory for a period of time. When page data has been found a `page-data` event is emitted. The event's argument holds the `PageData` structure. The `getCached` function can be used to access any cached data for a url. ## Supported Types of page data The following types of page data (`PageDataSchema.DATA_TYPE`) are currently supported: - `PRODUCT` - `DOCUMENT` - `ARTICLE` - `AUDIO` - `VIDEO` --- ### Devtools Docs Contributor Files README (`devtools/docs/contributor/files/README.md`) # Directories Overview This page provides a very top level overview of what is on each directory in the DevTools source code: * `devtools/shared`: Code shared by both the client (front-end UI) and server. If we are using any third party libraries, or importing external repositories into our tree, those libraries generally live here (eg, `devtools/shared/jsbeautify`), assuming they are used by both client and server. * `devtools/shared/client`: Code for the [Remote Debugging Protocol](../backend/protocol.md) (RDP) client. You may wonder why this is not in `devtools/client` below: it's mainly because tests in server also need access to the RDP client. * `devtools/shared/locales`: Strings used in either the server only, or shared with both the client and server. * `devtools/server`: Code for the [RDP](../backend/protocol.md) server and transport layer. * `devtools/server/actors`: [RDP Actors](../backend/protocol.md#actors). Note that if you're modifying actors, you may need to worry about [backwards compatibility](../backend/backward-compatibility.md) with older clients. * `devtools/client`: Code for the front-end side of our tools. In theory, each directory corresponds to a panel, but this is not always the case. This directory is only shipped with desktop Firefox, as opposed to other directories above, which are shipped with all Gecko products (Firefox for Android, etc.) * `devtools/client/locales`: Strings used in the client front-end. * `devtools/client/themes`: CSS and images used in the client front-end. --- ### Devtools Docs Contributor Tests README (`devtools/docs/contributor/tests/README.md`) # Automated tests When working on a patch for DevTools, there's almost never a reason not to add a new test. If you are fixing a bug, you probably should write a new test to prevent this bug from occurring again. If you're implementing a new feature, you should write new tests to cover the aspects of this new feature. Ask yourself: * Are there enough tests for my patch? * Are they the right types of tests? We use three suites of tests: * [`xpcshell`](xpcshell.md): Unit-test style of tests. No browser window, only a JavaScript shell. Mostly testing APIs directly. * [Chrome mochitests](mochitest-chrome.md): Unit-test style of tests, but with a browser window. Mostly testing APIs that interact with the DOM. * [DevTools mochitests](mochitest-devtools.md): Integration style of tests. Fires up a whole browser window with every test and you can test clicking on buttons, etc. To run all DevTools tests, regardless of suite type: ```bash ./mach test devtools/* ``` Have a look at the child pages for more specific commands for running only a single suite or single test in a suite. --- ### Devtools Docs Contributor Tests Performance Tests Overview (`devtools/docs/contributor/tests/performance-tests-overview.md`) # DevTools Performance Tests overview This page provides a short overview of the various DevTools performance tests. ## damp DAMP (short for DevTools At Maximum Performance) is the main DevTools performance test suite, based on the talos framework. It mostly runs end to end scenarios, opening the toolbox, various panels and interacting with the UI. It might regress for a wide variety of reasons: DevTools frontend changes, DevTools server changes, platform changes etc. To investigate DAMP regressions or improvements, it is usually necessary to analyze DAMP subtests individually. See [DAMP Performance tests](performance-tests-damp.md) for more details on how to run DAMP, analyze results or add new tests. ## debugger-metrics debugger-metrics measures the number of modules and the overall size of modules loaded when opening the Debugger in DevTools. This test is a mochitest which can be executed locally with: ```bash ./mach test devtools/client/framework/test/metrics/browser_metrics_debugger.js --headless ``` At the end of the test, logs should contain a `PERFHERDER_DATA` entry containing 4 measures. `debugger-modules` is the number of debugger-specific modules loaded, `debugger-chars` is the number of characters in said modules. `all-modules` is the number of modules loaded including shared modules, `all-chars` is the number of characters in said modules. A significant regression or improvement to this test can indicate that modules are no longer lazy loaded, or a new part of the UI is now loaded upfront. ## inspector-metrics See the description for debugger-metrics. This test is exactly the same but applied to the inspector panel. It can be executed locally with: ```bash ./mach test devtools/client/framework/test/metrics/browser_metrics_inspector.js --headless ``` ## netmonitor-metrics See the description for debugger-metrics. This test is exactly the same but applied to the netmonitor panel. It can be executed locally with: ```bash ./mach test devtools/client/framework/test/metrics/browser_metrics_netmonitor.js --headless ``` ## webconsole-metrics See the description for debugger-metrics. This test is exactly the same but applied to the webconsole panel. It can be executed locally with: ```bash ./mach test devtools/client/framework/test/metrics/browser_metrics_webconsole.js --headless ``` ## server.pool server.pool measures the performance of the DevTools `Pool` [class](https://searchfox.org/firefox-main/source/devtools/shared/protocol/Pool.js) which is intensively used by the DevTools server. This test is a mochitest which can be executed with: ```bash ./mach test devtools/client/framework/test/metrics/browser_metrics_pool.js --headless ``` At the end of the test, logs should contain a `PERFHERDER_DATA` entry which contain values corresponding to various APIs of the `Pool` class. A regression or improvement in this test is most likely linked to a change in a file from devtools/shared/protocol. ## toolbox:parent-process toolbox:parent-process measures the number of objects allocated by DevTools after opening and closing a DevTools toolbox. This test is a mochitest which can be executed with: ```bash ./mach test devtools/client/framework/test/allocations/browser_allocations_toolbox.js --headless ``` The test will record allocations while opening and closing the Toolbox several times. The `PERFHERDER_DATA` entry in the logs will contain 3 measures. objects-with-stacks is the number of allocated objects for which the allocation site is known and should be easy to fix for developers. You can refer to the [allocation tests documentation](https://searchfox.org/firefox-main/source/devtools/client/framework/test/allocations/docs/index.md) for a more detailed description of this test and how to use it to investigate and fix memory issues. A regression here may indicate a leak, for instance a module which no longer cleans its dependencies. It can also indicate that DevTools is loading more singletons or other objects which are not tied to the lifecycle of the DevTools objects. ## target:parent-process target:parent-process measures the number of objects created by DevTools to create a tab target. It does not involve DevTools frontend. This test is a mochitest which can be executed with: ```bash ./mach test devtools/client/framework/test/allocations/browser_allocations_target.js --headless ``` See the description for toolbox:parent-process for more information. ## reload:parent-process target:parent-process measures the number of objects created by DevTools when reloading a page inspected by a DevTools Toolbox. This test is a mochitest which can be executed with: ```bash ./mach test devtools/client/framework/test/allocations/browser_allocations_reload.js --headless ``` See the description for toolbox:parent-process for more information. Note that this test also records another suite, reload:content-process. ## reload:content-process See the description for reload:parent-process. ## browser-console:parent-process browser-console:parent-process measures the number of objects created by DevTools when opening and closing the Browser Console. This test is a mochitest which can be executed with: ```bash ./mach test devtools/client/framework/test/allocations/browser_allocations_browser_console.js --headless ``` See the description for toolbox:parent-process for more information. --- ### Devtools Client Framework Test Allocations Docs Index (`devtools/client/framework/test/allocations/docs/index.md`) # Allocation tests The [allocations](https://searchfox.org/firefox-main/source/devtools/client/framework/test/allocations) folder contains special mochitests which are meant to record data about the memory usage of DevTools. This uses Spidermonkey's Memory API implemented next to the debugger API. For more info, see the following doc: # Test example ```javascript add_task(async function() { // Execute preliminary setup in order to be able to run your scenario // You would typicaly load modules, open a tab, a toolbox, ... ... // Run the test scenario first before recording in order to load all the // modules. Otherwise they get reported as "still allocated" objects, // whereas we do expect them to be kept in memory as they are loaded via // the main DevTools loader, which keeps the module loaded until the // shutdown of Firefox await testScript(); // Pass alsoRecordContentProcess if you want to record the content process // of the current tab. Otherwise it will only record parent process objects. await startRecordingAllocations({ alsoRecordContentProcess: true }); // Now, run the test script. This time, we record this run. await testScript(toolbox); // This will stop the record and also publish the results to Talos database // Second argument will be the name of the test displayed in Talos. // Many tests will be recorded, but all of them will be prefixed with this string. await stopRecordingAllocations("reload", { alsoRecordContentProcess: true }); // Then, here you can execute cleanup. // You would typically close the tab, toolbox, ... }); ``` # How to run them locally ```bash $ ./mach mochitest --headless devtools/client/framework/test/allocations/ ``` And to only see the results: ```bash $ ./mach mochitest --headless devtools/client/framework/test/allocations/ | grep " test leaked " ``` # Debug leaks If you are seeing a regression or an improvement, only seeing the number of objects being leaked isn't super helpful. The tests includes some special debug modes which are printing lots of data to figure out what is leaking and why. You may run the test with the following env variable to turn debug mode on: ```bash DEBUG_DEVTOOLS_ALLOCATIONS=leak|allocations $ ./mach mochitest --headless devtools/client/framework/test/allocations/the-fault-test.js ``` **DEBUG_DEVTOOLS_ALLOCATIONS** can enable two distinct debug output. (Only one can be enabled at a given time) **DEBUG_DEVTOOLS_ALLOCATIONS=allocations** will report all allocation sites that have been made while running your test. This will include allocations which has been freed. This view is especially useful if you want to reduce allocations in order to reduce GC overload. **DEBUG_DEVTOOLS_ALLOCATIONS=leak** will report only the allocations which are still allocated at the end of your test. Sometimes it will only report allocations with missing stack trace. Thus making the preview view helpful. ## Example Let's assume we have the following code: ```javascript 1: exports.MyModule = { 2: globalArray: [], 3: test() { 3: // The following object will be allocated but not leaked, 5: // as we keep no reference to it anywhere 6: const transientObject = {}; 7: 8: // The following object will be allocated on this line, 9: // but leaked on the following one. By storing a reference 10: // to it in the global array which is never cleared. 11: const leakedObject = {}; 12: this.globalArray.push(leakedObject); 13: }, 14: }; ``` And that, we have a memory test doing this: ```javascript const { MyModule } = require("devtools/my-module"); await startRecordingAllocations(); MyModule.test(); await stopRecordingAllocations("target"); ``` We can first review all the allocations by running: ```bash DEBUG_DEVTOOLS_ALLOCATIONS=allocations $ ./mach mochitest --headless devtools/client/framework/test/allocations/browser_allocation_myTest.js ``` which will print at the end: ```javascript DEVTOOLS ALLOCATION: all allocations (which may be freed or are still allocated): [ { "src": "UNKNOWN", "count": 80, "lines": [ "?: 80" ] }, { "src": "resource://devtools/my-module.js", "count": 2, "lines": [ "11: 1" "6: 1" ] } ] ``` The first part, with `UNKNOWN` can be ignored. This is about objects with missing allocation sites. The second part of this logs tells us that 2 objects were allocated from my-module.js when running the test. One has been allocated at line 6, it is `transcientObject`. Another one has been allocated at line 11, it is `leakedObject`. Now, we can use the second view to focus only on objects that have been kept allocated: ```bash DEBUG_DEVTOOLS_ALLOCATIONS=leaks $ ./mach mochitest --headless devtools/client/framework/test/allocations/browser_allocation_myTest.js ``` which will print at the end: ```javascript DEVTOOLS ALLOCATION: allocations which leaked: [ { "src": "UNKNOWN", "count": 80, "lines": [ "?: 80" ] }, { "src": "resource://devtools/shared/commands/commands-factory.js", "count": 1, "lines": [ "11: 1" ] } ] ``` Similarly, we can focus only on the second part, which tells us that only one object is being leaked and this object has been originally created from line 11, this is `leakedObject`. This doesn't tell us why the object is being kept allocated, but at least we know which one is being kept in memory. ## Debug leaks via dominators This last feature might be the most powerful and isn't bound to DEBUG_DEVTOOLS_ALLOCATIONS. This is always enabled. Also, it requires to know which particular object is being leaked and also require to hack the codebase in order to pass a reference of the suspicious object to the test helper. You can instruct the test helper to track a given object by doing this: ```javascript 1: // Let's say it is some code running from "my-module.js" 2: 3: // From a DevTools CommonJS module: 4: const { track } = require("devtools/shared/test-helpers/tracked-objects.sys.mjs"); 5: // From anything else, JSM, XPCOM module,...: 6: const { track } = ChromeUtils.importESModule("resource://devtools/shared/test-helpers/tracked-objects.sys.mjs"); 7: 8: const g = []; 9: function someFunctionInDevToolsCalledBySomething() { 10: const myLeakedObject = {}; 11: track(myLeakedObject); 12: 13: // Simulate a leak by holding a reference to the object in a global `g` array 14: g.push({ seeMyCustomAttributeHere: myLeakedObject }); 15: } ``` Then, when running the test you will get such output: ```bash 0:41.26 GECKO(644653) # Tracing: Object@my-module:10 0:40.65 GECKO(644653) ### Path(s) from root: 0:41.26 GECKO(644653) - other@no-stack:undefined.WeakMap entry value 0:41.26 GECKO(644653) \--> LexicalEnvironment@base-loader.sys.mjs:160.**UNKNOWN SLOT 1** 0:41.26 GECKO(644653) \--> Object@base-loader.sys.mjs:155.g 0:41.26 GECKO(644653) \--> Array@my-module.js:8.objectElements[0] 0:41.26 GECKO(644653) \--> Object@my-module.js:14.seeMyCustomAttributeHere 0:41.26 GECKO(644653) \--> Object@my-module.js:10 ``` This output means that `myLeakedObject` was originally allocated from my-module.js at line 10. And is being held allocated because it is kept in an Object allocated from my-module.js at line 14. This is our custom object we stored in `g` global Array. This custom object it hold by the Array allocated at line 8 of my-module.js. And this array is held allocated from an Object, itself allocated by base-loader.sys.mjs at line 155. This is the global of the my-module.js's module, created by DevTools loader. Then we see some more low level object up to another global object, which misses its allocation site. # How to easily get data from try run ```bash $ ./mach try fuzzy devtools/client/framework/test/allocations/ --query "'linux 'chrome-e10s 'opt '64-qr/opt" ``` You might also pass `--rebuild 3` if the test result is having some noise and you want more test runs. # Following trends for these tests You may try looking at: Or at: Link that you get from: by looking at last year data for "DevTools" in the first dropdown, and double clicking on the relevant line in "Tests" menulist. Significant improvements and regressions will be notified through [the following dashboard](https://treeherder.mozilla.org/perfherder/alerts?hideDwnToInv=1&page=1&framework=12). --- ### Dom Webgpu Tests Cts Checkout Docs Intro README (`dom/webgpu/tests/cts/checkout/docs/intro/README.md`) # Introduction These documents contains guidelines for contributors to the WebGPU CTS (Conformance Test Suite) on how to write effective tests, and on the testing philosophy to adopt. The WebGPU CTS is arguably more important than the WebGPU specification itself, because it is what forces implementation to be interoperable by checking they conform to the specification. However writing a CTS is hard and requires a lot of effort to reach good coverage. More than a collection of tests like regular end2end and unit tests for software artifacts, a CTS needs to be exhaustive. Contrast for example the WebGL2 CTS with the ANGLE end2end tests: they cover the same functionality (WebGL 2 / OpenGL ES 3) but are structured very differently: - ANGLE's test suite has one or two tests per functionality to check it works correctly, plus regression tests and special tests to cover implementation details. - WebGL2's CTS can have thousands of tests per API aspect to cover every combination of parameters (and global state) used by an operation. Below are guidelines based on our collective experience with graphics API CTSes like WebGL's. They are expected to evolve over time and have exceptions, but should give a general idea of what to do. ## Contributing Testing tasks are tracked in the [CTS project tracker](https://github.com/orgs/gpuweb/projects/3). Go here if you're looking for tasks, or if you have a test idea that isn't already covered. If contributing conformance tests, the directory you'll work in is [`src/webgpu/`](../src/webgpu/). This directory is organized according to the goal of the test (API validation behavior vs actual results) and its target (API entry points and spec areas, e.g. texture sampling). The contents of a test file (`src/webgpu/**/*.spec.ts`) are twofold: - Documentation ("test plans") on what tests do, how they do it, and what cases they cover. Some test plans are fully or partially unimplemented: they either contain "TODO" in a description or are `.unimplemented()`. - Actual tests. **Please read the following short documents before contributing.** ### 0. [Developing](developing.md) - Reviewers should also read [Review Requirements](../reviews.md). ### 1. [Life of a Test Change](life_of.md) ### 2. [Adding or Editing Test Plans](plans.md) ### 3. [Implementing Tests](tests.md) ## [Additional Documentation](../) ## Examples ### Operation testing of vertex input id generation This section provides an example of the planning process for a test. It has not been refined into a set of final test plan descriptions. (Note: this predates the actual implementation of these tests, so doesn't match the actual tests.) Somewhere under the `api/operation` node are tests checking that running `GPURenderPipelines` on the device using the `GPURenderEncoderBase.draw` family of functions works correctly. Render pipelines are composed of several stages that are mostly independent so they can be split in several parts such as `vertex_input`, `rasterization`, `blending`. Vertex input itself has several parts that are mostly separate in hardware: - generation of the vertex and instance indices to run for this draw - fetching of vertex data from vertex buffers based on these indices - conversion from the vertex attribute `GPUVertexFormat` to the datatype for the input variable in the shader Each of these are tested separately and have cases for each combination of the variables that may affect them. This means that `api/operation/render/vertex_input/id_generation` checks that the correct operation is performed for the cartesian product of all the following dimensions: - for encoding in a `GPURenderPassEncoder` or a `GPURenderBundleEncoder` - whether the draw is direct or indirect - whether the draw is indexed or not - for various values of the `firstInstance` argument - for various values of the `instanceCount` argument - if the draw is not indexed: - for various values of the `firstVertex` argument - for various values of the `vertexCount` argument - if the draw is indexed: - for each `GPUIndexFormat` - for various values of the indices in the index buffer including the primitive restart values - for various values for the `offset` argument to `setIndexBuffer` - for various values of the `firstIndex` argument - for various values of the `indexCount` argument - for various values of the `baseVertex` argument "Various values" above mean several small values, including `0` and the second smallest valid value to check for corner cases, as well as some large value. An instance of the test sets up a `draw*` call based on the parameters, using point rendering and a fragment shader that outputs to a storage buffer. After the draw the test checks the content of the storage buffer to make sure all expected vertex shader invocation, and only these ones have been generated. --- ### Index (`docs/index.rst`) ================================= Firefox Source Tree Documentation ================================= .. toctree:: :caption: Overview :maxdepth: 2 {overview_doc} .. toctree:: :caption: Getting Started :maxdepth: 1 {setup_doc} .. toctree:: :caption: Working On Firefox :maxdepth: 2 {contributing_doc} .. toctree:: :caption: Firefox User Guide :maxdepth: 2 {user_guide} .. toctree:: :caption: Source Code Documentation :maxdepth: 2 {source_doc} .. toctree:: :caption: The Firefox Build System :maxdepth: 1 {build_doc} .. toctree:: :caption: Testing & Test Infrastructure :maxdepth: 1 {testing_doc} .. toctree:: :caption: AI Agent Tools :maxdepth: 1 {ai_agent_tools_doc} .. toctree:: :caption: Releases & Updates :maxdepth: 1 {release_doc} .. toctree:: :caption: Localization & Internationalization :maxdepth: 2 {l10n_doc} .. toctree:: :caption: Firefox and Python :maxdepth: 1 {python_doc} .. toctree:: :caption: Metrics Collected in Firefox :maxdepth: 1 {metrics_doc} Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` --- ### Accessible Docs Architecture (`accessible/docs/Architecture.md`) # Architecture This document provides a high-level overview of how the accessibility code is structured. See [the Document Accessibility Lifecycle page](DocumentAccessibilityLifecycle.md#docaccessible-creation) for a lower level description of the code. ## Process Model The accessibility component spans multiple processes. In the parent process, it creates an accessibility tree of the Firefox UI and responds to requests from accessibility clients such as screen readers, magnifiers and voice control tools. In content processes, the accessibility component creates accessibility trees from web content. To respond to accessibility client requests quickly, the accessibility tree from each content process is cached in the parent process. ## Accessibility Trees Accessibility trees can carry different kinds of information: informally, there are "local trees" that represent a document in the current process and "remote trees" that mirror a local tree created in a separate process. A local tree can only contain nodes in the current process, i.e. you can visit any node in the tab document and its in-process iframes. However, out-of-process iframes appear as a separate local tree in a different process. A remote tree, on the other hand, unifies these trees: you can visit any node in the tab document and both its in-process and out-of-process iframes. This means there are multiple accessibility trees for a single tab: one local tree in the content process, one local tree for each out-of-process iframe, and one remote tree in the parent process that mirrors these local trees. The Firefox UI is represented by a single local tree in the parent process. An accessibility client communicates only with the parent process. It sees the local tree for the Firefox UI and the remote trees for tabs and iframes as a single, unified tree. ### Tree Nodes An accessibility tree is composed of nodes represented by the `Accessible` class and its subtypes. Below is an example local accessibility tree from [example.com](https://example.com), as printed by `a11y::logging::Tree` (unfortunately, without type information): ``` A11Y TREE: Initial subtree; 44:14.388 { : 0x107077a00; role: document, name: 'Example Domain', idx: 0, node: 0x105f84800, #document : 0x105fb8b30; role: heading, name: 'Example Domain', idx: 0, node: 0x107b048b0, h1 : 0x105fb8c90; role: text leaf, name: 'Example Domain', idx: 0, node: 0x107b05600, #text : 0x105fb8d40; role: paragraph, idx: 1, node: 0x107b04940, p : 0x105fb8df0; role: text leaf, name: 'This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.', idx: 0, node: 0x107b05700, #text : 0x105fb8ea0; role: paragraph, idx: 2, node: 0x107b049d0, p : 0x107922030; role: link, name: 'More information...', idx: 0, node: 0x107b030e0, a [ href="https://www.iana.org/domains/example" ] : 0x1079220e0; role: text leaf, name: 'More information...', idx: 0, node: 0x107b05800, #text } ``` Accessible has a direct subtype for different kinds of accessibility trees: `LocalAccessible` for nodes of local trees and `RemoteAccessible` for nodes of remote trees. For example, `LocalAccessible` can be used in content processes for web content and in the parent process for the Firefox UI. The descendants of these two types diverge. LocalAccessible's direct descendant is `AccessibleWrap`. By convention, a class that ends in `Wrap` is a platform-specific implementation so `AccessibleWrap` contains the platform-specific implementations of `Accessible` and `LocalAccessible`. `AccessibleWrap's` direct and indirect subtypes are representations of HTML and XUL nodes such as `HTMLButtonAccessible` and `HTMLListBulletAccessible`. The Document and the root node of the accessibility tree are also represented by the `Accessible` class: `DocAccessible` and `DocAccessibleWrap` as well as `RootAccessible` and `RootAccessibleWrap` extend `AccessibleWrap`. RemoteAccessible doesn’t have such an extensive type hierarchy. Its primary descendant is `DocAccessibleParent` which is the Document node of a remote tree located in the parent process: its local tree counterpart in a content process is `DocAccessible`. Below is a graph that displays the same relationships described above. In the graph, solid lines represent direct descendants while dotted lines represent indirect descendants: ```{mermaid} flowchart TD accTitle: Graph of the class hierarchy described above Accessible --> LocalAccessible[LocalAccessible: local tree] & RemoteAccessible[RemoteAccessible: remote tree] LocalAccessible --> AccessibleWrap[AccessibleWrap: platform-specific implementation] AccessibleWrap -.-> DocAccessible & HTMLButtonAccessible & HTMLListBulletAccessible DocAccessible --> DocAccessibleWrap --> RootAccessible --> RootAccessibleWrap RemoteAccessible -.-> DocAccessibleParent ``` ### Platform-Specific Behavior Accessibility trees differ by platform. The platform-independent tree, composed of types like `LocalAccessible` and `RemoteAccessible`, is marshalled into a platform-specific tree that makes it easier to implement the platform's accessibility API (or APIs). The platform tree is composed of the following node types: - Windows: [MsaaAccessible], [ia2Accessible] and [uiaRawElmProvider] - macOS: [mozAccessible] - Linux: [ATKObjects and MaiAtkObjects](https://searchfox.org/mozilla-central/rev/d7d2cc647772de15c4c5aa47f74d25d0e379e404/accessible/atk/nsMai.h#87) [MsaaAccessible]: https://searchfox.org/mozilla-central/rev/d7d2cc647772de15c4c5aa47f74d25d0e379e404/accessible/windows/msaa/MsaaAccessible.h [ia2Accessible]: https://searchfox.org/mozilla-central/rev/d7d2cc647772de15c4c5aa47f74d25d0e379e404/accessible/windows/ia2/ia2Accessible.h#21 [uiaRawElmProvider]: https://searchfox.org/firefox-main/rev/dab03896ede1413be148884e054b311767bcf1a0/accessible/windows/uia/uiaRawElmProvider.h#34 [mozAccessible]: https://searchfox.org/mozilla-central/rev/d7d2cc647772de15c4c5aa47f74d25d0e379e404/accessible/mac/mozAccessible.mm --- ### Accessible Docs ColorsAndHighContrastMode (`accessible/docs/ColorsAndHighContrastMode.md`) # Colors and High Contrast Mode Firefox offers several customisations to improve the accessibility of colors used to render web content and Firefox chrome. This document describes the customisation options available and their behaviour across platforms. It also describes how these options interact with one another. It is intended for developer reference :) ## The Contrast Control Settings In `about:preferences > Language and Appearance`, you'll find a subsection labeled "Contrast Control". The radio group in this section determines if high contrast mode (HCM) will be used. HCM can either be enabled on the platform level (OS HCM), or forced on in the browser (FF HCM) The radio buttons alter `browser.display.document_color_use`. HCM can be enabled automatically with OS settings (OS HCM, `document_color_use=0`), it can be forced off (`document_color_use=1`), or forced on (FF HCM, `document_color_use=2`). When HCM is enabled, either automatically or explicitly, web content is rendered with a predetermined palette to give the user full control of the content's color contrast. > Note: FF HCM only affects web content, so changing the option in this select will only alter color usage for web pages. It will not change FF chrome. Current behaviour on chrome pages (ie. `about:` pages) is undefined. ### User-customisable Colors Dialog If the user has chosen to explicitly turn on Firefox HCM (`document_color_use=2`), they may customize the palette in a modal dialog. Users can choose to override background color, foreground color, visited link color, and/or unvisited link color by selecting a new color from the color inputs in the dialog. Modifications to these colors are stored in their corresponding user preference: - `browser.background_color` - `browser.foreground_color` - `browser.visited_color` - `browser.anchor_color` ## Color Usage and System Colors Before we render any Firefox/web content, we need to select a color palette to render that content _with_. There are three different sets of colors we can use to style Firefox and/or web content: - Stand-in colors - System colors - Colors-dialog colors > Note: Web pages may supply their palette through style sheets. When FF HCM is set to "On", or set to "Use platform's contrast settings" and OS HCM is enabled, the chosen color palette is _forced_, meaning it cannot be overridden by web pages. We decide which set of colors to use in `PreferenceSheet::Load`. If `resistFingerprinting` is enabled, we use stand-in colors. These colors are pre-defined constants and are not dynamically fetched from the operating system. Check out `nsXPLookAndFeel::GetStandinForNativeColor` for more information, as well as the constants themselves. If we aren't using stand-in colors, we'll check the `browser.display.document_color_use` pref. If HCM is explicitly off (`1`), or automatically off (`0`), we will use the system colors as default text and link colors. System colors are colors queried from the operating system. They help Firefox adapt to OS-level changes that aren't strictly HCM (ie. light/dark themeing). Because these colors are OS-dependent, a user operating Firefox on a Windows machine with system colors enabled will see Firefox differently than a user with system colors enabled on MacOS. So, how do we _get_ system colors? Our style system has a set of pre-defined `ColorID`'s in `ServoStyleConsts.h`, which are mapped to platform-specific colors in `widget/[cocoa | android | windows | gtk]/LookAndFeel.cpp`. Depending on the `ColorID` queried, we may do a dynamic fetch or simply return a constant. On MacOS, for example, `ColorID::TextForeground` and `ColorID::TextBackground` are hard-coded to return black and white respectively. `ColorID::Highlight`, on the other hand, queries the OS for `NSColor.selectedTextBackgroundColor`, which is set based on the accent color a user has selected in System Preferences. > Note: The colors we fetch here are theme-relative. If a user has set their OS to a dark theme, we'll fetch colors from that palette, and likewise for a light theme. Windows HCM, though not strictly a "theme", overrides the colors stored for Windows' light theme, leading to [some confusing code, like this](https://searchfox.org/mozilla-central/rev/b462b11e71b500e084f51e61fbd9e19ea0122c78/layout/style/PreferenceSheet.cpp#202-210). Lastly, if we explicitly turn on HCM (`document_color_use=2`) AND we are _not_ styling Firefox chrome AND we are _not_ `resistFingerprinting`, we'll use colors-dialog colors to style web content. By default, `browser.display.document_color_use` is set to `2` on Windows. If a user turns on the OS HCM Firefox will automatically go into HCM mode as well. > Note: This is intentional. Windows HCM is the most robust HCM offered among the operating systems we support, and so we cater to it here :) Users on non-Windows platforms have HCM disabled by default (`document_color_use=1`). In order to enable Firefox HCM, they will either need to turn it on explicitly (`document_color_use=2`), or set it to use the OS HCM mode and palette (`document_color_use=0`). For a simplified flow chart of this decision tree, check out our [HCM Settings page](HCMSettings.html) ## High Contrast Mode ### Operating System High Contrast Mode (OS HCM) Operating System HCM (or OS HCM) describes a high contrast customisation that is enabled outside of Firefox, in the settings of a user's operating system. Each of our major desktop operating systems has an OS HCM variant: - Windows: Settings > Accessibility > Increase Contrast > (select theme) > Apply - MacOS: System Preferences > Accessibility > Display > Increase Contrast - Linux: Settings > Themes > High Contrast The presence of an OS HCM is stored in `IntID::UseAccessibilityTheme`. --- ### Accessible Docs DocumentAccessibilityLifecycle (`accessible/docs/DocumentAccessibilityLifecycle.md`) # Document Accessibility Lifecycle ## 1. DocAccessible creation When a DocAccessible is created, it is initially empty. A DocAccessible can be created in one of several ways: ### Scenario 1: Accessibility service is already started, layout fires an a11y notification for a new document 1. The layout [PresShell gets initialized (PresShell::Initialize)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/layout/base/PresShell.cpp#1820). 2. As part of that, layout [inserts content from the root content object down](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/layout/base/PresShell.cpp#1885). 3. This [fires an accessibility insertion notification (nsAccessibilityService::ContentRangeInserted)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/layout/base/nsCSSFrameConstructor.cpp#6863). 4. That [gets the DocAccessible (DocManager::GetDocAccessible)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/nsAccessibilityService.cpp#463). 5. Because it doesn't exist yet, [the DocAccessible gets created (DocManager::CreateDocOrRootAccessible)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#62). ### Scenario 2: Accessibility service is already started, DOM loading completes for a new document For top level content documents, if the accessibility service is started, layout should fire an a11y notification, resulting in scenario 1 above. For child documents (e.g. in-process iframes), this might not happen because the container Accessible for the child document might not be created yet. In that case, we can't create a DocAccessible when the layout notification is fired. If the container Accessible is created when DOM loading completes for the child document, this scenario can occur. 1. [a11y::DocManager gets notified that the document has stopped loading (DocManager::OnStateChange)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#238). 2. It tries to get an existing DocAccessible, but it doesn't exist yet, so it [creates a DocAccessible (DocManager::CreateDocOrRootAccessible)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#395). ### Scenario 3: Accessibility service is already started, child document is reached while building accessibility tree for parent document Child document here refers to a child document in the same process; i.e. an in-process iframe or a parent process document such as an about: page. Note that scenario 1 or 2 could happen for a child document as well. 1. While building the accessibility tree for the parent document, an OuterDocAccessible is created (e.g. for a XUL browser or iframe). 2. The [OuterDocAccessible constructor gets the DocAccessible for the child document (DocManager::GetDocAccessible)](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/generic/OuterDocAccessible.cpp#56). 3. Because it doesn't exist yet, [the DocAccessible gets created (DocManager::CreateDocOrRootAccessible)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#62). ### Scenario 4: Accessibility service starts after top level document is loaded 1. When the accessibility service starts, it [initializes the ApplicationAccessible (ApplicationAccessible::Init)](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/base/nsAccessibilityService.cpp#1219). 2. As part of that, all documents are iterated. 3. For each top level document, [the DocAccessible is retrieved (DocManager::GetDocAccessible)](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/generic/ApplicationAccessible.cpp#130) and [thus created (DocManager::CreateDocOrRootAccessible)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#62). Scenario 3 would then apply for any child documents encountered while building the accessibility trees for these top level DocAccessibles. ### Scenario 5: Document gets focus before layout begins It is possible for a document to get focus before layout has begun and before DOM loading is complete. In that case, there will be a PresShell, but it will have no root frame. Despite this, it is necessary to create the document because otherwise, a11y focus would go nowhere while the document had DOM focus. 1. [a11y::FocusManager gets notified of a DOM focus change (FocusManager::NotifyOfDOMFocus)](https://searchfox.org/mozilla-central/rev/04dbb1a865894aec20eb02585aa75acccc0b72d5/accessible/base/FocusManager.cpp#126). 2. It gets the DocAccessible for the child document (DocManager::GetDocAccessible). 3. Because it doesn't exist yet, [the DocAccessible gets created (DocManager::CreateDocOrRootAccessible)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#62). ## 2. Initial tree creation 1. When a DocAccessible is created, it [creates a refresh observer (NotificationController)](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/generic/DocAccessible.cpp#368) which performs various processing asynchronously. 2. When the NotificationController is created, it [schedules processing for the next possible refresh tick](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/base/NotificationController.cpp#39). 3. Once a refresh tick occurs, [while there is not an interruptible reflow in progress](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/base/NotificationController.cpp#615) and there is an initialized PresShell, the DocAccessible's [initial update is triggered (DocAccessible::DoInitialUpdate)](https://searchfox.org/firefox-main/source/accessible/base/NotificationController.cpp#649). 4. For a top level document, the [DocAccessibleChild IPC actor is created](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/generic/DocAccessible.cpp#1752). See the section on IPC actor creation below. 5. The [DOM tree is walked and the accessibility tree is built for the document down (DocAccessible::CacheChildrenInSubtree)](https://searchfox.org/mozilla-central/rev/36f79bed679ad7ec46f7cd05868a8f6dc823e1be/accessible/generic/DocAccessible.cpp#1789). Note that the document might still have no layout frame if the PresShell still has no frame; see scenario 5 in DocAccessible creation above. Nevertheless, DoInitialUpdate must be called because otherwise, we wouldn't create the IPC actor, which would in turn mean remote documents in this state couldn't get a11y focus. ## 3. Child document binding Child document here refers to a child document in the same process; e.g. an in-process iframe or a parent process document such as an about: page. Child documents need to be a child of their OuterDocAccessible; e.g. the iframe. However, the child document might be ready before the parent document is. To deal with this: 1. When a DocAccessible is created for a child document (DocManager::CreateDocOrRootAccessible), it is [scheduled for binding to its parent (DocAccessible::BindChildDocument)](https://searchfox.org/mozilla-central/rev/1758450798ae14492ba28b695f48143840ad6c5b/accessible/base/DocManager.cpp#505). 2. NotificationController [does not handle any updates for child documents until they are bound to their parent](https://searchfox.org/mozilla-central/rev/1758450798ae14492ba28b695f48143840ad6c5b/accessible/base/NotificationController.cpp#638). 3. After the initial tree creation for the parent document, NotificationController [binds the document scheduled in 1)](https://searchfox.org/firefox-main/source/accessible/base/NotificationController.cpp#783). ## 4. IPC actor (DocAccessibleChild/Parent) creation ### Scenario 1: Top level document 1. As the first part of the DocAccessible's initial update (DocAccessible::DoInitialUpdate), if the document is a top level document, it [creates a DocAccessibleChild](https://searchfox.org/mozilla-central/rev/1758450798ae14492ba28b695f48143840ad6c5b/accessible/generic/DocAccessible.cpp#1757). - There is also a [code path to handle the case where the DocAccessibleChild has already been created](https://searchfox.org/firefox-main/source/accessible/generic/DocAccessible.cpp#1755). However, it doesn't seem like this should happen and code coverage information suggests that it doesn't. 2. It then [sends a message to the parent process to construct the DocAccessibleParent (BrowserChild::SendPDocAccessibleConstructor)](https://searchfox.org/firefox-main/source/accessible/generic/DocAccessible.cpp#1771). ### Scenario 2: Child document The [DocAccessibleChild for a child document is created](https://searchfox.org/firefox-main/source/accessible/base/NotificationController.cpp#909) when the child document is bound to its parent by NotificationController. There is also a [code path to handle the case where the DocAccessibleChild has already been created](https://searchfox.org/firefox-main/source/accessible/base/NotificationController.cpp#905). However, it doesn't seem like this should happen and code coverage information suggests that it doesn't. ## 5. Document load events ### Scenario 1: DocAccessible is already created, DOM loading completes 1. [a11y::DocManager gets notified that the document has stopped loading (DocManager::OnStateChange)](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/base/DocManager.cpp#238). 2. It [notifies the DocAccessible (DocAccessible::NotifyOfLoad](https://searchfox.org/firefox-main/source/accessible/base/DocManager.cpp#399), passing EVENT_DOCUMENT_LOAD_COMPLETE. 3. That [sets the eDOMLoaded LoadState](https://searchfox.org/mozilla-central/rev/4e87b5392eafe1f1d49017e76f7317b06ec0b1d8/accessible/generic/DocAccessible-inl.h#93) and mLoadEventType on the DocAccessible. 4. Something schedules NotificationController processing. This could be the initial update, an insertion, etc. 5. Because the DocAccessible has been marked as loaded, the initial tree has been built and all child documents are loded, [NotificationController calls DocAccessible::ProcessLoad](https://searchfox.org/firefox-main/source/accessible/base/NotificationController.cpp#815). 6. ProcessLoad [fires the EVENT_DOCUMENT_LOAD_COMPLETE event](https://searchfox.org/firefox-main/source/accessible/generic/DocAccessible.cpp#1841) as set in 3). ### Scenario 2: DocAccessible is created some time after DOM loading completed This can happen if the accessibility service is started late. It can also happen if a DocAccessible couldn't be created earlier because the PresShell or containre Accessible wasn't created yet. 1. The [DocAccessible is initialized (DocAccessible::Init)](https://searchfox.org/mozilla-central/rev/8db61933e64b13c4a0ae456bcaccbd86a519ccc5/accessible/generic/DocAccessible.cpp#359). 2. It [detects that DOM loading is already complete](https://searchfox.org/mozilla-central/rev/8db61933e64b13c4a0ae456bcaccbd86a519ccc5/accessible/generic/DocAccessible.cpp#379). 3. In response, it [sets the eDOMLoaded state and mLoadEventType on the DocAccessible](https://searchfox.org/mozilla-central/rev/8db61933e64b13c4a0ae456bcaccbd86a519ccc5/accessible/generic/DocAccessible.cpp#381). 4. Something schedules NotificationController processing. This could be the initial update, an insertion, etc. 5. Because the DocAccessible has been marked as loaded, the initial tree has been built and all child documents are loded, [NotificationController calls DocAccessible::ProcessLoad](https://searchfox.org/firefox-main/source/accessible/base/NotificationController.cpp#815). 6. ProcessLoad [fires the EVENT_DOCUMENT_LOAD_COMPLETE event](https://searchfox.org/firefox-main/source/accessible/generic/DocAccessible.cpp#1841) as set in 3). ### Suppression of document load events for parent process iframes Note that for documents loaded directly in the parent process, ProcessLoad won't fire a load event for a child document whose parent is still loading. This is old behavior which does not work in the content process and will probably be removed in future. See [bug 1700362](https://bugzilla.mozilla.org/show_bug.cgi?id=1700362). --- ### Accessible Docs GeckoViewThreadTopography (`accessible/docs/GeckoViewThreadTopography.md`) # GeckoView Thread Topography Unlike conventional Gecko, GeckoView utilizes two main threads in the parent process. A thread called the "UI" thread that runs the native Java event loop, and a "Gecko" thread that spawns an instance of Gecko. Note, this "Gecko" thread is considered the main thread in conventional Gecko and throughout the source is referred to as such. For example `NS_IsMainThread()` returns `true` when called on the Gecko thread. Android's accessibility API's entry point is the UI thread. The most common methods for an accessibility service to query and interact with Gecko have a return value and thus must be performed synchronously. For example [performAction()](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeProvider#performAction(int,%20int,%20android.os.Bundle)) and [createAccessibilityNodeInfo()](https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeProvider#createAccessibilityNodeInfo(int)). ## Thread Safety Concerns As a rule, every data structure and method in Gecko should be considered unsafe to access from GeckoView's UI thread. For example the default reference counting implementation is not thread safe and should not be used outside the Gecko thread. Cross-process messaging must be done from the Gecko thread as well. Since the accessibility consumer is in the UI thread we need to either call into the Gecko thread while blocking the UI thread, or make a limited subset of the accessibility API thread safe. We employ both methods for different types of content. ## In-Process Content Content that is rendered in the top-level process is rare and mostly consists of "about" pages that give insight to browser internals, like `about:support`. Since our Gecko accessibility API queries DOM and Layout, and includes many complex, thread-unsafe data structures, we call into the Gecko thread to retrieve what is needed and block the UI until we get a response from the Gecko thread. For example, to retrieve a "class name" enum that is calculated for a certain accessible the method will look something like this: ```cpp int SessionAccessibility::GetNodeClassName(int32_t aID) { int32_t classNameEnum = java::SessionAccessibility::CLASSNAME_VIEW; RefPtr self(this); nsAppShell::SyncRunEvent([this, self, aID, &classNameEnum] { if (Accessible* acc = GetAccessibleByID(aID)) { classNameEnum = AccessibleWrap::AndroidClass(acc); } }); return classNameEnum; } ``` ## Out-of-Process Content Most web content will be rendered in a child process. Historically, we would cache the accessible tree hierarchy and object roles in the parent process and use synchronous IPC to query individual objects for more properties. We are transitioning to a fully cached approach where all fields are either stored or calculated in remote proxy objects in the parent process. The "cache" in our definition is any data member associated with the remote `Accessible` or its subclasses, such as `mParent`, `mChildren` and `mCachedFields` in `RemoteAccessibleBase`, or `mAccessibles` in `DocAccessibleParent`. In addition to all those members the cache includes the accessible/id table in `SessionAccessibility`. The cache is initialized and modified exclusively by messages from the child process to the parent process. Since the cache is limited to our module and is relatively well scoped, it is possible to synchronize access to it and allow it to be consumed by the UI thread. ### Global Accessibility Thread Monitor We have global thread monitor that can be acquired by calling `nsAccessibilityService::GetAndroidMonitor()`. For example, if we were to retrieve the class name enum we would use an RAII wrapped monitor to exclusively access the cache: ```cpp int SessionAccessibility::GetNodeClassName(int32_t aID) { MonitorAutoLock mal(nsAccessibilityService::GetAndroidMonitor()); if (Accessible* acc = GetAccessibleByID(aID)) { return AccessibleWrap::AndroidClass(acc); } } ``` #### Gecko Thread Access As a rule, all incoming IPC messages (ie. all `DocAccessibleParent::Recv` methods) should hold the global monitor. This is because any `Recv` method may indirectly modify the cache, for example a certain event might invalidate or update a cached property. There are currently no deferred tasks that happen as a result of a `Recv` method, so holding the monitor at the start of these methods will assure that the cache is being read or written in a synchronized fashion. #### UI Thread Access All methods that are called in via JNI should be assumed are in the UI thread and should acquire the monitor, unless the are annotated with `@WrapForJNI(dispatchTo = "gecko")`. This assures us that they are synchronized with any potential modifications to the cache happening in the Gecko thread. --- ### Accessible Docs GuidelinesForNewContributors (`accessible/docs/GuidelinesForNewContributors.md`) # Guidelines for New Contributors Thank you for your interest in contributing to the Gecko accessibility module. This document provides some brief, high level guidelines to get you started. ## Local and Remote Accessibility Trees Accessibility clients communicate with Gecko's parent process, but web content is isolated in its own content processes. Therefore, in order for accessibility clients to access web content, the accessibility tree from each content process is cached in the parent process. See the [Architecture](Architecture.md) page for more details. This means that when writing patches to change what is exposed to accessibility clients, you need to ensure that: 1. The data is included in the cache sent to the parent process. This might already be the case if you are modifying an existing property, but it most likely won't be if you are adding something new. The cache is built in [`LocalAccessible::BundleFieldsForCache`](https://searchfox.org/firefox-main/rev/dab03896ede1413be148884e054b311767bcf1a0/accessible/generic/LocalAccessible.cpp#3538). 2. An event is fired when the data is changed, if appropriate. This is necessary both to update the parent process cache and to notify clients of the change. However, not all properties have associated events. See [the `EVENT_*` constants in nsIAccessibleEvent](https://searchfox.org/firefox-main/rev/dab03896ede1413be148884e054b311767bcf1a0/accessible/interfaces/nsIAccessibleEvent.idl#31) for the supported events. 3. A cache update is queued when the data is changed, if there is no associated event. See [`DocAccessible::QueueCacheUpdate`](https://searchfox.org/firefox-main/rev/dab03896ede1413be148884e054b311767bcf1a0/accessible/generic/DocAccessible.h#114). 4. The data can be queried via both `LocalAccessible` and `RemoteAccessible` methods. ## Tests Ideally, any change to code in this module should be covered by automated tests. To run a test directory or file, use the command: `./mach test accessible/tests/path` ### Browser Tests Browser tests are located in `accessible/tests/browser`. This is our preferred test suite, as it supports testing across multiple processes, is supported by our linters, allows for OS specific testing, etc. Any new tests should be added to this test suite, in the folder which best approximates their behavior. The one exception is changes related to XUL, as XUL can only run in the parent process. Test tasks are defined using [`addAccessibleTask`](https://searchfox.org/firefox-main/rev/ad5f057320ecc6b934dfa1e3ec361f87712806cc/accessible/tests/browser/shared-head.js#694). `addAccessibleTask` can be given a markup snippet (normally HTML) to load. You also pass it an async test function, which should be named to make debugging easier, though many older tests have unnamed functions. The same test can then optionally be run in a top level remote document (`{ topLevel: true }`), in the parent process (`{ chrome: true }`), in a remote in-process iframe (`{ iframe: true }`) and an out-of-process iframe (`{ remoteIframe: true }`). This makes it easy to test both `LocalAccessible` and `RemoteAccessible` using the same code. Tests in `accessible/tests/browser/atk` and `accessible/tests/browser/windows` exercise OS specific APIs. Like all browser tests, they are primarily written in JS, but the `runPython` function is used to execute snippets of Python code in a separate process, simulating a real accessibility client. ATK tests use the pyatspi library to make AT-SPI calls. Windows tests use the Python ctypes and comtypes libraries to make MSAA, IAccessible2 and UI Automation calls. Tests in `accessible/tests/browser/telemetry` and `accessible/tests/browser/performance` are non-standard. Please do not use them as examples for general test writing. If you believe your work requires a telemetry or performance test, please reach out to :morgan on matrix or bugzilla. ### Mochitests Mochitests are located in `accessible/tests/mochitest`. This is an older, legacy test suite which only supports testing `LocalAccessible` in a single process. However, because of the massive number of tests here, many have not yet been ported to browser tests. Mochitests are also necessary for testing XUL accessibility. New tests should not be added in this directory except for those related to XUL. However, any failures introduced in these tests must still be fixed. ### Crash Tests There is another suite of tests located in `accessible/tests/crashtests`. However, this test suite is unreliable and thus legacy. Because the accessibility module runs asynchronously from DOM, it is difficult to guarantee that any potential crash is hit before the test exits. New tests should not be added in this directory. To verify a crash fix, you should instead write a browser test as outlined above. `addAccessibleTask` explicitly waits until the document's accessibility tree has been built before running the test function. If the crash was caused by a change to the accessibility tree, you can also wait for a specific accessibility event (or events) to ensure the change has been processed by the accessibility code before the test exits. --- ### Accessible Docs HCMCSSChecklist (`accessible/docs/HCMCSSChecklist.md`) # HCM CSS Self-Check Guide Use these checks when writing or reviewing CSS that targets high contrast mode (HCM) or Increase Contrast (IC) users. For background on the media queries and colour systems referenced here, see the documentation on [HCM Media Queries](HCMMediaQueries.md) and [Colors and High Contrast Mode](ColorsAndHighContrastMode.md). You should read and understand these documents before moving forward with the checks below. Note: These checks are ordered intentionally, please complete them in order. --- ## Architecture ### Check 1: Have I identified all places where HCM overrides are necessary? **When writing HCM-specific CSS, our goal is to write as little CSS as possible.** Our design system is a huge help here. The design system token layer system (`toolkit/themes/shared/design-system/dist/tokens-shared.css`) includes three cascade layers — `tokens-foundation`, `tokens-prefers-contrast`, and `tokens-forced-colors` — that automatically override token values in contrast modes. Any variable whose value is (or cascades to) a design system token gets HCM adaptation for free. In addition to the `.css` files above, you can view the [design system tokens table here](https://firefoxux.github.io/firefox-desktop-components/?path=/story/docs-tokens-table--default). Make sure to select "Chrome" or "Content" as is appropriate for your work. **Variables that use design system tokens generally do NOT need explicit `forced-colors` overrides.** For example: ```css /* These adapt automatically in HCM — no override needed */ color: var(--button-text-color); /* → ButtonText in forced-colors */ background: var(--button-background-color); /* → ButtonFace in forced-colors */ border-color: var(--button-border-color); /* → ButtonText in forced-colors */ ``` **Variables with raw custom values DO need explicit `forced-colors` overrides.** These are those holding hardcoded hex colors, `light-dark()` calls, `rgba()` values, gradients, or references to brand palette tokens (like `--color-violet-80`) which do not resolve to system colors. ```css /* These do NOT adapt — explicit forced-colors overrides required */ --my-bg: light-dark(var(--color-gray-0), var(--color-gray-80)); --my-accent: var(--color-violet-90); --my-gradient: linear-gradient(83deg, #5119dc 0.73%, var(--color-violet-30) 98.05%); --my-hover-bg: rgba(191, 143, 204, 0.2); ``` **Audit step:** Scan all CSS custom properties in your `:root` / `:host` block. For each one, ask: does this value ultimately resolve to a [CSS system color keyword](https://www.w3.org/TR/css-color-4/#css-system-colors) in `tokens-forced-colors`? If yes, verify the token is appropriate (other checks below still apply). If no, it needs an override. Note that only the keywords listed in the spec are valid system colors — values like `inherit`, named colors like `teal`, or `transparent` are not CSS system colors and will not adapt correctly in HCM. If your component uses no design system tokens at all, pay particularly close attention to ensuring every color property has an explicit override. --- ### Check 2: Am I using the right media query for the right audience? `forced-colors` and `prefers-contrast` are not interchangeable. You can read more about their differences, with examples, in our [HCM Media Query documentation](HCMMediaQueries.md). | Query | Fires for | |---|---| | `forced-colors: active` | Windows HCM, Firefox HCM | | `prefers-contrast: more` | macOS Increase Contrast **and** most `forced-colors` users (contrast ratio > 7:1) | **It is important to note:**: most HCM users also trigger `prefers-contrast`. A bare `@media (prefers-contrast)` block applies to *both* IC and HCM users. If that is not your intent, you must use a more specific media query. macOS "Increase Contrast" and Linux HCM alone do **not** trigger `forced-colors`. When a component needs distinct treatment for IC and HCM users, the recommended split is: ```css :root { @media (prefers-contrast) { /* Applies to ALL contrast users (IC + HCM). Safe to use here: borders, border-width increases. Do NOT use CSS system color keywords here — IC users keep the default Firefox color scheme. */ } @media (prefers-contrast) and (not (forced-colors)) { /* IC users only. Keep original colors. You may optionally improve a foreground color for readability here, but only using non-system colors. */ } @media (forced-colors) { /* HCM users only. Design system tokens that resolve to CSS system colors are required here. Do not use system color keywords directly. */ } } ``` A rule that belongs in both IC and HCM (e.g. removing child outlines from a button with both an icon and a label so only the button wrapper shows a focus ring) should use bare `@media (prefers-contrast)` without the `not (forced-colors)` exclusion. **IC-specific color improvements:** IC users on macOS keep the default Firefox color scheme and should not receive a reduced-palette experience. If a foreground color modification on a control could meaningfully improve contrast for IC users, it can go in the `prefers-contrast and (not (forced-colors))` block — but only using non-system color tokens. There are currently no design system tokens specifically for IC color improvements beyond borders. If you are uncertain which media query applies to your use case, reach out to the accessibility team in #Accessibility for guidance. --- ### Check 3: Am I overriding tokens in the correct places? Two main rules govern how HCM overrides should be written: **Nest media queries inside `:root` / `:host`, not on specific elements.** Do not create a separate top-level `@media` rule wrapping a new `:root` declaration. Nesting inside the existing block keeps all variable definitions for a component in one place and makes the full cascade visible at a glance. ```css /* WRONG — separate top-level @media rule instead of nesting inside :root */ :root { --my-wrong-text-color: rgb(123, 123, 123); } @media (forced-colors) { :root { --my-wrong-text-color: var(--text-color-design-system-token); } } /* WRONG — @media nested at element level instead of in :root */ .myWrongClass { color: var(--my-wrong-text-color); @media (forced-colors) { color: var(--text-color-design-system-token); } } /* CORRECT */ :root { --my-bg: #ffffff; --my-text-color: rgb(123, 123, 123); @media (forced-colors) { --my-bg: var(--background-design-system-token); --my-text-color: var(--text-color-design-system-token); } } .myClass { background-color: var(--my-bg); color: var(--my-text-color); } ``` **Override the existing variable; do not introduce new HCM-specific ones.** Do not create `-hcm-`-suffixed variables or other HCM-specific names. Overriding the existing variable means the element rule can stay simple and clean. ```css /* WRONG — introduces an HCM-specific variable; --my-btn-text-color still resolves to the light-dark() value in forced-colors, so the element must also carry its own override */ :root { --my-wrong-btn-text-color: light-dark(var(--color-violet-80), var(--color-white)); @media (forced-colors) { --my-wrong-btn-hcm-text-color: var(--button-text-color); } } .myWrongBtn { color: var(--my-wrong-btn-text-color); /* still unresolved in forced-colors */ @media (forced-colors) { color: var(--my-wrong-btn-HCM-text-color); /* element-level override now required */ } } /* CORRECT — element-level CSS is unchanged; HCM is handled entirely at :root */ :root { --my-btn-text-color: light-dark(var(--color-violet-80), var(--color-white)); @media (forced-colors) { --my-btn-text-color: var(--button-text-color); } } .myBtn { color: var(--my-btn-text-color); } ``` --- ## Token Selection These checks apply when you're writing `forced-colors` overrides. They ensure you pick tokens that are correct, consistent, and safe across all HCM themes. --- ### Check 4: Are my foreground/background pairs correct, and am I mapping them semantically? When choosing tokens for an element in HCM, identify the semantic role of the element (interactive control, selected item, static page content, link text, disabled content), find the appropriate token family in the [tokens table](https://firefoxux.github.io/firefox-desktop-components/?path=/story/docs-tokens-table--default), then use that family consistently across background, text, and border. Do not mix component-specific tokens with generic ones, or tokens from unrelated components. ```css /* WRONG — mixing component families */ --my-wrong-bg: var(--button-background-color-primary); --my-wrong-text: var(--text-color); /* generic, not button family */ --my-wrong-border var(--border-color-interactive); /* evaluates to a button color, but a better match exists */ /* WRONG — mixing component family types (button general, primary button, ghost button) */ --my-wrong-bg: var(--button-background-color); --my-wrong-text: var(--button-text-color-primary); --my-wrong-border: var(--button-border-color-ghost); /* CORRECT — same family throughout */ --my-bg: var(--button-background-color-primary); --my-text: var(--button-text-color-primary); --my-border: var(--button-border-color-primary); ``` **Token families inside our design system tokens set have already been audited for HCM compliance**. By sticking with one family, you're guaranteed to avoid pair mismatches. #### What is a pair mismatch? CSS system colors come in guaranteed-contrast pairs. Contrast is only guaranteed *within* a pair. Mixing a foreground from one pair with a background from another removes that guarantee and can produce unreadable combinations on some themes. Do not use CSS system color keywords directly. Use design system tokens — they resolve to the correct system colors through the `tokens-forced-colors` layer. Consult the [Firefox design system tokens table](https://firefoxux.github.io/firefox-desktop-components/?path=/story/docs-tokens-table--default) to identify which tokens are available and what they resolve to in forced-colors mode. --- ### Check 5: Are my tokens semantically appropriate for the property they set? A token named `background-color` should only be used to set backgrounds. A token named `text-color` should only be used for text (foreground). Do not use a background token to set a text color variable, even if it happens to resolve to the right system color in a specific theme. ```css /* WRONG — background token used to set text color */ --my-wrong-btn-text: var(--button-background-color-primary); /* In HCM this resolves to ButtonText via --color-accent-primary, but the token name says "background" and the usage says "text" */ /* CORRECT */ --my-btn-text: var(--button-text-color-primary); /* This also resolves to ButtonText, and the token name is appropriate and consistent */ ``` Beyond property type, also verify that the token's component matches your use case. When multiple tokens resolve to the same CSS system color, they are not interchangeable — prefer the one whose name most accurately describes the element being styled. A token that resolves correctly but names the wrong component is still a semantic mismatch, and makes the code harder to audit in future. ```css /* WRONG — despite being a background token, this token describes a list item; it is not appropriate for a button background */ --my-wrong-button-background: var(--background-color-list-item); /* CORRECT */ --my-button-background: var(--button-background-color); ``` If no token exists whose name is a good semantic match for your use case, that is worth noting — it may indicate the design system doesn't yet cover your component. Please reach out to the accessibility team directly in #Accessibility for guidance. --- ### Check 6: Are my tokens from matching interaction states? Background, text, and border tokens for a given state (hover, active, focus, selected, current, etc.) must all carry the same state suffix. Mixing states produces pairs that may be unreadable on some HCM themes — hover backgrounds and default-state text colors can resolve to the same system color, making content invisible. ```css /* WRONG — hover-state background paired with default-state text */ --my-btn-bg: var(--button-background-color-hover); /* hover state */ --my-wrong-btn-text: var(--button-text-color); /* default state ← mismatch */ /* CORRECT — both hover state */ --my-btn-bg: var(--button-background-color-hover); --my-btn-text: var(--button-text-color-hover); ``` --- ### Check 7: Does any information rely on color alone to communicate meaning? HCM reduces the available palette to a small set of system colors. If any information in the component is conveyed by color alone, it will be lost in HCM. This is also a violation of our general a11y guidelines and [WCAG](https://www.w3.org/TR/WCAG22/#use-of-color). Check that: - **Selected states remain visually distinct** from unselected states, even when both use system colors. A selected item should use the selection token pair rather than only differing from its neighbor by hue or opacity. - **Disabled/inactive states remain distinct** from enabled states. Use disabled tokens (ex. `--button-text-color-disabled`) for disabled foreground rather than relying on reduced opacity. - **Status or severity** (e.g. error, warning, success) is not indicated only by color. If an icon or label is the only indicator, ensure it is present and its text/icon uses an appropriate foreground token. ```css /* WRONG — selected state differs from default only by color, which may become indistinguishable across HCM themes */ :root { @media (forced-colors) { --my-wrong-item-text: var(--button-text-color); --my-wrong-item-bg: var(--button-background-color); --my-wrong-item-bg-selected: var(--button-background-color); /* ← no distinction */ /* no selected foreground color specified */ } } /* CORRECT — selected state uses the dedicated selection token pair */ :root { @media (forced-colors) { --my-item-text: var(--button-text-color); --my-item-bg: var(--button-background-color); --my-item-bg-selected: var(--color-accent-primary-selected); --my-item-text-selected: var(--text-color-accent-primary-selected); } } ``` --- ### Check 8: Have I verified that my chosen tokens actually have `forced-colors` variants? Not every design system token has an entry in the `tokens-forced-colors` layer. A token without a forced-colors override resolves to its foundation or `tokens-prefers-contrast` value in HCM, which may be a non-system color. Before using a token in a `forced-colors` block, look it up in the [Firefox design system tokens table](https://firefoxux.github.io/firefox-desktop-components/?path=/story/docs-tokens-table--default). Ensure your chosen token has an entry in the High Contrast Mode column. If it does not, reach out to the accessibility team in #Accessibility for guidance. In addition, you should build and test your patch on Windows when possible. Testing chrome patches in Firefox using FF HCM will not produce the same results as testing on Windows with Windows HCM enabled. Please read about the differences between FF HCM and Windows HCM in the [Colors and High Contrast Mode in Firefox](ColorsAndHighContrastMode.md) documentation. --- ### Check 9: Do ghost components have appropriate tokens set in HCM? The design system's `--button-*-ghost-*` tokens already have `forced-colors` overrides that add a visible border in the default state (ghost buttons are borderless by default) and override hover and active states. If a component uses ghost styling in non-HCM, do not override the ghost tokens to non-ghost values in the `forced-colors` block — that creates a state mismatch between modes. Let the ghost tokens cascade naturally through the design system. If you've chosen custom color values for your ghost component, override those styles with ghost tokens in HCM. ```css /* WRONG — non-HCM uses ghost state, forced-colors switches to default state */ :host { --my-wrong-ghost-btn-bg: var(--button-background-color-ghost); @media (forced-colors) { --my-wrong-ghost-btn-bg: var(--button-background-color); /* ← this will remove the ghost stylinlg, causing a state mismatch */ } } /* CORRECT */ :host { --my-ghost-btn-bg: var(--button-background-color-ghost); } /* ALSO CORRECT */ :host { --my-ghost-btn-bg: color-mix(in srgb, --button-background-color, #fff, 20%); @media (forced-colors) { --my-ghost-btn-bg: var(--button-background-color-ghost); } } ``` --- ## Elements and Features These checks address specific UI elements and CSS features that require particular handling in contrast modes. --- ### Check 10: Am I adding borders to all elements that require them, for all contrast users? Controls, sidebars, toolbars, dialogs, cards, and sections require a solid border of at least 1px in contrast modes. Borders provide visual separation where color alone is insufficient, and are important for both IC and HCM users. Ensure adequate padding around the border so it does not reduce legibility of the content inside. In HCM, border tokens are supplied by our design system for most token family types and states. In Increase Contrast (IC), border color should match the component's foreground color (often with `currentColor`). If the same border is appropriate for both IC and HCM, set it in a bare `@media (prefers-contrast)` block. The `forced-colors` block's value will override it for HCM users due to source order: ```css :root { --my-item-border-width: 0px; --my-item-border-color: transparent; @media (prefers-contrast) { /* 1px solid border using the component's foreground color, for all contrast users */ --my-item-border-width: var(--border-width); --my-item-border-color: currentColor; } @media (forced-colors) { /* Override to use the token matching the component family */ /* Keep the border width token above, as it is appropriate for both modes */ --my-item-border-color: var(--button-border-color); } } .my-element { border: var(--my-item-border-width) solid var(--my-item-border-color); padding: var(--space-small); } ``` --- ### Check 11: Have I removed or replaced visual effects that don't belong in HCM? Blur effects, drop shadows, semi-opaque surfaces, and gradient backgrounds must be removed or replaced with solid equivalents in HCM. These effects rely on color blending that is meaningless or visually broken against a forced system-color palette. | Effect | HCM replacement | |---|---| | Drop shadow | 1px solid border using the component's foreground color token | | Gradient background | Solid background using the appropriate `background-color` token | | Semi-opaque surface | Solid background (`var(--background-color-box)`) with `opacity:1;`| | Blur | Remove entirely | ```css :root { --my-shadow: drop-shadow(-16px -16px red); --my-gradient: linear-gradient(135deg, var(--color-violet-50), var(--color-blue-50)); --my-overlay-bg: rgba(0, 0, 0, 0.5); --my-border-width: 0px; --my-custom-opacity: 0.1; @media (forced-colors) { --my-shadow: none; --my-gradient: none; --my-overlay-bg: var(--background-color-canvas); --my-border-width: var(--border-width); /* border replaces shadow */ --my-custom-opacity: 1; } } ``` --- ### Check 12: Have I handled SVG colors correctly for HCM? SVGs fall into two categories with different HCM requirements: **Decorative SVGs**, or SVGs that duplicate information already available in an accessible format (e.g. a triangle icon next to a text label starting with "Warning"). These SVGs may use colors outside the HCM palette. No override is needed. **Informational or interactive SVGs** — those that uniquely communicate information or function as controls — must use only HCM palette colors. An example of an SVG in this category is the down-chevron on a custom accordian element. Generally, button tokens are appropriate when these items are interactive and traditional background/text tokens are appropriate when they are static. These components should also gain borders in HCM. ```css /* Interactive icon SVG — must adapt in HCM */ :root { --my-chevron-fill: var(--color-violet-60); --my-chevron-stroke: var(--color-violet-80); @media (forced-colors) { --my-chevron-fill: var(--button-background-color); --my-chevron-stroke: var(--button-border-color); } } ``` --- ### Accessible Docs HCMMediaQueries (`accessible/docs/HCMMediaQueries.md`) # High Contrast Mode (HCM) Media Queries Firefox supports both the `prefers-contrast` and `forced-colors` media queries. These queries detect a user's display settings (in the browser and/or in their OS), and allow authors to adjust content styling accordingly. These queries are not interchangeable, and we should be intentional about using one or the other (or both!) when designing for accessibility. ## What activates these queries? ### Forced Colors The `forced-colors` media query has two values: `active` and `none`. The resolved value of this media query is determined by the browser based on user settings (OS and Firefox). * The `none` state indicates documents can use any colors to render content. * The `active` state indicates a user has OS or browser settings that limit the color palette available to the User Agent. In Firefox's default configuration, the `active` state is triggered when a user has enabled Windows High Contrast Mode or [Firefox High Contrast Mode](https://firefox-source-docs.mozilla.org/accessible/ColorsAndHighContrastMode.html#the-colors-dialog) (FF HCM). Both of these forced-colors modes offer users a limited amount of color customisation. In Windows, users can override seven colors, and with Firefox High Contrast Mode users can override four. MacOS's "Increase Contrast" setting does **not** trigger `forced-colors: active` because it does not limit the color palette available to UA's. > **NOTE:** MacOS's "Increase Contrast" setting **will** trigger `forced-colors: active` (in non-chrome web content) if it is enabled in combination with FF HCM's "Only with High Contrast Themes" option. This is also true on Linux. Because [FF HCM defaults to "Never" on non-Windows platforms](https://searchfox.org/mozilla-central/rev/896042a1a71066254ceb5291f016ca3dbca21cb7/modules/libpref/init/StaticPrefList.yaml#1195-1199), enabling "Increase Contrast" or Linux High Contrast Themes alone will not trigger `forced-colors: active`. Similarly, if a user disables FF HCM while Win HCM is enabled, `forced-colors` (in content) will evaluate to `none`. #### CSS System Colors Colors that are overridden by the forced-colors modes list above are inherited into the browser's [CSS System Colors](https://www.w3.org/TR/css-color-4/#css-system-colors). Designers must use these colors exclusively in their designs when designing for forced-colors modes. CSS System Colors are intended to be used in pairs: for example the `ButtonFace` and `ButtonText` colors should be used together to create styling for interactive controls. The full pairings are listed in the [system color pairings](https://www.w3.org/TR/css-color-4/#system-color-pairings) section of the CSS spec. Mozilla has additional design guidance for using CSS System Colors in our [HCM Design Guide](https://wiki.mozilla.org/Accessibility/Design_Guide). You can also check out our other docs to [learn more about color overriding](https://firefox-source-docs.mozilla.org/accessible/ColorsAndHighContrastMode.html). ### Prefers Contrast The `prefers-contrast` media query has four values: `more`, `less`, `custom`, and `no-preference`. * The `more` state is triggered when a user has macOS's "Increase Contrast" setting enabled, or when a forced-colors mode is active **and** the ratio between a user's [chosen foreground and background](https://searchfox.org/mozilla-central/rev/655f49c541108e3d0a232aa7173fbcb9af88d80b/layout/style/PreferenceSheet.cpp#123-126) is higher than 7:1. This check is done [in our style system](https://searchfox.org/mozilla-central/rev/655f49c541108e3d0a232aa7173fbcb9af88d80b/layout/style/nsMediaFeatures.cpp#287-308). * The `less` state is triggered when a forced-colors mode is active and the foreground/background ratio is less than 4.5. * When a forced-colors mode is enabled with a ratio between these two values, we return `custom`. * Otherwise, if no forced-colors mode is active, and macOS's "Increase Contrast" is off, the media query resolves to `no-preference`. ## So what do I use? Generally, this boils down to which operating systems you want your styling to apply to. In the past, we've often written code to target _all_ platforms within `prefers-contrast` blocks because the kinds of changes we make to target forced-colors mode also benefit "Increase Contrast" users on macOS; they allow system colors to propagate to the UA. The palette that macOS supplies when "Increase Contrast" is enabled is _also_ inherited to CSS System Colors, and may offer improvements over the standard palette for a design. It is still possible that changes made for forced-colors modes benefit "Increase Contrast" users, however we strongly encourage developers to consider whether diversifying our designs for these modes provides better UX. On macOS, we aren't limited to the OS palette. Instead of modifying a design to use fewer colors, we can simply increase the contrast ratio of the existing colors to 7:1 to satisfy [the enhanced contrast criterion of Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-enhanced.html) for better accessibility. Consider the following designs. Standard UX on macOS: UX with increased contrast of existing colors on macOS: Changes present in this example belong in a `prefers-contrast: more` block. This is **assuming these changes are appropriately overridden in the cascade for `forced-colors: active` users**. If they are not overridden, an additional query like `@media (-moz-platform: macos)` or `.. and (not (forced-colors))` should be combined with `prefers-contrast: more` to ensure these changes only apply to macOS. For users who prefer less contrast, we can supply colors that lower the contrast ratios in the existing design and encase those changes in a `prefers-contrast: less` block. UX with limited color palette in FF HCM on macOS: In forced-colors modes, we require that designs reduce their palettes for compatibility. To accomplish this, we use CSS System Colors instead of the original design colors. This allows the overridden palette to "show through", since colors from the various forced-colors modes are inherited into CSS System Colors. It is possible that using CSS System Colors also increases contrast for users on macOS, but this more drastically changes the design at hand, and can detract from the overall user experience for users who are simply looking for more contrast. Designers should consider the additional guidelines on border use, removing gradients, etc. in our [HCM Design Guide](https://wiki.mozilla.org/Accessibility/Design_Guide). > **NOTE:** Firefox's chrome style sheets are subject to different rules than web-author style sheets. Firefox's chrome style sheets (including those in our `about:` pages) are not prevented from using colors that aren't system colors, even if a forced colors mode is enabled. In webpages, however, Firefox forces CSS System Colors regardless of the author's original specification. This is a safety mechanism to ensure pages render appropriately even if no `@media (prefers-contrast)` or `@media (forced-colors)` styling was specified. To avoid this overriding, web authors can use the [forced-color-adjust: none;](https://developer.mozilla.org/en-US/docs/Web/CSS/forced-color-adjust) CSS property. ## Writing Maintainable Frontend Code Where possible, we prefer color overriding for `prefers-contrast` and `forced-colors` take place in one block at the `root` level rather than in many blocks on an element-by-element basis. We encourage developers to use [design systems tokens](https://searchfox.org/mozilla-central/rev/c130c69b7b863d5e28ab9524b65c27c7a9507c48/toolkit/themes/shared/design-system/tokens-shared.css) with semantic naming when overriding. Consider the following. ```text :root { --page-background: #cccccc; --page-text-color: #000000; @media (forced-colors) { --page-background: Canvas; --page-text-color: CanvasText; } } body { color: var(--page-text-color); background-color: var(--page-background); } ``` Here, we've defined one set of color variables on `:root` and subsequently overridden them in a `forced-colors` block. We don't need to re-write the styling for `body` within our media query because the vars it references will correctly adapt when `forced-colors` is active. Though `forced-colors` overriding doesn't happen in Firefox chrome style sheets, our style system _does_ force all instances of `transparent` to the [default color](https://searchfox.org/mozilla-central/rev/655f49c541108e3d0a232aa7173fbcb9af88d80b/servo/components/style/properties/cascade.rs#468-481) for a color attribute (usually `CanvasText`). This allows us to specify styles that appear only in forced-colors mode without an additional CSS keyword. It is also sometimes beneficial to define vars at the `:root` level with an initial value (eg. `transparent`, `0px`, `none`) so the vars exist for HCM overriding later (see: `--dialog-border-width`). ```text :root { /* ... */ --dialog-background: #ffffff; --dialog-color: #bbbbbb; --dialog-border-color: transparent; --dialog-border-width: 0px; @media (forced-colors) { /* ... */ --dialog-background: Canvas; --dialog-color: CanvasText; /* No override for --dialog-borer-color, since it'll become * CanvasText when HCM is enabled, which matches the HCM spec. */ --dialog-border-width: 1px; } } .dialog { color: var(--dialog-color); background-color: var(--dialog-background); border: var(--dialog-borer-width) solid var(--dialog-border-color); } /* ... */ ``` In general, it is best to do overriding at the `:root` level, even if additional variables are required. It is _not_ recommended to do overriding on a class-by-class or element-by-element basis, like below: ```text :root { /* ... */ --button-background: #ffffff; --button-text-color: #bbbbbb; @media (forced-colors) { /* ... */ --button-background: ButtonFace; --button-text-color: ButtonText; --button-border-color: var(--button-text-color); } } @media (forced-colors) { /* BAD: These rules are generic and should be outside of a @media block */ .destroyButton { color: var(--button-text-color); background-color: var(--button-background); border: 1px solid var(--button-border-color); } } @media (not (forced-colors)) { /* BAD: Element-level styling should not be placed in media query blocks. * See "Scoping token overrides with @media (not (forced-colors))" below * for when this pattern IS appropriate. */ .destroyButton { color: var(--light-grey-20); background-color: var(--red-60); } } /*...*/ ``` ## Scoping token overrides with `@media (not (forced-colors))` When you introduce a custom override for a CSS variable that **already has a `@media (forced-colors)` value in the design system token layer**, wrapping your override in `@media (not (forced-colors))` prevents it from replacing that value. When forced-colors is active, the scoped declaration does not apply at all, leaving the token layer's system-color value as the only one in effect — no extra forced-colors handling required. Consider a variable that already has a forced-colors override in the token layer: ```css :root { --page-background: #f0f0f0; @media (forced-colors) { --page-background: Canvas; } } ``` A component author later adds a dark-mode-aware override: ```text /* BAD: replaces the token layer's Canvas value for forced-colors users */ :root { --page-background: light-dark(#f0f0f0, #1a1a1a); } /* GOOD: only applies when forced-colors is not active, so forced-colors * users still get the Canvas value from the token layer above */ @media (not (forced-colors)) { :root { --page-background: light-dark(#f0f0f0, #1a1a1a); } } ``` When choosing between `@media (not (forced-colors))` and `@media (not (prefers-contrast))` you need to consider a few things: * Do defaults exist for the tokens you're overriding in _both_ the prefers-contrast layer and the forced-colors layer? Or are defaults only specified in a single layer? Remember: the goal of this override strategy is to reveal the defeault token values. * Do your new token values increase contrast? If so, they could be more valuable to `prefers-contrast` users than the existing token defaults. You should consider exempting `forced-colors` users only. In most cases, `(not (forced-colors))` is the right choice: it leaves the existing token layer's forced-colors handling in effect, while users who have only a contrast preference (and no active forced-colors mode) continue to benefit from non-system-color visual enhancements. ## Putting it all together Let's walk through an example on this sample website. The majority of our site styling is done via color overriding on the root block. ```css :root { /* General */ --background: #202124; --color: #cccccc; --border-color: transparent; --border-size: 0; --table-background: #303134; /* Note */ --note-background: gold; --note-color: var(--table-background); --note-opacity: .7; /* General Controls */ --control-background: gray; --control-color: var(--color); --control-border-size: var(--border-size); --control-border-color: var(--border-color); /* Destructive Button */ --destructive-button-background: tomato; --destructive-button-color: var(--table-background); } ``` How might we adapt this website for users who prefer increased contrast? What about for users with forced colors? Let's start with users who prefer increased contrast. We might decide to make the background and foreground easier to read by making the foreground text lighter, increasing the contrast ratio. We might also remove the note's opacity and darken its text color. We don't need to remove the note's golden background, since prefers-contrast doesn't require a reduced color palette. ```text :root { /* ... */ @media (prefers-contrast) and (not (forced-colors)) { /* General */ --color: white; /* Note */ --note-color: black; --note-opacity: 1; /* ... */ } } ``` To address these same issues in forced-colors mode, we should replace the colors with the semantically appropriate system color. Unlike our work in the `prefers-contrast` block above, we do need to modify the note's background, since `gold` is not a system color. We might end up with something like this: ```text :root { /* ... */ @media (forced-colors) { /* General */ --background: Canvas; --color: CanvasText; --table-background: var(--background); /* Note */ --note-background: var(--background); --note-color: var(--color); --note-opacity: 1; /* ... */ } } ``` After this change, you'll notice our page background, table background, and note background all share the same color. This makes them difficult to differentiate. To address this, we can add a contrasting border and override the previously transparent `--border-color` variable and its corresponding `--border-size`. This var applies to content areas but not controls. ```text :root { /* ... */ @media (forced-colors) { /* General */ --background: Canvas; --color: CanvasText; --border-color: var(--color); --border-size: 1px; --table-background: var(--background); /* Note */ --note-background: var(--background); --note-color: var(--color); --note-opacity: 1; /* ... */ } } ``` Next, let's look at the controls this page uses for the web form. We've got an input, a checkbox, a submit button, and a clear button. In the prefers-contrast case, we should ensure the controls contrast from the background as much as possible. It's possible to do this via color alone, but it can help to add borders for additional contrast. Here, again, we don't need to get rid of the clear button's `tomato` background, but we can update it to something brighter. ```text :root { /* ... */ @media (prefers-contrast) and (not (forced-colors)) { /* ... */ /* General Controls */ --control-background: color-mix(in srgb, gray, lightgray); --control-color: black; --control-border-size: 1px; --control-border-color: gray; /* Destructive Button */ --destructive-button-background: red; --destructive-button-color: white; /* ... */ } } ``` Finally, let's style the page's controls for `forced-colors`. Unlike in prefers-contrast, we can't use color to differentiate between the submit button and the clear form button -- both should inherit from our button CSS system colors. ```text :root { /* ... */ @media (forced-colors) { /* General */ --background: Canvas; --color: CanvasText; --border-color: var(--color); --border-size: 1px; --table-background: var(--background); /* Note */ --note-background: var(--background); --note-color: var(--color); --note-opacity: 1; /* General Controls */ --control-background: ButtonFace; --control-color: ButtonText; --control-border-color: ButtonText; /* Destructive Button */ --destructive-button-background: var(--control-background); --destructive-button-color: var(--control-color); } } ``` If we wanted to make the submit button stand out as a primary button, we could invert the styling on that button in particular. Something like: ```text :root { /* ... */ @media (forced-colors) { /* General */ --background: Canvas; --color: CanvasText; --border-color: var(--color); --border-size: 1px; --table-background: var(--background); /* Note */ --note-background: var(--background); --note-color: var(--color); --note-opacity: 1; /* General Controls */ --control-background: ButtonFace; --control-color: ButtonText; --control-border-color: ButtonText; /* Destructive Button */ --destructive-button-background: var(--control-background); --destructive-button-color: var(--control-color); } #submit { background: var(--control-color); color: var(--control-background); border: var(--control-border-size) solid currentColor; } } ``` Now we've got a site that functions in multiple HCM scenerios :) Visit the live site with HCM or Increase Contrast enabled to test it for yourself. A few takeaways: * `prefers-contrast` and `forced-colors` are not mutually exclusive. If you write two independent `forced-colors` and `prefers-contrast` media query blocks, they'll both apply when FF HCM is enabled (assuming your foreground/background contrast ratio is high, which it is by default). Adding an `and (not (forced-colors))` clause to your `@media (prefers-contrast)` declaration can help make the two blocks distinct if you'd like mac-centric styling in one and `forced-colors` styling in the other. * `prefers-contrast` requires specific, case-by-case overriding, whereas `forced-colors` is largely about inheretince. In the former, page regions that are differentiated with color should stay that way (albeit with more contrasting colors). In `forced-colors` all page regions that aren't interactive should use `Canvas`/`CanvasText` and rely on borders for distinction. Once you've set `--background: Canvas;` at the root level, for ex. subsequent background vars should inherit from it. * Where possible, aim to do overriding at the `:root` level using CSS variables, this makes it easier to update code in the future. --- ### Accessible Docs HCMSettings (`accessible/docs/HCMSettings.md`) # HCM Settings Several Firefox settings work together to determine how web content and browser chrome are rendered. They can be hard to keep track of! Use the flowcharts below for quick reference. ## Settings that control color usage in browser chrome - OS HCM: - Windows: High Contrast Mode in OS accessibility settings - macOS: Increase Contrast in OS accessibility settings - Linux: High Contrast Theme in OS accessibility settings - FF Theme (AKA FF Colorway) Note: OS HCM settings will only trigger HCM color usage in chrome if a user's FF theme is set to "system auto". If they have a pre-selected colorway or other FF theme (including explicit "Dark" or "Light") they will not see color changes upon enabling OS HCM. ```{mermaid} flowchart TD A[Is OS HCM enabeld?] A -->|Yes| B[Is FF's theme set to System Auto?] B --> |Yes| C[Use OS HCM colors to render browser chrome] B -->|No| D[Use FF theme colors to render browser chrome] A -->|No| D ``` ## Settings that control color usage in content - Colors Dialog (about:preferences > Contrast Control) - Extensions like Dark Reader, or changes to user.css, may override author specified colors independent of HCM. ```{mermaid} flowchart TD A[Which option is selected in 'Contrast Control'?] A -->|Use platform's contrast settings| B[Is a OS HCM enabled?] A -->|Off| H A --->|On| I[Use colors dialog colors to render all content (HCM)] B -->|Yes| C[Use OS colors to render all content (HCM)] B -->|No| H[Use system colors for all unstyled content] ``` --- ### Accessible Docs TaggedPdfOutput (`accessible/docs/TaggedPdfOutput.md`) # Tagged PDF Output Tagged PDF embeds a semantic structure tree alongside the graphical content in a PDF, enabling screen readers and other assistive technology to interpret the document. Firefox generates tagged PDFs by leveraging its accessibility engine and Skia's SkPDF backend. The feature is toggled by the pref `accessibility.tagged_pdf_output.enabled`. ## High Level Architecture The implementation spans several modules: - **`accessible/base/DocManager`**: `NotifyOfPrintDocument` bootstraps the accessibility engine and builds accessibility trees for print documents. - **`accessible/base/nsAccessibilityService`**: provides an `ePdfOutput` consumer mode that allows the accessibility engine to run in a stripped-down mode purely for PDF generation. - **`accessible/pdf/PdfStructTreeBuilder`**: translates the Gecko accessibility tree into an `SkPDF::StructureElementNode` tree for Skia and maps accessibility node IDs to SkPDF node IDs. - **`gfx/thebes/PrintTargetSkPDF`**: the Skia PDF print target, which calls `PdfStructTreeBuilder` to obtain the structure tree and passes it to `SkPDF::MakeDocument`. - **`layout/generic/nsIFrame`** + **`layout/painting/nsDisplayList`**: layout emits `nsDisplayAccessibleId` display items to associate painted content with accessibility nodes. - **`gfx/2d/DrawTarget`** + **`gfx/2d/DrawTargetSkia`**: the `AccessibleId` draw command propagates the association down to Skia, where `SkPDF::SetNodeId` tags subsequent drawing commands. ## Triggering Tagged PDF Generation When a print job starts, [`nsPrintJob::SetupToPrintContent`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/layout/printing/nsPrintJob.cpp#903) calls [`a11y::DocManager::NotifyOfPrintDocument(doc)`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/DocManager.cpp#203). `NotifyOfPrintDocument` calls [`GetOrCreateAccService(nsAccessibilityService::ePdfOutput)`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/nsAccessibilityService.h#553) to ensure the accessibility service is running, then creates a `DocAccessible` for the print document (a static clone of the live document, so `aAllowStatic=true` is passed), and immediately calls [`DoInitialUpdate()`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/generic/DocAccessible.cpp#1835) to build the accessibility tree synchronously. In-process iframes embedded in the document are also initialized here in the same way. For a parent process document, `NotifyOfPrintDocument` calls [`PdfStructTreeBuilder::Init`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#36) directly. For remote documents in content processes, after the local accessibility tree is built, `NotifyOfPrintDocument` arranges for `PdfStructTreeBuilder::Init(browsingContext)` to be called in the parent process (see the next section on IPC). ## IPC: Remote Top Level Documents and OOP Iframes Content can live in content processes, but a PDF can only be generated in the parent process, regardless of where the content lives or where the print job is initiated. There are two IPC cases. ### Remote Top Level Document `nsPrintJob` runs in whatever process owns the document, so for a remote tab, `NotifyOfPrintDocument` runs in the content process. After building the accessibility tree locally and sending it to the parent process via `PDocAccessible`, [a `PDocAccessible::Printing` IPDL message is sent to the parent process](https://searchfox.org/firefox-main/rev/f3695d1fd8d9f7419576d8e0366069bf2cc576ac/accessible/base/DocManager.cpp#245). [`DocAccessibleParent::RecvPrinting`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/ipc/DocAccessibleParent.cpp#1500) handles this message and calls `PdfStructTreeBuilder::Init` in the parent process. ### OOP Iframes Once `PdfStructTreeBuilder::Init` runs in the parent process for the top level document as described above, [`InitInternal`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#138) walks all descendant `BrowserParent`s and sends a `PBrowser::RequestDocAccessibleForPrint` IPDL message to each. In the content process, [`BrowserChild::RecvRequestDocAccessibleForPrint`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/dom/ipc/BrowserChild.cpp#4248) calls `NotifyOfPrintDocument`. As above, this builds the accessibility tree, sends it to the parent process, sends `PDocAccessible::Printing` and thus calls `PdfStructTreeBuilder::Init` in the parent process. `PdfStructTreeBuilder` tracks how many OOP iframes are pending via `mPendingOopIframes`. Each time an OOP iframe's accessibility tree arrives and is registered with the builder via a further call to `InitInternal`, the counter is decremented. When it reaches zero, a `ReadyPromise` is resolved. [The print job awaits this promise before proceeding](https://searchfox.org/firefox-main/rev/f3695d1fd8d9f7419576d8e0366069bf2cc576ac/layout/printing/ipc/RemotePrintJobParent.cpp#45). SkPDF requires the complete structure tree at the time the document is opened, so this waiting is necessary before `SkPDF::MakeDocument` can be called. ## Building the Structure Tree Once the `ReadyPromise` resolves, [`PrintTargetSkPDF::BeginPrinting`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/thebes/PrintTargetSkPDF.cpp#211) calls [`PdfStructTreeBuilder::BuildStructTree`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#170). This walks the accessibility tree rooted at the top document — using `DocAccessible` for in-process documents and `DocAccessibleParent` for remote ones — and recursively builds a tree of `SkPDF::StructureElementNode` objects. For each accessible, [`BuildStructSubtree`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#210): - Assigns an SkPDF integer node ID (via [`GeneratePdfId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#190)) and records the mapping in `mAccToPdf`. - Maps the Gecko accessibility role to the corresponding PDF structure type; e.g. `roles::HEADING` → `"H1"`–`"H6"` or `"H"`, `roles::PARAGRAPH` → `"P"`, `roles::TABLE` → `"Table"`, etc. - Depending on the role, maps Gecko accessibility properties to PDF attributes such as table row/column span, header associations and alt text for figures and headings. The completed struct tree root is stored in `SkPDF::Metadata::fStructureElementTreeRoot` before `SkPDF::MakeDocument` is called. SkPDF also derives a PDF bookmark outline from heading nodes; headings' accessible names are set as `fAlt` to provide this text, since Gecko provides glyph indices rather than text runs when drawing. ## Associating Painted Content with Structure Nodes The struct tree alone is not sufficient: each drawing command in the content stream must be tagged with the SkPDF node ID of the structure element it belongs to. ### Layout: Emitting `nsDisplayAccessibleId` During display list construction for a print document, [`nsIFrame::BuildDisplayListForChild`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/layout/generic/nsIFrame.cpp#4238) calls the local helper [`MaybeAddAccId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/layout/generic/nsIFrame.cpp#4223) for each child frame. `MaybeAddAccId` calls [`PdfStructTreeBuilder::GetAccId(frame)`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#105) which looks up the `Accessible` for the frame's content node and returns a `{browsingContextId, accessibleId}` pair. If one is found, an [`nsDisplayAccessibleId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/layout/painting/nsDisplayList.h#6854) display item is prepended to the content list for that frame. ### Painting: The `DrawTarget::AccessibleId` Command [`nsDisplayAccessibleId::Paint`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/layout/painting/nsDisplayList.cpp#8737) calls [`DrawTarget::AccessibleId(browsingContextId, accId)`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/2d/2D.h#1459). For parent process content rendered directly to a `DrawTargetSkia` backed by an SkPDF canvas, [`DrawTargetSkia::AccessibleId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/2d/DrawTargetSkia.cpp#2259) translates the Gecko IDs to a SkPDF integer via [`PdfStructTreeBuilder::GetPdfId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#88), then calls `SkPDF::SetNodeId(mCanvas, pdfId)`. All drawing commands issued to the canvas after this point are tagged with that node in the PDF. ### Content Process: `DrawTargetRecording` When content is painted in a content process, it goes through `DrawTargetRecording`. [`DrawTargetRecording::AccessibleId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/2d/DrawTargetRecording.cpp#991) emits a [`RecordedAccessibleId`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/2d/RecordedEventImpl.h#1880) event into the recording stream . When the recording is replayed in the parent process on a `DrawTargetSkia`, `RecordedAccessibleId::PlayEvent` calls `DrawTargetSkia::AccessibleId` and the same SkPDF tagging occurs as described above. ## Stripped-Down Accessibility Engine (`ePdfOutput` Mode) Without a dedicated PDF output mode, tagged PDF generation would require an AT client to already be running (or the engine to be force enabled), because normal accessibility engine startup does significant work that is only needed to serve AT clients: walking all existing documents, initialising platform accessibility APIs and activating the service in every content process. None of this work is necessary to build an accessibility tree for a single document being printed. The [`ePdfOutput`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/nsAccessibilityService.h#405) consumer mode allows the engine to start in a lightweight mode when the only reason it is needed is to generate a tagged PDF. ### `ePdfOutput` Consumer Flag `nsAccessibilityService` has a bitmask of active consumers. If only the `ePdfOutput` bit is set, this indicates that the only reason the service is running is to support PDF generation. [`nsAccessibilityService::IsOnlyForPdfOutput()`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/nsAccessibilityService.h#413) returns true in this case. ### Skipped Initialization When `GetOrCreateAccService(ePdfOutput)` starts the engine and no other consumer is active, [`nsAccessibilityService::Init`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/nsAccessibilityService.cpp#1650) **skips** three steps that are deferred into [`FullInit`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/nsAccessibilityService.cpp#1724): 1. [`ApplicationAccessible::CreateInitialDocs`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/generic/ApplicationAccessible.cpp#113): forces creation of `DocAccessible`s for all already-open windows. 2. [`PlatformInit`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/Platform.h#73): initializes platform accessibility APIs (IAccessible2/UIA on Windows, ATK on Linux, etc.). 3. Activating the accessibility service in every content process. The `a11y-init-or-shutdown` notification is fired with the value `"pdf"` instead of `"1"` to let observers distinguish this limited startup from a full one. ### Suppressing Unrelated `DocAccessible` Creation While `IsOnlyForPdfOutput()`, [creation of `DocAccessible`s is suppressed](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/DocManager.cpp#519) for any document that was not explicitly passed to `NotifyOfPrintDocument`. This prevents ordinary browsing documents from consuming resources they do not need. ### Promotion to Full Service If a real AT consumer (e.g. a screen reader) causes `GetOrCreateAccService` to be called while the service is already running in `ePdfOutput`-only mode, [`PromoteFromPdfOutput`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/base/nsAccessibilityService.cpp#1745) is called to perform the deferred `FullInit` work: creating initial document accessibles, running `PlatformInit` and notifying content processes. ### Cache Domains Print documents use a specific set of cache domains (requested per-document via [`DocAccessible`](https://searchfox.org/firefox-main/rev/f3695d1fd8d9f7419576d8e0366069bf2cc576ac/accessible/generic/DocAccessible.cpp#396)/[`DocAccessibleParent`](https://searchfox.org/firefox-main/rev/f3695d1fd8d9f7419576d8e0366069bf2cc576ac/accessible/ipc/DocAccessibleParent.cpp#78)) rather than the global `gCacheDomains`. This is done so that PDF output does not inadvertently widen the cache domains in use by any other running clients. This also avoids pushing unnecessary domains for PDF when another client requires a wider set of domains. Note that a print document is a static clone of the original DOM document, so this doesn't impact the original document being printed. ### Lifecycle When the last print document is removed, [the `ePdfOutput` consumer bit is cleared](https://searchfox.org/firefox-main/rev/f3695d1fd8d9f7419576d8e0366069bf2cc576ac/accessible/base/DocManager.cpp#137). If no other consumers remain, the accessibility service shuts down normally. [`PdfStructTreeBuilder::Done`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/accessible/pdf/PdfStructTreeBuilder.cpp#75) is called from [`nsDeviceContext::EndDocument`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/src/nsDeviceContext.cpp#269)/[`AbortDocument`](https://searchfox.org/firefox-main/rev/2e7b2a02b5198ae72c06debc5cc1c2ac527fd742/gfx/src/nsDeviceContext.cpp#306) to clean up the builder instance after printing completes or is aborted. ## Data Flow Summary ``` /* Detailed source-code truncated for AI context efficiency. */ ``` --- ### Accessible Docs Index (`accessible/docs/index.rst`) Accessibility ============= These pages contain design documents for the accessibility implementation in Gecko. They live in the mozilla-central repository under the accessible/docs directory. The `Accessibility page on the Mozilla Wiki `__ contains general information about accessibility and the accessibility team at Mozilla. The `Mochitest FAQ docs <../testing/mochitest-plain/faq.html#how-can-i-run-accessibility-tests-a11y-checks>`__ contain guidance on debugging a11y-checks failures and working with AccessibilityUtils when writing frontend test cases. .. toctree:: :maxdepth: 1 GuidelinesForNewContributors Architecture DocumentAccessibilityLifecycle GeckoViewThreadTopography ColorsAndHighContrastMode HCMSettings HCMMediaQueries HCMCSSChecklist TaggedPdfOutput --- ### Browser Docs BrowserStartup (`browser/docs/BrowserStartup.md`) # Browser Startup ## Invoking your code on browser startup The first rule of running code during startup is: don't. We take performance very seriously and ideally your component/feature should initialize only when needed. If you have established that you really must run code during startup, register a category manager entry in `browser/components/BrowserComponents.manifest`. See [the category manager indirection docs](./CategoryManagerIndirection.md) for more details on the mechanism. ### Available category manager entries (in order) Categories come in two types: per-application (fired once at startup) and per-window (fired for each browser window). The following categories are listed in the order they fire. #### Per-application categories (invoked once, not per-window) | Category | Notes | |---|---| | `browser-before-ui-startup` | Please don't do it unless absolutely necessary. This will run code before the first browser window appears on the screen and make Firefox seem slow. | | `browser-first-window-ready` | After the first browser window's `browser-window-delayed-startup` call. | | `browser-idle-startup` | Preferred entrypoint for most startup code. Runs during a user-idle period after startup. | | `browser-best-effort-idle-startup` | Like `browser-idle-startup`, but your code **may not run at all** if the browser is shut down quickly. | #### Per-window categories (invoked for each browser window) | Category | Notes | |---|---| | `browser-window-before-initial-xul-layout-document-preparation` | Before XUL layout; before the tab bar visibility update. | | `browser-window-before-initial-xul-layout` | Before XUL layout; after the tab bar visibility update and document icon are set. | | `browser-window-domcontentloaded-before-tabbrowser` | During `DOMContentLoaded`, before the `Tabbrowser` is created. | | `browser-window-domcontentloaded-tabbrowser` | During `DOMContentLoaded`, creates the `Tabbrowser`. **Internal category - do not add consumers here.** | | `browser-window-domcontentloaded` | During `DOMContentLoaded`, after the `Tabbrowser` is created. Preferred entry point for `DOMContentLoaded` initialization. | | `browser-window-load-before-sessionstore-init` | During the window `load` event, before SessionStore initializes the window. For components that must be ready before session restore runs. | | `browser-window-load` | During the window `load` event, after SessionStore has initialized the window. | | `browser-window-delayed-startup` | After the window's first paint, for code that can run after the window is visible. | | `browser-window-location-change` | Fires on every `XULBrowserWindow.onLocationChange` for the window. | | `browser-window-unload-begin` | At the very start of window unload, before checking whether the window finished loading. Runs even if the window never fully loaded. | | `browser-window-unload` | During window unload, before `Tabbrowser` is destroyed. Preferred entry point for window unload cleanup. | | `browser-window-unload-tabbrowser` | During window unload, destroys the `Tabbrowser`. **Internal category - do not add consumers here.** | | `browser-window-final-unload` | During window unload, after `Tabbrowser` is destroyed. | Other useful points in startup are: - `BrowserGlue`'s `_onWindowsRestored`, and/or the observer service's `sessionstore-windows-restored` topic, and/or a category manager call that should replace the `BrowserGlue` list of direct calls. This fires after session restore has completed restoring all windows (but before all pages that may have been restored have necessarily loaded). Note that this is guaranteed to fire even if automatic session restore is not enabled. ## How do first run/first startup experiments work? Why does synchronously reading Nimbus feature values work for customizing display features like `about:welcome` onboarding and the default browser prompt? The key invariant is that the display decisions wait for `sessionstore-windows-restored` to show customizable UI, and therefore we just need Nimbus available to read at that point. This is arranged either via the `--first-startup` flag; or, for subsequent startups, the relevant Nimbus features being marked `isEarlyStartup: true`. When `isEarlyStartup: true`, Nimbus caches all its feature variables as Gecko preferences, ready to be read during early startup. (See [the early startup docs](https://experimenter.info/faq/early-startup/what-do-it-do).) Customizable display features like `about:welcome` or the default browser prompt are used in [`_maybeShowDefaultBrowserPrompt()`](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/components/BrowserGlue.sys.mjs#4685), which is invoked as part of a startup idle task. Startup idle tasks are [scheduled in response to `sessionstore-windows-restored`](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/components/BrowserGlue.sys.mjs#2423). Now, why is `sessionstore-windows-restored` late enough for a first startup experiment? The answer is subtle. During Firefox launch, [`final-ui-startup` is notified](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/toolkit/xre/nsAppRunner.cpp#5764-5765), and in response `SessionStore` is initialized. Additionally, Nimbus/Normandy initialization is [started but not awaited](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/components/BrowserGlue.sys.mjs#1487). Then the [command line is handled](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/toolkit/xre/nsAppRunner.cpp#5775-5778). When `--first-startup` is passed, we [spin the event loop to allow Nimbus/Normandy time to complete its initialization and first fetch](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/components/BrowserContentHandler.sys.mjs#677) before continuing to process the command line. See [the `FirstStartup` module](https://firefox-source-docs.mozilla.org/toolkit/modules/toolkit_modules/FirstStartup.html). (Important caveat: `--first-startup` is only used on Windows; see [Bug 1872934](https://bugzilla.mozilla.org/show_bug.cgi?id=1872934), for example.) This races with `SessionStore`, which itself waits for the first browser window to be shown -- in particular, the `sessionstore-windows-restored` notification waits for the [first browser window's `browser-delayed-startup-finished` notification](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/components/sessionstore/SessionStore.sys.mjs#2147-2159). This first `browser-delayed-startup-finished` notification **is not guaranteed** to be after `--first-startup` has spun the event loop! But, when launched with only `--first-startup` and flags considered very early in `nsAppRunner.cpp` -- as [the stub installer does](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/installer/windows/nsis/stub.nsi#1424-1456) -- then the first window **is guaranteed** to be after the event loop has been spun, and therefore `sessionstore-windows-restored` is after as well. (As a counter-example: try `firefox.exe --browser --first-startup` and witness the [`--browser` flag](https://searchfox.org/mozilla-central/rev/a965e3c683ecc035dee1de72bd33a8d91b1203ed/browser/components/BrowserContentHandler.sys.mjs#505-508) creating a window before spinning the event loop, inadvertently racing against `sessionstore-windows-restored`.) Making this deterministic is tracked by [Bug 1944431](https://bugzilla.mozilla.org/show_bug.cgi?id=1944431). Together, this means that first-startup experiments will be loaded in time to impact display features such as `about:welcome` and the default browser prompt, and we should not have a "split brain" scenario in which the Nimbus feature is intermittently unavailable to the relevant display features. --- ### Browser Docs BrowserUsageTelemetry (`browser/docs/BrowserUsageTelemetry.rst`) .. _browserusagetelemetry: ======================= Browser Usage Telemetry ======================= The :searchfox:`BrowserUsageTelemetry.sys.mjs ` module is the main module for measurements regarding the browser usage (e.g. tab and window counts, search counts, ...). The measurements recording begins right after the ``SessionStore`` has finished restoring the session (i.e. restoring tabs/windows after Firefox starts). Tab and window interactions =========================== The usage telemetry module currently measures these interactions with the browser's tabs and windows: - *tab and window engagement*: counts the number of non-private tabs and windows opened in a subsession, after the session is restored (see e.g. ``browser.engagement.max_concurrent_tab_count``); - *URI loads*: counts the number of page loads (doesn't track and send the addresses, just the counts) directly triggered by the users (see ``browser.engagement.total_uri_count``); - *navigation events*: at this time, this only counts the number of time a page load is triggered by a particular UI interaction (e.g. by searching through the URL bar, see ``browser.engagement.navigation.urlbar``). Please see :searchfox:`Scalars.yaml ` for the full list of tracked interactions. Customizable UI =============== This telemetry records information about the positions of toolbar items and when the user interacts with them. It is submitted as scalar values along with the normal telemetry ping. There are a number of different parts to this telemetry: UI Areas -------- For the purposes of this telemetry a set of areas are defined: * In the main browser UI: * ``menu-bar`` - The main menu. * ``menu-toolbar`` - The normally hidden toolbar that holds the main menu. * ``titlebar`` - The optional title bar. * ``tabs-bar`` - The area where tabs are displayed. * ``vertical-tabs-container`` - The area where vertical tabs are displayed. * ``bookmarks-bar`` - The bookmarks toolbar. * ``app-menu`` - The main application (hamburger) menu. * ``tabs-context`` - The context menu shown from right-clicking a tab. * ``content-context`` - The context menu shown from right-clicking the web page. * ``widget-overflow-list`` - Items that have overflowed the available space. * ``pinned-overflow-menu`` - Items that the user has pinned to the toolbar overflow menu. * ``pageaction-urlbar`` - Page actions buttons in the address bar. * ``pageaction-panel`` - The page action (meatball) menu. * ``nav-bar-start`` - The area of the navigation toolbar before the address bar. * ``nav-bar-end`` - The area of the navigation toolbar after the address bar. * ``unified-extensions-area`` - The unified extensions panel. * In ``about:preferences`` the different categories are used: * ``preferences-paneDownloads`` * ``preferences-paneGeneral`` * ``preferences-paneHome`` * ``preferences-panePrivacy`` * ``preferences-paneSearch`` * ``preferences-paneSearchResults`` * ``preferences-paneSync`` * ``preferences-paneContainers`` * ``preferences-paneAccessibility`` * ``preferences-paneAppearance`` * ``preferences-paneLanguages`` * ``preferences-paneAbout`` * ``preferences-panePermissionsData`` * ``preferences-paneTabsBrowsing`` Widget Identifiers ------------------ In order to uniquely identify a visual element a set of heuristics are used: #. If the element is one of the customizable toolbar items then that item's ID is used. #. If the DOM element has an ID set then that is used. #. If the DOM element's class contains one of ``bookmark-item``, ``tab-icon-sound`` or ``tab-close-button`` then that is used. #. If the DOM element has a ``preference`` ``key``, ``command``, ``observes`` or ``data-l10n-id`` attribute then that is used. #. If there is still no identifier then this is repeated for the DOM element's parent element. Widget Locations ---------------- The keyed scalar ``browser.ui.toolbar_widgets`` records the position of widgets in the UI. At startup the positions of widgets are collected and recorded by setting the scalar key ``_pinned_`` to true. The widget ID are the IDs of the elements in the DOM. The area is one of the areas listed above from the browser UI that can be customised. For the areas that can be controlled the scalar keys ``_`` are set. ``newtab`` is special to the Bookmarks Toolbar and is used when the toolbar will only be shown on the New Tab page. Widget Customization -------------------- The scalar ``browser.ui.customized_widgets`` records whenever the user moves a widget around the toolbars or shows or hides some of the areas. When a change occurs the scalar with the key ``____`` is incremented. The action can be one of ``move``, ``add`` or ``remove``. Old area and new area are the previous and now locations of the widget. In the case of ``add`` or ``remove`` actions one of the areas will be ``na``. For areas that can be shown or hidden the areas will be ``off`` or ``on``. The reason is a simple string that indicates what caused the move to happen (drag, context menu, etc.). UI Interactions --------------- The scalars ``browser.ui.interaction.`` record how often the use interacts with the browser. The area is one of those above with the addition of ``keyboard`` for keyboard shortcuts. When an interaction occurs the widget's identifier is used as the key and the scalar is incremented. If the widget is provided by an add-on then the add-on identifier is dropped and an identifier of the form ``addonX`` is used where X is a number. The number used is stable for a single session. Every time the user moves or interacts with an add-on the same number is used but then the numbers for each add-on may change after Firefox has been restarted. Profile Count ============= The scalar ``browser.engagement.profile_count`` records how many profiles have been used by the current Firefox installation. It reports a bucketed result, which will be 0 if there is an error. The raw value will be reported for 1-10, but above that, it will report 10 for 10-99, 100 for 100-999, 1000 for 1000-9999, and 10000 for any values greater than that. The profile count data for an installation is stored in the root of the update directory in a file called ``profile_count_.json``. The full path to the file will typically look something like ``C:\ProgramData\Mozilla\profile_count_5A9E6E2F272F7AA0.json``. This value is meant to be resilient to re-installation, so that file will not be removed when Firefox is uninstalled. Context menu entrypoints ======================== Some context menus are re-used in multiple places. By default, we simply count the number of interactions per item within a context menu, and do not record the entrypoint that caused the context menu to open. It is possible to opt-in to recording the entrypoint that caused the context menu to open. This is done by adding an entry to ``ENTRYPOINT_TRACKED_CONTEXT_MENU_IDS``, mapping the ID of the context menu to a keyed Scalar under ``browser.ui.interaction.``. This scalar is recorded only if an interaction is recorded within the context menu itself. When the keyed scalar is recorded, the key will be a unique ID for the trigger node that caused the context menu to open. The value is the count of openings from that trigger node. --- ### Browser Docs CategoryManagerIndirection (`browser/docs/CategoryManagerIndirection.md`) # Category manager indirection (callModulesFromCategory) Firefox front-end code uses the category manager as a publish/subscribe mechanism for dependency injection, so consumers can be notified of interesting things happening without having to directly talk to the publisher/actor who decides the interesting thing is happening. There are 2 parts to this: 1. Consumers registering with the category manager 2. Publishers/actors invoking consumers via the category manager. ## Consumer registration with the category manager The category manager is used for various purposes within Firefox; it is more or less an arbitrary double string-keyed data store. For this particular usecase, the publisher/consumer have to use the same primary key (i.e. category name), such as `browser-idle-startup`. The secondary key is a full URL to a `sys.mjs` module. Note that because this is a key, **only one consumer per module & category combination is possible**. The "value" part is an `Object.method` notation, where the expectation is that `Object` is an exported symbol from the module identified as the secondary key, and `method` is some method on that object. At compile-time, registration can happen with an entry in a `.manifest` file like [BrowserComponents.manifest](https://searchfox.org/firefox-main/source/browser/components/BrowserComponents.manifest). Note that any manifest successfully processed by the build system would do, we don't need to use `BrowserComponents.manifest` specifically. In fact, it would be preferable if components used their own manifest files. An example registration looks like: ``` category browser-idle-startup moz-src:///browser/components/tabbrowser/TabUnloader.sys.mjs TabUnloader.init ``` This will ensure that when the `browser-idle-startup` publisher is invoked, the `TabUnloader.sys.mjs` module is loaded and the `init` method on the exported `TabUnloader` object is invoked. ### Runtime registration Runtime registration is less-often used, but can be done using the category manager's XPCOM API: ```js Services.catMan.addCategoryEntry( "browser-idle-startup", "moz-src:///browser/components/tabbrowser/TabUnloader.sys.mjs", "TabUnloader.init" ) ``` ## Publishers/actors invoking consumers Publishers call `BrowserUtils.callModulesFromCategory` with a dictionary of options as the first argument. If provided, any other arguments are passed straight through to any consumers. ```{js:autofunction} BrowserUtils.callModulesFromCategory ``` Example: ```js BrowserUtils.callModulesFromCategory({ categoryName: "my-fancy-category-name", profilerMarker: "markMyCategories", idleDispatch: true, someArgument }); ``` This will pass `someArgument` to each consumer registered for `my-fancy-category-name`. Each consumer will be invoked via an idle task, and each task will get a profiler marker (labelled `"markMyCategories"`) in the [Firefox Profiler](https://profiler.firefox.com/) so it's easy to find in performance profiles. You should consider using `idleDispatch: true` if invocation of the consumers does not need to happen synchronously. If you need to care about errors produced by consumers, you can specify a function for `failureHandler` and handle any exceptions/errors using your own logic. Note that it may be invoked asynchronously if the consumers are async. ## Caveats Any errors thrown by consumers are automatically caught and reported via the [Browser Console](/devtools-user/browser_console/index.rst). Async functions are not awaited before invoking other consumers. Note that rejections (exceptions from async code) are still caught and reported to the console, and that the async duration of a given consumer will be what determines the length of the profiler marker, if the publisher asks for profiler markers. ## Why not just call consumers directly? There are a number of benefits over direct method calls and module imports. ### Reducing direct dependencies between different parts of the code-base Code that looks like this: ``` Foo.thingHappened(arg); Bar.thingHappened(arg); Baz.thingHappened(arg); ``` is not only repetitive, it also means that the code in question has to directly import all the modules that provide `Foo`, `Bar` and `Baz`. It means that if those modules change or move or are refactored, the "publisher" code has to be updated, with all the added burdens that comes with (potential for merge conflicts, more automatically added reviewer groups for trivial changes, easy to miss if dependencies are widespread). ### Avoiding a bootstrap problem in favour of a "just in time" approach To make sure code is invoked later, when using the observer service, DOM event listeners, or other mechanisms, it usually needs to add a listener before the event of interest happens. If not managed carefully, this often leads to component initialization being front-loaded to make sure not to "miss" it later. This in turn makes browser startup more heavyweight rather than it needs to be, because we set up listeners for _everything_, potentially loading entire JS modules just to do that. ### Unified error-handling, performance inspection, and scheduling Using the `BrowserUtils.callModulesFromCategory` API allows specifying error handling, performance profiler markers, and scheduling (use of idle tasks) in one place. This abstracts away the fact that we never want observers, event listeners or other mechanisms like this to break and stop notifying (or worse, propagate an exception themselves) when one of the consumers breaks. --- ### Browser Docs CommandLineParameters (`browser/docs/CommandLineParameters.rst`) ======================= Command Line Parameters ======================= Firefox recognizes many (many!) command line parameters. Overview documentation of these parameters lives here. Known parameters ---------------- .. list-table:: :widths: 20 80 :header-rows: 1 * - Parameter - Description * - ``-osint`` - On Windows, ``-osint`` serves two purposes. Most importantly, it signals that the command line is untrusted and must be sanitized. Command lines with ``-osint`` are rejected unless they have a very specific structure, usually ``firefox.exe -osint -url URL`` or ``firefox.exe -osint -private-window URL``: refer to :searchfox:`the EnsureCommandLineSafe function `. These command lines are produced by apps delegating to Firefox, and the resulting URL may not be correctly quoted. The sanitization process ensures that maliciously chosen URLs do not add additional parameters to Firefox. Secondarily, the ``-osint`` parameter signals that Firefox is being invoked by Windows to handle a URL: generally a registered file type, e.g., ``.html``, or protocol, e.g., ``https``. --- ### Browser Docs FrontendCodeReviewBestPractices (`browser/docs/FrontendCodeReviewBestPractices.md`) # Frontend Code Review Best Practices ## Introduction Code reviews help ensure that the code solves a specific problem, doesn’t have bugs or regress other functionality, and has adequate test coverage. It also provides an opportunity to ensure correct documentation is added, whether through code comments or documentation of changes. The process of reviewing code also helps spread knowledge about how the code works amongst developers, both as a patch author and as a reviewer. A review is required before code or tests are added to Mozilla’s repository. Once approved, code is merged to autoland and once tests pass, sheriffs will merge it with other commits to mozilla-central. This guide outlines a set of standards for both patch author and reviewer. ## Intended audience and outcomes This document is primarily intended for engineers on the Firefox Desktop Front end team. The aim of this guide is to align the team around an agreed set of expectations for patch reviews that will reduce confusion, prevent misunderstandings, help land patches more efficiently and to help onboard new team members. As an engineer, you’ll be in the position of being both a patch author and a reviewer, so having a good understanding of the expectations of both roles is recommended. ## What is expected from a frontend code review? The sections below outline some of the high level expectations when reviewing code. See also the [Technologies and Specifics sections for more details on what to look for that are specific to Frontend code](#technologies-and-specifics). ### The basics A code review and automation will check if this patch: * applies cleanly to mozilla-central and can be built. * has a [good commit message](/contributing/contribution_quickref.rst#commit-message) that describes the changes as well as the reason for them where that is not obvious. * Adding a longer description in a commit message will be used as the summary in Phabricator. * fixes the issue at hand. * has automated test coverage where appropriate. [Exceptions to this are covered by using the test-exception-\* tags in Phabricator](https://firefox-source-docs.mozilla.org/testing/testing-policy/index.html#exceptions). Here are some common exceptions in frontend where \[new\] test coverage isn’t needed: * style/image/l10n-only changes * Code that interacts directly with the OS in ways we can’t mock in automated tests. * Code that requires very specific external circumstances (OS settings, wall clock time, actions by other programs, etc.) we can’t mock reliably. * Refactorings of existing code (where existing test coverage exists) * Removing code * passes linting and/or automated tests. **If any of these is missing/broken, a reviewer is likely to stop then and there.** Before submitting patches, code authors should ensure they have these covered. ### Is this necessary and sufficient? Two useful ways of looking at patches are “is this necessary?” and “is this sufficient?”: * **Necessary**: are all the changes in the patch required? It’s common to find other issues when fixing a bug, but code not necessary to fix this specific bug should be moved to a separate bug. Reviewers will usually flag up: * Unrelated code changes * Changing unrelated whitespace etc. (mind your editor’s autoformat) * Unnecessarily complex or hacky fixes * **Sufficient**: does this fix the issue completely? That is, have we looked at edge cases and is the patch/patchset definitely fixing all of the issue, not just parts of it or a symptom of it? * This also means **considering what is not in the patch**. So e.g. when renaming a method, patch authors and reviewers should not just check if all the replacements in the patch are correct, but also if all occurrences were actually touched in the patch (searchfox should make this relatively straightforward, or you can apply the patch locally and use `grep`/`ack`/`ag` etc). ## Expectations for the Reviewer ### Progress > Perfection As noted above, the context for the patch should be provided by the author, however it’s important to try to strike a balance between ensuring we maintain high standards and being able to make progress. If you identify issues that are routinely cropping up that could be covered by automated linting, please file issues for new rules to be added. This helps us to ensure that the time engineers dedicate to review is primarily spent on efficiently ensuring a change addresses what it sets out to and is both a maintainable and safe addition to Firefox. ### Language and tone in review comments * Take the time to thank and point out good code changes. * Focus on the code, not the patch author (avoid wording that sounds like it’s criticizing the author, for example “this doesn’t make sense, why did you do it this way?” versus “I’m curious why you took this approach. Could you please provide some context?”). * Framing comments as questions rather than statements can help create an environment conducive to collaboration. Rather than “This doesn’t work when `bar` is `undefined`”, “Could you please check if this code is properly handling the case of `bar` being `undefined`?” . * Using “please” and “what do you think?” goes a long way in making others feel like colleagues, and not subordinates. As a reviewer, double-check your comments. Assume the code author has spent more time thinking about this part of the code than you have and might actually be right, even if you originally thought something was wrong. * Be clear about what changes are required to be changed in order to land the patch versus those that are optional. * For things that aren’t [nits](#what-is-a-nit) or trivially understood to be improvements, explain *why* you are requesting a change. Understanding the reasoning behind requested changes helps make sure that you and the patch author share an understanding of what the patch is doing, and helps the patch author learn. * Minimize the number of passes required for review and addressing review comments. Where possible provide your review comments in a single pass rather than multiple iterations. This helps to reduce the number of cycles needed to get something through review and any associated context switching for both the reviewer and the patch author. In a case where you don't have time for a full review, mention that your review is currently incomplete and set expectations for when it will be so the author can plan accordingly. * When reviewing code on behalf of additional review groups added to a patch, your review should primarily focus on the areas that the review-group is responsible for or interfaces that your group is using. However, if you do spot a non-trivial issue that falls outside this during review, then it would be reasonable to flag it. . ### Turnaround time for reviews * Aim for a response within 1 business day. This need not be a full review, but could be a comment setting expectations about when you’ll be able to review the patch, pointing to other folks who might be able to review it sooner or would be more appropriate to review the patch. * If you’re explicitly asked for review and can’t get to it due to time constraints, it’s always helpful to set expectations for the patch author. ## Expectations for the patch author ### Communication There is often more than one way to address an issue, and reviewers and patch authors may disagree about the “right” approach to a bug. What is “complex” or “hacky” to one person may be “correctly architectured” or “efficient” to another. If when working on a bug, you’re unsure about what the “right” approach is (e.g. “just add a nullcheck here and move on” vs. “refactor the calling code so we don’t ever pass null”), talk to your prospective reviewer or other people familiar with the code before deciding, to avoid repeated work when your reviewer suggests an alternative, perhaps because they have other context you weren’t aware of, or to fit the general architecture of the component you’re changing. When you haven’t talked to your reviewer because you think the approach you chose is obviously correct, it is usually still helpful to outline your reasoning/choices in the extended commit message, a phabricator comment, and/or bugzilla. It doesn’t need to be an essay, but ideally the reviewer should be able to understand the patch and its reasoning from reading the patch and commit message. Make use of the commit message to offer both a brief, and where necessary a longer explanation of what the change is doing. Reviewers often review dozens of patches each week. Ensuring that the patch contains all the information they need to review the change helps speed up reviews and avoids confusion about what a patch is trying to achieve. If the patch needs a shorter turnaround time of the review cycle due to a release or uplift deadline (which should also be reflected in the bug priority and severity that’s been set), you should ping blocking reviewers on slack or matrix to raise awareness of this deadline and to confirm they can review your patch as soon as possible. If they are unable to do so, you’ll need to find another reviewer who can. Where possible ask the existing reviewer for a suggestion, or ask someone else in the same review group. If that’s not possible, ask for input from your team/project lead or manager. When making changes to revisions, using the ‘plan-changes’ action in Phabricator [“removes revisions from reviewers’ queues, meaning that they will no longer be visible under “Ready to Review” on their “Active Revisions” dashboards, until a new diff is uploaded”](https://moz-conduit.readthedocs.io/en/latest/phabricator-user.html#other-revision-actions) When making non-trivial changes to patches which are already on Phabricator, use `--message` (or `-m`) with your `moz-phab` submission to explain what you’re changing. Leave questions or comments in Phabricator about things you were not sure about. Your reviewer might be able to offer answers, or you might have stumbled on deeper underlying problems that need addressing elsewhere. Either way, everyone learns. ### Addressing review comments Except for very small patches it is extremely common for a reviewer to request changes to a patch after their first review. Reviewers are expected to be courteous and clear about what they’re asking you to change and why. While reviewers *do* have the final sign-off, code review should be considered to be a conversation. Reviewers are not expected to be perfect. If you don’t understand what a reviewer has asked or disagree with their suggestions then respond with your reasoning or ask for clarification. Usually this happens in the code review itself but it is not uncommon to talk with the reviewer directly where that is faster. In this case it is helpful to add a summary of your discussion to the review comment in Phabricator for future code historians. If you have requested reviews from multiple reviewers and one of them requests changes, the patch is removed from all reviewers' queues until you re-submit the patch with the requested changes, questions for clarification or comments. Once you’ve addressed everything the reviewer requested, push your patch up for review again and expect that the reviewer will be verifying that you changed everything requested. To help save unnecessary review iterations, where possible avoid putting the patch back into review until you've made all the necessary changes. Occasionally the reviewer may ask for a small number of changes but still approve the patch. You are expected to make those changes before the patch can land, the reviewer is just indicating that they trust you to make those changes and don’t need to re-review the patch. If those changes turn out to be larger than the reviewer would have reasonably expected then you should re-request review. You’re within your rights to suggest that some review feedback can be fixed in follow-up bugs and patches, so long as you ensure to get those follow-ups filed in Bugzilla and that they’re addressed in a timely manner. This is particularly true for in-progress features that are being held to Nightly. Features still being developed and held to Nightly should not be expected to land in a perfect state all in one patch. ### Code quality Make sure before submitting a patch that it compiles cleanly and that the tests included all pass. Consider re-reading the patch you’ve just submitted to Phabricator once you submit it the first time. Often Phabricator’s clear diff view will highlight things to you that you might have missed, especially if you’ve worked on the patch a long time. It can also help highlight changes that aren’t immediately obvious to someone reading the patch for the first time, and might need an explanation. Avoid whitespace or other trivial changes to code that you don’t need to change to accomplish your goal. Making other, unrelated changes makes the patch harder to review, and makes it difficult to later to find the origin of a change. Several small patches are easier to review than one monolith that changes lots of files. Talk to your peers and prospective reviewer(s) before starting big refactors. Firefox’s code base is huge and refactors carry risk, so reviewers are wary of big changes like that and they are usually difficult to review. ## Technologies and Specifics This section covers some frontend-specific aspects of patches that reviewers are likely to look at. ### JS/DOM * Use existing components to implement feature designs. Do not reimplement custom button/card/toggle/… styling based on the design and vanilla HTML, as it doesn’t scale, is hard to maintain, and will likely miss edge-cases for accessibility, RTL, etc. * The inverse is also true: not every new bit of code you work on has to be factored out as a generic, reusable component immediately. When you are the first/only consumer of a bit of code, it is usually not possible to predict what aspects of your code will need to be “generic”, where API boundaries should be, and so on. Trying to do it immediately is doomed to failure, so don’t spend time on it - save it for when the second potential consumer comes along. * Lines of code is a flawed metric, and we’re not code golfing - but don’t write several 10-line functions when 2 lines of inline code will do. Balance brevity and readability appropriately. * Use DOM properties over attributes where possible. * Where it isn’t, `toggleAttribute` and `classList.toggle` are often helpful to avoid repetitive if/else blocks. ### Styling and CSS, and SVGs * Use existing components/classes to implement feature designs (see JS/DOM section). * Keep in mind all CSS needs to work in RTL languages. Use logical properties (`margin-inline-start` and friends) rather than physical ones (`margin-left`). * See [Firefox RTL (right-to-left) guidelines](/code-quality/coding-style/rtl_guidelines.rst) for more detailed information. * See the [Accessibility](#accessibility) section on use of colours, HCM, etc. * See detailed [CSS authoring guidelines](/code-quality/coding-style/css_guidelines.rst). * See the [Firefox SVG Guidelines](/code-quality/coding-style/svg_guidelines.rst). ### Localization * For anything user-facing, use localised strings. **Do NOT** hardcode English strings in markup. * For new code, use fluent. For modifying older code, use what the old code uses (but consider switching to fluent if it’s straightforward, as it provides better translation primitives in other languages). * When writing experimental features that need strings for en-US only that are not final yet, use fluent and put the ftl file in a `content` rather than `locale` directory and package it accordingly. When strings are final, move them to a regular `locale` directory and include them as normal but make sure to do so outside string freeze and while allowing reasonable time for our (largely volunteer) localisers to submit translations - don’t just dump dozens of strings into `locale` a day before string freeze. * If the meaning of a string changes, or \[in fluent\] you add/remove attributes, **you must update the message identifier**. * More detailed [fluent review guidelines](/l10n/fluent/review.rst#guidelines-for-fluent-reviewers) are available separately. ### Accessibility {#accessibility} * Write semantic HTML. * Anything mouse-accessible should be keyboard-accessible or have a keyboard-accessible equivalent. * Ensure things work in high contrast mode and that there is sufficient colour contrast between foreground and background items in non-high-contrast mode and with different themes. * Any images that **aren’t purely decorative** (e.g. toolbar button icons where there is no visible text label) need an `alt` attribute or `aria-label` or similar to give it an accessible name, as well as a tooltip for sighted users who might not understand icons. * Any images that **are** purely **decorative** (e.g. illustrations next to text) should be implemented using one of these options: * CSS background images, which have no representation in the accessibility tree * HTML `img` elements that use `role=presentation` to remove them from the accessibility tree, and do not have an alt attribute. * If implementing animations or transitions, do so behind a `prefers-reduced-motion` media query to ensure people who have epilepsy or other motion-triggered sensitivities are not hurt by our attempts to make things beautiful. * The first rule of ARIA is “don’t use ARIA” (see also “Write semantic HTML”) - but it can be a tool where semantic markup is insufficient (e.g. live regions, complex labeling structures). ### Performance * Avoid [style](https://firefox-source-docs.mozilla.org/performance/bestpractices.html#detecting-and-avoiding-synchronous-style-flushes) and [layout](https://firefox-source-docs.mozilla.org/performance/bestpractices.html#detecting-and-avoiding-synchronous-reflow) flushes. * Use `requestIdleCallback` and/or workers for anything on the startup path and/or CPU or disk-intensive work that doesn’t actually need to happen immediately. * Use `IOUtils` to do async File IO, rather than nsIFile for synchronous access. * Keep complexity in mind and use reasonable data structures * e.g. use a Set rather than arrays if they’re big, unordered, and you need to look items up in the collection * Bear in mind that some collections/loops may be reasonably sized in the common case, but have pathological edge cases (that person with 3652 tabs is looking at you. You know who I mean\!). You shouldn’t need to jump through too many hoops, but use memoization or association (which are O(1) or O(log n)) rather than “just” looping through the list (which is O(n)). * Other than that, don’t over-optimize things unless the code is known to be hot/performance-sensitive. * As an example, we don’t, as a rule, use `for (var i; i < ary.length; i++)` style “raw” array loops, instead preferring the more readable `for (let item of ary)`, even though that is slightly less performant. ### Security * When in doubt, ask the security team, and/or `#security` on slack. * Take care when communicating between processes or with web content. Specifically: * We can’t trust web content. * We can’t trust web content processes (!). Any information you get via IPC (JSActor messages or similar) could be completely bogus. Use information from the parent process (the CanonicalBrowsingContext and so on) to make security decisions wherever possible. * As a corollary, if you have code that wants to navigate or interact with web content, do it entirely within the content process, rather than passing e.g. URIs or similar information to the parent and expecting it to navigate for you. This avoids exposing APIs to (potentially compromised) content processes that let them navigate arbitrarily - the “basic” APIs for that (`document.location` and so on) will be secured by Gecko itself, and we want to reuse that infrastructure as much as possible. * Do not load untrusted content (ie content from the web) in the parent process. * XSS and markup related advice: * Avoid inline event handlers wherever possible. * All `about:` pages must have a Content Security Policy (CSP). Use one that prevents inline styles and inline script. * Do not use `innerHTML`. * Gecko has built in sanitizer APIs - if you have to deal with untrusted HTML, see [nsIParserUtils](https://searchfox.org/firefox-main/source/parser/html/nsIParserUtils.idl). Do NOT hand-roll sanitizing inputs. * Other vectors to take into account: * URLs are malleable and not a good way of identifying an origin. Use nsIPrincipal objects. You’ll need this to deal correctly with `blob` URIs, `about:blank`, and data URIs. * We can’t assume that for `something.foo.sometld`, `something` is a subdomain of `foo`, or that `foo.sometld` is the “top” domain. Some TLDs (`.co.uk` and `.org.uk` and so on are an obvious example, but `github.io` and `s3.dualstack.ap-northeast-1.amazonaws.com`, too\!) have individually controlled subdomains. Use [nsIEffectiveTLDService](https://searchfox.org/firefox-main/source/netwerk/dns/nsIEffectiveTLDService.idl) to work out what the “top” domain is. Do not use manual string manipulation. * Spoofing: where an attacker tries to pretend to the user they’re on a different website, usually by overlaying content or markup over the address bar or other trusted UI, or using full screen or similar tricks. * Clickjacking/keyjacking: where an attacker encourages users to click or hit keys repeatedly (“win $50 if you [hook a duck](https://en.wikipedia.org/wiki/Hook-a-duck) by clicking this button really fast”), and uses that to bypass security warnings. Typical defence: delay enabling buttons on security-critical dialogs - there’s even a [helper](https://searchfox.org/mozilla-central/rev/d00845a44a8d1bf3f472ff36fd3f22a03af30a76/toolkit/components/prompts/src/PromptUtils.sys.mjs#49-61) for this. * Crypto: do not make up your own cryptography, random number generator, password/key management or similar. Talk to experts (some of them work at Mozilla)\! ### Testing * All patches must have automated tests where possible and practical. * When writing tests, be sure to see that you’ve seen your test fail. This helps to avoid scenarios where a test always passes even when it shouldn’t. * There are some patches where it may be appropriate not to have tests, particularly ones that only touch documentation, styling (CSS/images), or test-only changes. * For situations where you can’t write tests, such as with features that interact with the operating system in ways we can’t verify automatically, leave a comment explaining why to the reviewer. It is likely going to be the first question they ask and they should know when one of these situations applies or may know alternate ways to write the test. * If you’ve pushed to try, leaving a link to the try push on Phabricator can help avoid duplicating effort (Note: reviewers are not expected to create try pushes by default). If there are unclear test failures that may or may not be intermittent, your reviewer can help work out what is happening. ### Documentation * Ideally, code should be readable without explanation. Where documentation is required, use code comments for individual pieces of code, and the extended commit message (i.e. the second/third/nth lines of the commit message) to describe the high-level goal of your change. * A guideline for code comments is to add them in cases where they provide additional context for *why* a change is being made, but to avoid adding them if the comment only restates *what* the code is doing. * If the reviewer asks for explanations, this is often a sign that the code should be simplified, it needs more code comments, or the approach in the patch is not right. Prefer code and/or comment changes over communicating only in Phabricator - so that future readers of the code have the same context. * Ensure that any existing Firefox Source Docs material is also updated to reflect the change. ## Commandeering patches Patches should only be commandeered by agreement with the original patch author or if the author cannot be expected to respond in a timely fashion (on vacation or sick leave or no longer active in the project). If you do need to commandeer a patch you can preserve the original author with `git commit --amend --author="Other Person "` when amending the original commit. ## Community Participation Guidelines Please remember to always abide by [the Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/). Be generous and inclusive. Always assume good intentions, even where there is a disagreement during the course of the review. ## FAQ ### What is a Nit? A nit is a minor defect. This could be a typo or a small issue. These are usually the kind of things that would *not result in a “request for changes”*, but they should be called out and it’s expected that they would be addressed by the patch author before the patch lands. ### How do I file a bug for new lint rules? [If you have an idea for an eslint (JS) or stylelint (CSS) rule you can file a bug here](https://bugzilla.mozilla.org/enter_bug.cgi?product=Developer%20Infrastructure&component=Lint%20and%20Formatting) if a more specific component isn’t a better fit. ## Further Reading * [Code review antipatterns](https://www.chiark.greenend.org.uk/~sgtatham/quasiblog/code-review-antipatterns/) an article by Simon Tatham outlining common anti-patterns in code review. --- ### Browser Docs Index (`browser/docs/index.rst`) ================= Firefox Front-end ================= This is the documentation for the code powering the Firefox Desktop front-end. .. toctree:: :maxdepth: 2 how_to/index urlbar/index BrowserUsageTelemetry FrontendCodeReviewBestPractices CommandLineParameters BrowserStartup CategoryManagerIndirection components/customizableui/docs/index components/enterprisepolicies/docs/index components/taskbartabs/docs/index extensions/formautofill/docs/index extensions/newtab/docs/index components/aboutwelcome/docs/index installer/windows/installer/index components/attribution/docs/index /toolkit/mozapps/defaultagent/default-browser-agent/index components/migration/docs/index components/pagedata/docs/index places/index components/asrouter/docs/index search/index base/tabbrowser/index touchbar/index components/uitour/docs/index branding/docs/index components/storybook/docs/README.storybook.stories components/storybook/docs/README.reusable-widgets.stories components/storybook/docs/README.other-widgets.stories components/storybook/docs/README.lit-guide.stories components/storybook/docs/README.xul-and-html.stories components/storybook/docs/README.figma-code-connect.stories /toolkit/themes/shared/design-system/docs/README.design-tokens.stories components/backup/docs/index components/sidebar/docs/index components/mozcachedohttp/docs/index --- ### Browser Docs Overview (`browser/docs/overview.rst`) Firefox for Desktop =================== Desktop architecture -------------------- One of the keys to understanding how Firefox is architected is to know that Gecko is used to render both web content as well as the UI of the browser. This means that, to a large extent, the UI of Firefox is made using web technologies like HTML, CSS, and JavaScript. For example, the document ``chrome://browser/content/browser.xhtml`` is the markup for a single Firefox browser window. You can think of it almost like index.html for a webpage. The decision to use Gecko for rendering the UI was made during an era when HTML was not yet expressive enough or sufficient to build desktop UIs. A different markup language, `XUL `_, was developed for that purpose instead, which Gecko also knows how to interpret. Since that time, HTML and CSS has evolved to the point where XUL is not strictly necessary for most use-cases. Where possible, we have been gradually migrating our UI to use less XUL and more standard HTML and CSS. Reusable UI Widgets ------------------- Many of the UI widgets in use in the user interface are built as web components that can be reused. :ref:`Read more ` Tabbrowser ---------- The tabbrowser component manages the tabs in a browser window. :ref:`Read more ` Address Bar ----------- The address bar (varyingly also referred to as the Awesome Bar, or Quantum Bar) handles users entering web addresses including a popup with suggestions from various sources including history, bookmarks and search engines. :ref:`Read more
` Search ------ The search service manages the list of search engines available in the address bar. :ref:`Read more ` Places ------ The places component includes the database that stores history and bookmarks as well as a set of UI components that present those to the user. :ref:`Read more ` Firefox Sync and Application Services ------------------------------------- Application services includes the sync engines and Firefox Accounts integration. :ref:`Read more ` Developer Tools --------------- The developer tools support web developers when building webpages but as the Firefox UI is itself built using web technologies it is also possible to use the developer tools to debug the Firefox UI. :ref:`Read more ` Browser Toolbox ############### The Browser Toolbox is a way to launch the developer tools in a separate process so that they can be used to debug the main browser UI. :ref:`Read more ` Profiler ######## The Firefox Profiler is the way to measure the performance of your code. Go to `profiler.firefox.com `__ to enable the button in Firefox and record a performance profile. These profiles can be uploaded and shared. It can identify slow parts of the code, and reveal the underlying behavior of how code runs. Installer --------- The Windows installer for Firefox is built with NSIS. There are currently no installers for other operating systems. :ref:`Read more ` Application Update ------------------ Application Update is responsible for requesting available updates from the update servers, downloading them, verifying their integrity and then ultimately installing them. A binary patch tool (bsdiff) is used to reduce the size of update files and update files are delivered in the bespoke mar (Mozilla ARchive) format. :ref:`Read more ` --- ### Build Docs Build Overview (`build/docs/build-overview.rst`) .. _build_overview: ===================== Build System Overview ===================== This document provides an overview on how the build system works. It is targeted at people wanting to learn about internals of the build system. It is not meant for persons who casually interact with the build system. That being said, knowledge empowers, so consider reading on. The build system is composed of many different components working in harmony to build the source tree. We begin with a graphic overview. .. graphviz:: digraph build_components { rankdir="LR"; "configure" -> "config.status" -> "build backend" -> "build output" } Phase 1: Configuration ====================== Phase 1 centers around the ``configure`` script, which is a bash shell script. The file is generated from a file called ``configure.in`` which is written in M4 and processed using Autoconf 2.13 to create the final configure script. You don't have to worry about how you obtain a ``configure`` file: the build system does this for you. The primary job of ``configure`` is to determine characteristics of the system and compiler, apply options passed into it, and validate everything looks OK to build. The primary output of the ``configure`` script is an executable file in the object directory called ``config.status``. ``configure`` also produces some additional files (like ``autoconf.mk``). However, the most important file in terms of architecture is ``config.status``. The existence of a ``config.status`` file may be familiar to those who have worked with Autoconf before. However, Mozilla's ``config.status`` is different from almost any other ``config.status`` you've ever seen: it's written in Python! Instead of having our ``configure`` script produce a shell script, we have it generating Python. Now is as good a time as any to mention that Python is prevalent in our build system. If we need to write code for the build system, we do it in Python. That's just how we roll. For more, see :ref:`python`. ``config.status`` contains 2 parts: data structures representing the output of ``configure`` and a command-line interface for preparing/configuring/generating an appropriate build backend. (A build backend is merely a tool used to build the tree - like GNU Make or Tup). These data structures essentially describe the current state of the system and what the existing build configuration looks like. For example, it defines which compiler to use, how to invoke it, which application features are enabled, etc. You are encouraged to open up ``config.status`` to have a look for yourself! Once we have emitted a ``config.status`` file, we pass into the realm of phase 2. Phase 2: Build Backend Preparation and the Build Definition =========================================================== Once ``configure`` has determined what the current build configuration is, we need to apply this to the source tree so we can actually build. What essentially happens is the automatically-produced ``config.status`` Python script is executed as soon as ``configure`` has generated it. ``config.status`` is charged with the task of tell a tool how to build the tree. To do this, ``config.status`` must first scan the build system definition. The build system definition consists of various ``moz.build`` files in the tree. There is roughly one ``moz.build`` file per directory or per set of related directories. Each ``moz.build`` files defines how its part of the build config works. For example it says *I want these C++ files compiled* or *look for additional information in these directories.* config.status starts with the ``moz.build`` file from the root directory and then descends into referenced ``moz.build`` files by following ``DIRS`` variables or similar. As the ``moz.build`` files are read, data structures describing the overall build system definition are emitted. These data structures are then fed into a build backend, which then performs actions, such as writing out files to be read by a build tool. e.g. a ``make`` backend will write a ``Makefile``. When ``config.status`` runs, you'll see the following output:: Reticulating splines... Finished reading 1096 moz.build files into 1276 descriptors in 2.40s Backend executed in 2.39s 2188 total backend files. 0 created; 1 updated; 2187 unchanged Total wall time: 5.03s; CPU time: 3.79s; Efficiency: 75% What this is saying is that a total of *1096* ``moz.build`` files were read. Altogether, *1276* data structures describing the build configuration were derived from them. It took *2.40s* wall time to just read these files and produce the data structures. The *1276* data structures were fed into the build backend which then determined it had to manage *2188* files derived from those data structures. Most of them already existed and didn't need changed. However, *1* was updated as a result of the new configuration. The whole process took *5.03s*. Although, only *3.79s* was in CPU time. That likely means we spent roughly *25%* of the time waiting on I/O. For more on how ``moz.build`` files work, see :ref:`mozbuild-files`. Phase 3: Invocation of the Build Backend ======================================== When most people think of the build system, they think of phase 3. This is where we take all the code in the tree and produce Firefox or whatever application you are creating. Phase 3 effectively takes whatever was generated by phase 2 and runs it. Since the dawn of Mozilla, this has been make consuming Makefiles. However, with the transition to moz.build files, you may soon see non-Make build backends, such as Tup or Visual Studio. When building the tree, most of the time is spent in phase 3. This is when header files are installed, C++ files are compiled, files are preprocessed, etc. --- ### Build Docs Build Targets (`build/docs/build-targets.rst`) .. _build_targets: ============= Build Targets ============= When you build with ``mach build``, there are some special targets that can be built. This page attempts to document them. Partial Tree Targets ==================== The targets in this section only build part of the tree. Please note that partial tree builds can be unreliable. Use at your own risk. export Build the *export* tier. The *export* tier builds everything that is required for C/C++ compilation. It stages all header files, processes IDLs, etc. compile Build the *compile* tier. The *compile* tier compiles all C/C++ files. libs Build the *libs* tier. The *libs* tier performs linking and performs most build steps which aren't related to compilation. tools Build the *tools* tier. The *tools* tier mostly deals with supplementary tools and compiled tests. It will link tools against libXUL, including compiled test binaries. binaries: Recompiles and relinks C/C++ files. Only works after a complete normal build, but allows for much faster rebuilds of C/C++ code. For performance reasons, however, it skips nss, nspr, icu and ffi. This is targeted to improve local developer workflow when touching C/C++ code. install-manifests Process install manifests. Install manifests handle the installation of files into the object directory. Unless ``NO_REMOVE=1`` is defined in the environment, files not accounted in the install manifests will be deleted from the object directory. install-tests Processes the tests install manifest. Common Actions ============== The targets in this section correspond to common build-related actions. Many of the actions in this section are effectively frontends to shell scripts. These actions will likely all be replaced by mach commands someday. buildsymbols Create a symbols archive for the current build. This must be performed after a successful build. check Run build system tests. --- ### Build Docs Chrome Registration (`build/docs/chrome-registration.rst`) Chrome Registration ------------------- What is chrome? --------------- `Chrome` is the set of user interface elements of the application window that are outside the window's content area. Toolbars, menu bars, progress bars, and window title bars are all examples of elements that are typically part of the chrome. ``chrome.manifest`` files are used to register XPCOM components and sources for the chrome protocol. Every application supplies a root ``chrome.manifest`` file that Mozilla reads on startup. Chrome providers ---------------- A supplier of chrome for a given window type (e.g., for the browser window) is called a chrome provider. The providers work together to supply a complete set of chrome for a particular window, from the images on the toolbar buttons to the files that describe the text, content, and appearance of the window itself. There are three basic types of chrome providers: Content The main source file for a window description comes from the content provider, and it can be any file type viewable from within Mozilla. It will typically be a XUL file, since XUL is designed for describing the contents of windows and dialogs. The JavaScript files that define the user interface are also contained within the content packages. Locale Localizable applications keep all their localized information in locale providers and Fluent FTL files, which are handled separately. This allows translators to plug in a different chrome package to translate an application without altering the rest of the source code. In a chrome provider, localizable files are mostly Java-style properties files. Skin A skin provider is responsible for providing a complete set of files that describe the visual appearance of the chrome. Typically a skin provider will provide CSS files and images. The chrome registry ------------------- The Gecko runtime maintains a service known as the chrome registry that provides mappings from chrome package names to the physical location of chrome packages on disk. This chrome registry is configurable and persistent, and thus a user can install different chrome providers, and select a preferred skin and locale. This is accomplished through xpinstall and the extension manager. In order to inform the chrome registry of the available chrome, a text manifest is used: this manifest is "chrome.manifest" in the root of an extension, or theme, or XULRunner application. The plaintext chrome manifests are in a simple line-based format. Each line is parsed individually; if the line is parsable the chrome registry takes the action identified by that line, otherwise the chrome registry ignores that line (and prints a warning message in the runtime error console). .. code:: text locale packagename localename path/to/files skin packagename skinname path/to/files .. note:: The characters @ # ; : ? / are not allowed in the packagename. Manifest instructions --------------------- comments ~~~~~~~~ .. code:: text # this line is a comment - you can put here whatever you want A line is a comment if it begins with the character '#'. Any following character in the same line is ignored. manifest ~~~~~~~~ :: manifest subdirectory/foo.manifest [flags] This will load a secondary manifest file. This can be useful for separating component and chrome registration instructions, or separate platform-specific registration data. component ~~~~~~~~~ :: component {00000000-0000-0000-0000-000000000000} components/mycomponent.js [flags] Informs Mozilla about a component CID implemented by an XPCOM component implemented in JavaScript (or another scripting language, if applicable). The ClassID {0000...} must match the ClassID implemented by the component. To generate a unique ClassID, use a UUID generator program or site. contract ~~~~~~~~ :: contract @foobar/mycontract;1 {00000000-0000-0000-0000-000000000000} [flags] Maps a contract ID (a readable string) to the ClassID for a specific implementation. Typically a contract ID will be paired with a component entry immediately preceding. category ~~~~~~~~ :: category category entry-name value [flags] Registers an entry in the `category manager`. The specific format and meaning of category entries depend on the category. content ~~~~~~~ A content package is registered with the line: :: content packagename uri/to/files/ [flags] This will register a location to use when resolving the URI ``chrome://packagename/content/...``. The URI may be absolute or relative to the location of the manifest file. Note: it must end with a '/'. locale ~~~~~~ A locale package is registered with the line: .. code:: text locale packagename localename uri/to/files/ [flags] This will register a locale package when resolving the URI chrome://*packagename*/locale/... . The *localename* is usually a plain language identifier "en" or a language-country identifier "en-US". If more than one locale is registered for a package, the chrome registry will select the best-fit locale using the user's preferences. skin ~~~~ A skin package is registered with the line: .. code:: text skin packagename skinname uri/to/files/ [flags] This will register a skin package when resolving the URI chrome://packagename/skin/... . The *skinname* is an opaque string identifying an installed skin. If more than one skin is registered for a package, the chrome registry will select the best-fit skin using the user's preferences. style ~~~~~ Style overlays (custom CSS which will be applied to a chrome page) are registered with the following syntax: .. code:: text style chrome://URI-to-style chrome://stylesheet-URI [flags] override ~~~~~~~~ In some cases an extension or embedder may wish to override a chrome file provided by the application or XULRunner. In order to allow for this, the chrome registration manifest allows for "override" instructions: .. code:: text override chrome://package/type/original-uri.whatever new-resolved-URI [flags] Note: overrides are not recursive (so overriding chrome://foo/content/bar/ with file:///home/john/blah/ will not usually do what you want or expect it to do). Also, the path inside overridden files is relative to the overridden path, not the original one (this can be annoying and/or useful in CSS files, for example). .. _chrome_manifest_resource: resource ~~~~~~~~ Aliases can be created using the ``resource`` instruction: .. code:: text resource aliasname uri/to/files/ [flags] This will create a mapping for ``resource:///`` URIs to the path given. .. note:: **Note:** There are no security restrictions preventing web content from including content at resource: URIs, so take care what you make visible there. Manifest flags -------------- Manifest lines can have multiple, space-delimited flags added at the end of the registration line. These flags mark special attributes of chrome in that package, or limit the conditions under which the line is used. application ~~~~~~~~~~~ Extensions may install into multiple applications. There may be chrome registration lines which only apply to one particular application. The flag .. code:: text application=app-ID indicates that the instruction should only be applied if the extension is installed into the application identified by *app-ID*. Multiple application flags may be included on a single line, in which case the line is applied if any of the flags match. This example shows how a different overlay can be used for different applications: :: overlay chrome://browser/content/browser.xul chrome://myaddon/content/ffOverlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} overlay chrome://messenger/content/mailWindowOverlay.xul chrome://myaddon/content/tbOverlay.xul application={3550f703-e582-4d05-9a08-453d09bdfdc6} overlay chrome://songbird/content/xul/layoutBaseOverlay.xul chrome://myaddon/content/sbOverlay.xul application=songbird@songbirdnest.com appversion ~~~~~~~~~~ Extensions may install into multiple versions of an application. There may be chrome registration lines which only apply to a particular application version. The flag .. code:: text appversion=version appversionversion appversion>=version indicates that the instruction should only be applied if the extension is installed into the application version identified. Multiple ``appversion`` flags may be included on a single line, in which case the line is applied if any of the flags match. The version string must conform to the `Toolkit version format`. platformversion ~~~~~~~~~~~~~~~ When supporting more then one application, it is often more convenient for an extension to specify which Gecko version it is compatible with. This is particularly true for binary components. If there are chrome registration lines which only apply to a particular Gecko version, the flag .. code:: text platformversion=version platformversionversion platformversion>=version indicates that the instruction should only be applied if the extension is installed into an application using the Gecko version identified. Multiple ``platformversion`` flags may be included on a single line, in which case the line is applied if any of the flags match. contentaccessible ~~~~~~~~~~~~~~~~~ Chrome resources can no longer be referenced from within ,