Firefox

https://firefox-source-docs.mozilla.org/
Admin
Firefox is an open-source web browser developed by Mozilla designed for privacy, performance, and...
Tokens:4,010,189
Snippets:29,877
Trust Score:10
Update:1 day ago
Show doc for...
Tokens:
Raw
### Simple example: install, get binary, uninstall

Source: https://firefox-source-docs.mozilla.org/mozbase/mozinstall.html

Shows the basic workflow: create a temp directory, install a Firefox DMG, locate the binary, and uninstall. The binary can then be executed directly.

```python
import mozinstall
import tempfile

tempdir = tempfile.mkdtemp()
firefox_dmg = 'firefox-38.0a1.en-US.mac.dmg'
install_folder = mozinstall.install(src=firefox_dmg, dest=tempdir)
binary = mozinstall.get_binary(install_folder, 'Firefox')
# from here you can execute the binary directly
# ...
mozinstall.uninstall(install_folder)
```

--------------------------------

### Example command with default installation paths

Source: https://firefox-source-docs.mozilla.org/contributing/debugging/capturing_minidump.html

Concrete example for 64-bit Firefox when both the debugging tools and Firefox are installed in default folders. Note that double quotes are required when a path contains whitespace.

```batch
"C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe" -g -G -o "C:\Program Files\Mozilla Firefox\firefox.exe"
```

--------------------------------

### AddonManager.installAddonFromWebpage

Source: https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html

Starts installation of an AddonInstall notifying the registered web install listener of a blocked or started install.

```APIDOC
## AddonManager.installAddonFromWebpage

### Description
Starts installation of an AddonInstall notifying the registered web install listener of a blocked or started install.

### Method
static

### Signature
`static AddonManager.installAddonFromWebpage(aMimetype, aBrowser, aInstallingPrincipal, aInstall, aDetails)`

### Parameters
- **aMimetype** – The mimetype of the add-on being installed
- **aBrowser** – The browser element that started the install
- **aInstallingPrincipal** – The nsIPrincipal that initiated the install
- **aInstall** – The AddonInstall to be installed
- **aDetails** – Additional optional details
  - **aDetails.hasCrossOriginAncestor** – Boolean value set to true if any of cross-origin ancestors of the triggering frame (if set to true the installation will be denied).
```

--------------------------------

### Install push-to-try extension with mach vcs-setup

Source: https://firefox-source-docs.mozilla.org/tools/try/configuration.html

Run this command to install the `push-to-try` extension, which is required for using `mach try` to push to Try. This is the recommended setup step after obtaining Level 1 Commit Access.

```bash
mach vcs-setup
```

--------------------------------

### AddonManager.installSitePermsAddonFromWebpage(aBrowser, aInstallingPrincipal, aPermission)

Source: https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html

Starts installation of a SitePermsAddonInstall, notifying the registered web install listener of a blocked or started install. Returns a Promise that resolves when the user installs the addon, or rejects if blocked or unsupported.

```APIDOC
## AddonManager.installSitePermsAddonFromWebpage(aBrowser, aInstallingPrincipal, aPermission)

### Description
Starts installation of a SitePermsAddonInstall, notifying the registered web install listener of a blocked or started install. Returns a Promise that resolves when the user installs the addon, or rejects if blocked or unsupported.

### Method
static

### Arguments
- **aBrowser** (optional) - The optional browser element that started the install.
- **aInstallingPrincipal** (nsIPrincipal) - Required - The principal that initiated the install.
- **aPermission** (string) - Required - The permission to install.

### Throws
- **Components.Exception** - Thrown if the AddonManager is not initialized or if `aInstallingPrincipal` is not a nsIPrincipal.

### Returns
- **Promise** - Resolves when the user installs the addon. Rejects if the user blocked the install or if the addon can't be installed (e.g., the principal isn't supported).
```

--------------------------------

### AddonManager.installAddonFromAOM

Source: https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html

Starts installation of an AddonInstall created from add-ons manager front-end code (e.g., drag-and-drop of xpis or “Install Add-on from File”).

```APIDOC
## AddonManager.installAddonFromAOM

### Description
Starts installation of an AddonInstall created from add-ons manager front-end code (e.g., drag-and-drop of xpis or “Install Add-on from File”).

### Method
static

### Signature
`static AddonManager.installAddonFromAOM(browser, uri, install, options)`

### Parameters
- **browser** – The browser element where the installation was initiated
- **uri** – The URI of the page where the installation was initiated
- **install** – The AddonInstall to be installed
- **options** – Optional - An object containing the following options: “options.preferUpdateOverInstall” - Prefer update over install when there is an existing add-on for the `install` object.
```

--------------------------------

### UserInteraction.start() example with and without object

Source: https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/obsolete/collection/user-interactions.html

Example showing start() with an object and without an object. Returns false and logs a message to the browser console if the recording does not start for some reason.

```javascript
UserInteraction.start("browser.tabs.opening", "animated", window);
UserInteraction.start("browser.places.history_search", "synchronous");
```

--------------------------------

### ADBHost.start_server()

Source: https://firefox-source-docs.mozilla.org/mozbase/devicemanagement.html

Starts the ADB server.

```APIDOC
## ADBHost.start_server()

### Description
Starts the ADB server.

### Method
start_server

### Parameters
None

### Returns
None
```

--------------------------------

### Show help for structured_example.py

Source: https://firefox-source-docs.mozilla.org/mozbase/mozlog.html

Running the script with --help displays the available command line options for logging output. Each option takes a filename or '-' to write to stdout.

```bash
$ python structured_example.py --help

usage: structured_example.py [-h] [--log-unittest LOG_UNITTEST]
                             [--log-raw LOG_RAW] [--log-html LOG_HTML]
                             [--log-xunit LOG_XUNIT]
                             [--log-mach LOG_MACH]

optional arguments:
  -h, --help            show this help message and exit

Output Logging:
  Options for logging output. Each option represents a possible logging
  format and takes a filename to write that format to, or '-' to write to
  stdout.

  --log-unittest LOG_UNITTEST
                        Unittest style output
  --log-raw LOG_RAW     Raw structured log messages
  --log-html LOG_HTML   HTML report
  --log-xunit LOG_XUNIT
                        xUnit compatible XML
  --log-mach LOG_MACH   Human-readable output

```

--------------------------------

### Implement a setup function for ruff

Source: https://firefox-source-docs.mozilla.org/code-quality/lint/create.html

Python setup function that installs the `ruff` package if it is not already available. It takes the repository root as an argument and uses `subprocess.call` to run `pip install ruff`. The function should return quickly and produce no output when no setup is needed.

```python
import subprocess
from shutil import which


def setup(root, **lintargs):
    # This is a simple example. Please look at the actual source for better examples.
    if not which("ruff"):
        subprocess.call(["pip", "install", "ruff"])
```

--------------------------------

### LintRoller.setup(virtualenv_manager=None)

Source: https://firefox-source-docs.mozilla.org/python/mozlint.html

Runs setup for applicable linters.

```APIDOC
## Method: setup(virtualenv_manager=None)

### Description
Runs setup for applicable linters.

### Parameters
- **virtualenv_manager** (object) - Optional - Virtualenv manager to use for setup.
```

--------------------------------

### attributionData usage example

Source: https://firefox-source-docs.mozilla.org/browser/components/asrouter/docs/targeting-attributes.html

Example of using the attributionData targeting attribute to check if the browser was installed via the 'back_to_school' campaign.

```plaintext
attributionData && attributionData.campaign == "back_to_school"
```

--------------------------------

### Example data for startup_about_home_paint

Source: https://firefox-source-docs.mozilla.org/testing/perfdocs/talos.html

Example data output from the startup_about_home_paint test, showing timestamps in milliseconds for 20 runs.

```json
[1503.0, 1497.0, 1523.0, 1536.0, 1511.0, 1485.0, 1594.0, 1580.0, 1531.0, 1471.0, 1502.0, 1520.0, 1488.0, 1533.0, 1531.0, 1502.0, 1486.0, 1489.0, 1487.0, 1475.0]
```

--------------------------------

### static AddonManager.startup

Source: https://firefox-source-docs.mozilla.org/toolkit/mozapps/extensions/addon-manager/AddonManager.html

Initializes the AddonManager, loading any known providers and initializing them.

```APIDOC
## static AddonManager.startup

### Description
Initializes the AddonManager, loading any known providers and initializing them.

### Method
static
```

--------------------------------

### TEST_HARNESS_FILES.foo += ['foo.py']

Source: https://firefox-source-docs.mozilla.org/build/buildsystem/mozbuild-symbols.html

Appends a file to the TEST_HARNESS_FILES variable to install it into a subdirectory under $objdir/_tests. The example installs foo.py into _tests/foo.

```python
TEST_HARNESS_FILES.foo += ['foo.py']
```

--------------------------------

### Install libc6-prof on Ubuntu

Source: https://firefox-source-docs.mozilla.org/performance/jit_profiling_with_perf.html

Install the libc6-prof package to get frame pointers for libc calls, improving symbol resolution.

```bash
sudo apt-get install libc6-prof
```

--------------------------------

### mozinstall.install(src, dest, verify=True, dmg_tool=None, hfs_tool=None)

Source: https://firefox-source-docs.mozilla.org/mozbase/mozinstall.html

Installs a zip, exe, tar.gz, tar.bz2, tar.xz, or dmg file and returns the path of the installation folder. Supports optional verification and custom dmg/hfs tools.

```APIDOC
## mozinstall.install(src, dest, verify=True, dmg_tool=None, hfs_tool=None)

### Description
Installs a zip, exe, tar.gz, tar.bz2, tar.xz or dmg file, and returns the path of the installation folder.

### Method
Function call

### Signature
`mozinstall.install(src, dest, verify=True, dmg_tool=None, hfs_tool=None)`

### Parameters
- **src** (str) - Required - Path to the install file.
- **dest** (str) - Required - Path to install to (to ensure we do not overwrite any existent files the folder should not exist yet).
- **verify** (bool) - Optional - Whether to verify the checksum of a dmg file when mounting it. Only affects dmg files on macOS; other formats verify integrity as part of extraction.
- **dmg_tool** (str) - Optional - Path to the libdmg-hfsplus dmg tool. Together with hfs_tool, lets a dmg file be extracted without mounting it. Defaults to the DMG_TOOL build config or environment variable, then to dmg/dmg in MOZ_FETCHES_DIR.
- **hfs_tool** (str) - Optional - Path to the libdmg-hfsplus hfsplus tool. Defaults to the HFS_TOOL build config or environment variable, then to dmg/hfsplus in MOZ_FETCHES_DIR.

### Returns
- **str** - Path of the installation folder.

### Example
```python
import mozinstall
import tempfile

tempdir = tempfile.mkdtemp()
firefox_dmg = 'firefox-38.0a1.en-US.mac.dmg'
install_folder = mozinstall.install(src=firefox_dmg, dest=tempdir)
```
```

--------------------------------

### start_server() (mozdevice.ADBHost method)

Source: https://firefox-source-docs.mozilla.org/genindex.html

Method of the ADBHost class in the mozdevice module. Starts the ADB server.

```APIDOC
## start_server()

### Description
Starts the ADB server.

### Class
ADBHost

### Module
mozdevice

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Check Browsertime setup manually

Source: https://firefox-source-docs.mozilla.org/testing/perfdocs/browsertime.html

Use this command to manually check your Browsertime setup without installing or updating dependencies.

```bash
./mach browsertime --check
```

--------------------------------

### Example powermetrics output showing coalitions and process metrics

Source: https://firefox-source-docs.mozilla.org/performance/powermetrics.html

Sample output from the quick-start command, showing coalitions like com.apple.Terminal and org.mozilla.firefox with per-process CPU, wakeup, and GPU columns.

```text
*** Sampled system activity (Fri Sep  4 17:15:14 2015 +1000) (5009.63ms elapsed) ***

*** Running tasks ***

Name                               ID     CPU ms/s  User%  Deadlines (<2 ms, 2-5 ms)  Wakeups (Intr, Pkg idle)  GPU ms/s
com.apple.Terminal                 293    447.66                                      274.83  120.35            221.74
  firefox                          84627  77.59     55.55  15.37   2.59               91.42   42.12             204.47
  plugin-container                 84628  377.22    37.18  43.91   18.56              178.65  75.85             17.29
  Terminal                         694    9.86      79.94  0.00    0.00               4.39    2.20              0.00
  powermetrics                     84694  1.21      31.53  0.00    0.00               0.20    0.20              0.00
com.google.Chrome                  489    233.83                                      48.10   25.95             0.00
  Google Chrome Helper             84688  181.57    92.81  0.00    0.00               23.95   12.77             0.00
  Google Chrome                    84681  57.26     76.07  4.39    0.00               23.75   12.97             0.00
  Google Chrome Helper             84685  0.13      48.08  0.00    0.00               0.40    0.20              0.00
kernel_coalition                   1      128.64                                      780.19  330.52            0.00
  kernel_task                      0      109.97    0.00   0.20    0.00               779.47  330.35            0.00
  launchd                          1      18.88     2.44   0.00    0.00               0.40    0.20              0.00
com.apple.Safari                   488    90.60                                       108.58  56.48             26.65
  com.apple.WebKit.WebContent      84679  64.21     84.69  0.00    0.00               104.19  54.89             26.66
  com.apple.WebKit.Networking      84678  26.89     58.89  0.40    0.00               1.60    0.00              0.00
  Safari                           84676  1.56      55.74  0.00    0.00               2.59    1.40              0.00
  com.apple.Safari.SearchHelper    84690  0.15      49.49  0.00    0.00               0.20    0.20              0.00
org.mozilla.firefox                482    76.56                                       124.34  63.47             0.00
  firefox                          84496  76.70     89.18  10.58   5.59               124.55  63.48             0.00
```

--------------------------------

### bucketSample transform example

Source: https://firefox-source-docs.mozilla.org/browser/components/asrouter/docs/targeting-guide.html

Hashes the input and returns true if it falls within the given bucket range (start to start + count) out of total buckets. The range wraps around if it exceeds total. Example targets 500 out of 10,000 buckets.

```jexl
// Target 500 out of 10,000 buckets
userId | bucketSample(0, 500, 10000)
```

--------------------------------

### Human logging output example

Source: https://firefox-source-docs.mozilla.org/mach/logging.html

Example of the human-readable output produced by the human logger for the direct logging example. It prepends the time since application start and formats the message.

```text
0.52 My name is Gregory
```

--------------------------------

### start() (mozhttpd.MozHttpd method)

Source: https://firefox-source-docs.mozilla.org/genindex.html

Method of the MozHttpd class in the mozhttpd module. Starts the HTTP server.

```APIDOC
## start()

### Description
Starts the HTTP server.

### Class
MozHttpd

### Module
mozhttpd

### Parameters
No parameters documented.

### Returns
No return value documented.
```

--------------------------------

### Install GeckoView example APK

Source: https://firefox-source-docs.mozilla.org/testing/perfdocs/webextension.html

Installs the geckoview_example.apk on the Android device. The '-g' flag automatically grants all application permissions, which is required.

```bash
$ adb install -g ../Downloads/geckoview_example.apk
```

--------------------------------

### Show build-bergamot.py help

Source: https://firefox-source-docs.mozilla.org/toolkit/components/translations/resources/03_bergamot.html

Displays additional options and up-to-date documentation for building Bergamot.

```bash
./build-bergamot.py --help
```

--------------------------------

### Skip automatic certificate installation

Source: https://firefox-source-docs.mozilla.org/networking/NodeServers.html

Shows how to skip automatic certificate installation for a NodeHTTPSServer by setting _skipCert to true before starting the server.

```javascript
let server = new NodeHTTPSServer();
server._skipCert = true;
await server.start();
```

--------------------------------

### Bootstrap Firefox on Windows

Source: https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html

Commands to set up Firefox on Windows. Creates a mozilla-source directory, downloads bootstrap.py, and runs it. The download can take 40 minutes to two hours and the repository is less than 5GB (~20GB after build).

```bash
cd c:/
mkdir mozilla-source
cd mozilla-source
wget https://raw.githubusercontent.com/mozilla-firefox/firefox/refs/heads/main/python/mozboot/bin/bootstrap.py

python3 bootstrap.py
```

--------------------------------

### Start device and gecko process separately

Source: https://firefox-source-docs.mozilla.org/mozbase/mozrunner.html

Device runners have a `device` object. The emulator can be started independently of the gecko process. `runner.device.start()` launches the emulator, while `runner.start()` stops the gecko process (if started), installs the profile, and (re)starts the gecko process.

```python
runner.device.start()  # launches the emulator
runner.start()  # stops the gecko process (if started), installs the profile, (re)starts the gecko process
```

--------------------------------

### AddonManager.getInstallForFile()

Source: https://firefox-source-docs.mozilla.org/genindex.html

Creates an install for a local file.

```APIDOC
## AddonManager.getInstallForFile()

### Description
Creates an install for a local file.

### Method
getInstallForFile

### Parameters
- **file** (object) - Required - The file object.
- **mimetype** (string) - Optional - The MIME type of the file.

### Returns
- **Promise** - Resolves to an install object.

```

--------------------------------

### Quick start commands for setting up a Firefox checkout with jj

Source: https://firefox-source-docs.mozilla.org/contributing/jujutsu.html

Run these commands after installing git and jj. Choose either a fresh clone or use an existing Git clone. The commands set up jj configuration, track remote bookmarks, list untracked bookmarks, and move the working copy commit to main.

```shell
# Create a clone and enter the directory. Use one of the following

# (1) Fresh clone:
jj git clone https://github.com/mozilla-firefox/firefox
cd firefox
./mach vcs-setup

# (2) Or if you have a Git clone already:
./mach vcs-setup --vcs=jj

# Set up jujutsu default configuration (which will affect e.g. the default `jj log` output)
./mach vcs-setup

# Track remote bookmarks (you can do this for the other bookmarks, too)
jj bookmark track main@origin autoland@origin beta@origin release@origin

# To see the other untracked bookmarks on that remote:
jj bookmark list --remote origin -T 'if(!tracked && remote, name ++ "@" ++ remote ++ "\n")'

# Move the working copy commit to bookmarks/central
jj new main
```

--------------------------------

### UserInteraction.start() example with concurrent recordings

Source: https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/obsolete/collection/user-interactions.html

Example of starting two User Interactions with the same id but different objects (window1 and window2) to allow concurrent recordings.

```javascript
UserInteraction.start("browser.tabs.opening", "animated", window1);
UserInteraction.start("browser.tabs.opening", "animated", window2);
```

--------------------------------

### Set environment variables and launch Firefox (Windows command prompt)

Source: https://firefox-source-docs.mozilla.org/dom/loggingKeyboardIME.html

Use this in a Windows command prompt to enable logging from startup. Set MOZ_LOG to 'KeyboardHandler:4,IMEHandler:4,sync' and MOZ_LOG_FILE to a full path, then start Firefox. Replace <username> with your home folder name.

```batch
set MOZ_LOG=KeyboardHandler:4,IMEHandler:4,sync
set MOZ_LOG_FILE=C:\Users\<username>\firefox-log
start firefox
```

--------------------------------

### TEST_HARNESS_FILES.path with / and ! prefixes

Source: https://firefox-source-docs.mozilla.org/build/buildsystem/mozbuild-symbols.html

Installs files from topsrcdir (prefix '/') and objdir (prefix '!') into the specified subdirectory. The example installs /build/bar.py from topsrcdir and !quux.py from objdir into _tests/path.

```python
TEST_HARNESS_FILES.path += ['/build/bar.py', '!quux.py']
```

--------------------------------

### repack.cfg example

Source: https://firefox-source-docs.mozilla.org/taskcluster/partner-repacks.html

Example repack.cfg file for a partner repository. Contains configuration keys like aus, dist_id, dist_version, platform toggles, locales, and output_dir.

```ini
aus="mozilla-EMEfree"
dist_id="mozilla-EMEfree"
dist_version="1.0"
linux-i686=false
linux-x86_64=false
locales="ach af an ar"  # truncated for display here
mac=true
win32=true
win64=true
output_dir="%(platform)s-EME-free/%(locale)s"
```
Tokens:
Raw