## 1. Project Overview & Quickstart (ungoogled-software/ungoogled-chromium) ## File: README.md # ungoogled-chromium *A lightweight approach to removing Google web service dependency* **Help is welcome!** See the [docs/contributing.md](docs/contributing.md) document for more information. ## Objectives In descending order of significance (i.e. most important objective first): 1. **ungoogled-chromium is Google Chromium, sans dependency on Google web services**. 2. **ungoogled-chromium retains the default Chromium experience as closely as possible**. Unlike other Chromium forks that have their own visions of a web browser, ungoogled-chromium is essentially a drop-in replacement for Chromium. 3. **ungoogled-chromium features tweaks to enhance privacy, control, and transparency**. However, almost all of these features must be manually activated or enabled. For more details, see [Feature Overview](#feature-overview). In scenarios where the objectives conflict, the objective of higher significance should take precedence. ## Content Overview * [Objectives](#objectives) * [Motivation and Philosophy](#motivation-and-philosophy) * [Feature Overview](#feature-overview) * [**Downloads**](#downloads) * [Source Code](#source-code) * [**FAQ**](#faq) * [Building Instructions](#building-instructions) * [Design Documentation](#design-documentation) * [**Contributing, Reporting, Contacting**](#contributing-reporting-contacting) * [Credits](#credits) * [Related Projects](#related-projects) * [License](#license) ## Motivation and Philosophy Without signing in to a Google Account, Chromium does pretty well in terms of security and privacy. However, Chromium still has some dependency on Google web services and binaries. In addition, Google designed Chromium to be easy and intuitive for users, which means they compromise on transparency and control of internal operations. ungoogled-chromium addresses these issues in the following ways: 1. Remove all remaining background requests to any web services while building and running the browser 2. Remove all code specific to Google web services 3. Remove all uses of pre-made binaries from the source code, and replace them with user-provided alternatives when possible. 4. Disable features that inhibit control and transparency, and add or modify features that promote them (these changes will almost always require manual activation or enabling). These features are implemented as configuration flags, patches, and custom scripts. For more details, consult the [Design Documentation](docs/design.md). ## Feature Overview *This section overviews the features of ungoogled-chromium. For more detailed information, it is best to consult the source code.* Contents of this section: * [Key Features](#key-features) * [Enhancing Features](#enhancing-features) * [Borrowed Features](#borrowed-features) * [Supported Platforms and Distributions](#supported-platforms-and-distributions) ### Key Features *These are the core features introduced by ungoogled-chromium.* * Disable functionality specific to Google domains (e.g. Google Host Detector, Google URL Tracker, Google Cloud Messaging, Google Hotwording, etc.) * This includes disabling [Safe Browsing](https://en.wikipedia.org/wiki/Google_Safe_Browsing). Consult [the FAQ for the rationale](https://ungoogled-software.github.io/ungoogled-chromium-wiki/faq#why-is-safe-browsing-disabled). * Block internal requests to Google at runtime. This feature is a fail-safe measure for the above, in case Google changes or introduces new components that our patches do not disable. This feature is implemented by replacing many Google web domains in the source code with non-existent alternatives ending in `qjz9zk` (known as domain substitution; [see docs/design.md](docs/design.md#source-file-processors) for details), then [modifying Chromium to block its own requests with such domains](patches/core/ungoogled-chromium/block-trk-and-subdomains.patch). In other words, no connections are attempted to the `qjz9zk` domain. * Strip binaries from the source code (known as binary pruning; [see docs/design.md](docs/design.md#source-file-processors) for details) ### Enhancing Features *These are the non-essential features introduced by ungoogled-chromium.* * Add many new command-line switches and `chrome://flags` entries to configure new features (which are disabled by default). See [docs/flags.md](docs/flags.md) for the exhaustive list. * Add *Suggestions URL* text field in the search engine editor (`chrome://settings/searchEngines`) for customizing search engine suggestions. * Add more URL schemes allowed to save page schemes. * Add Omnibox search provider "No Search" to allow disabling of searching * Add a custom cross-platform build configuration and packaging wrapper for Chromium. It currently supports many Linux distributions, macOS, and Windows. (See [docs/design.md](docs/design.md) for details on the system.) * Force all pop-ups into tabs * Disable automatic formatting of URLs in Omnibox (e.g. stripping `http://`, hiding certain parameters) * Disable intranet redirect detector (extraneous DNS requests) * This breaks captive portal detection, but captive portals still work. * (Iridium Browser feature change) Prevent URLs with the `trk:` scheme from connecting to the Internet * Also prevents any URLs with the top-level domain `qjz9zk` (as used in domain substitution) from attempting a connection. * (Windows-specific) Do not set the Zone Identifier on downloaded files ### Borrowed Features In addition to the features introduced by ungoogled-chromium, ungoogled-chromium selectively borrows many features from the following projects (in approximate order of significance): * [Inox patchset](https://github.com/gcarq/inox-patchset) * [Bromite](https://github.com/bromite/bromite) * [Debian](https://tracker.debian.org/pkg/chromium) * [Iridium Browser](https://iridiumbrowser.de/) ### Supported Platforms and Distributions [See docs/platforms.md for a list of supported platforms](docs/platforms.md). Other platforms are discussed and tracked in this repository's Issue Tracker. Learn more about using the Issue Tracker under the section [Contributing, Reporting, Contacting](#contributing-reporting-contacting). ## Downloads ### Automated or maintained builds ungoogled-chromium is available in the following **software repositories**: * Arch: Available in the AUR, [see instructions in ungoogled-chromium-archlinux](https://github.com/ungoogled-software/ungoogled-chromium-archlinux) * Debian: Available in OBS, find your [distribution specific instructions](https://github.com/ungoogled-software/ungoogled-chromium-debian) in the Installing section * Ubuntu: Available in the [XtraDeb PPA](https://xtradeb.net/) as [ungoogled-chromium](https://xtradeb.net/apps/ungoogled-chromium/). * Fedora: Available in [COPR](https://copr.fedorainfracloud.org/coprs/) as [`wojnilowicz/ungoogled-chromium`](https://copr.fedorainfracloud.org/coprs/wojnilowicz/ungoogled-chromium/). Also available in [RPM Fusion](https://rpmfusion.org/Configuration) as `chromium-browser-privacy` (outdated). * Gentoo: Available in [`::pf4public`](https://github.com/PF4Public/gentoo-overlay) overlay as [`ungoogled-chromium`](https://github.com/PF4Public/gentoo-overlay/tree/master/www-client/ungoogled-chromium) and [`ungoogled-chromium-bin`](https://github.com/PF4Public/gentoo-overlay/tree/master/www-client/ungoogled-chromium-bin) ebuilds * [OpenMandriva](https://openmandriva.org/) includes ungoogled-chromium as its main browser. The `chromium` package includes all ungoogling patches. * macOS: Available in [Homebrew](https://brew.sh/) as [`ungoogled-chromium`](https://formulae.brew.sh/cask/ungoogled-chromium). Just run `brew install --cask ungoogled-chromium`. Chromium will appear in your `/Applications` directory. * FreeBSD: Available in pkg as [`www/ungoogled-chromium`](https://www.freshports.org/www/ungoogled-chromium/). * OpenBSD: Available in ports as [`www/ungoogled-chromium`](https://github.com/openbsd/ports/tree/master/www/ungoogled-chromium). * [openSUSE](https://www.opensuse.org/): Available as [`ungoogled-chromium`](https://software.opensuse.org//download.html?project=network%3Achromium&package=ungoogled-chromium). If your GNU/Linux distribution is not listed, there are distro-independent builds available via the following **package managers**: * Flatpak: Available [in the Flathub repo](https://flathub.org/apps/details/io.github.ungoogled_software.ungoogled_chromium) as `io.github.ungoogled_software.ungoogled_chromium` * GNU Guix: Available as `ungoogled-chromium` * NixOS/nixpkgs: Available as `ungoogled-chromium` ### Third-party binaries If your operating system is not listed above, you can also try to [**Download binaries from here**](https://ungoogled-software.github.io/ungoogled-chromium-binaries/) *NOTE: These binaries are provided by anyone who are willing to build and submit them. Because these binaries are not necessarily [reproducible](https://reproducible-builds.org/), authenticity cannot be guaranteed; In other words, there is always a non-zero probability that these binaries may have been tampered with. In the unlikely event that this has happened to you, please [report it in a new issue](#contributing-reporting-contacting).* These binaries are known as **contributor binaries**. ## Source Code This repository only contains the common code for all platforms; it does not contain all the configuration and scripts necessary to build ungoogled-chromium. Most users will want to use platform-specific repos, where all the remaining configuration and scripts are provided for specific platforms: [**Find the repo for a specific platform here**](docs/platforms.md). If you wish to include ungoogled-chromium code in your own build process, consider using [the tags in this repo](https://github.com/ungoogled-software/ungoogled-chromium/tags). These tags follow the format `{chromium_version}-{revision}` where * `chromium_version` is the version of Chromium used in `x.x.x.x` format, and * `revision` is a number indicating the version of ungoogled-chromium for the corresponding Chromium version. Additionally, most platform-specific repos extend their tag scheme upon this one. **Building the source code**: [See docs/building.md](docs/building.md) ### Mirrors List of mirrors: * [Codeberg](https://codeberg.org): [main repo](https://codeberg.org/ungoogled-software/ungoogled-chromium) and [ungoogled-software](https://codeberg.org/ungoogled-software) ## FAQ [See the frequently-asked questions (FAQ) on the Wiki](https://ungoogled-software.github.io/ungoogled-chromium-wiki/faq) ## Building Instructions [See docs/building.md](docs/building.md) ## Design Documentation [See docs/design.md](docs/design.md) ## Contributing, Reporting, Contacting * For reporting and contacting, see [SUPPORT.md](SUPPORT.md) * If you're willing to help, check out the [Issue Tracker](https://github.com/ungoogled-software/ungoogled-chromium/issues) and especially issues, which [need help](https://github.com/ungoogled-software/ungoogled-chromium/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) * For contributing (e.g. how to help, submitting changes, criteria for new features), see [docs/contributing.md](docs/contributing.md) * If you have some small contributions that don't fit our criteria, consider adding them to [ungoogled-software/contrib](https://github.com/ungoogled-software/contrib) or [our Wiki](https://github.com/ungoogled-software/ungoogled-chromium-wiki) instead. ## Credits * [The Chromium Project](https://www.chromium.org/) * [Inox patchset](https://github.com/gcarq/inox-patchset) * [Debian](https://tracker.debian.org/pkg/chromium-browser) * [Bromite](https://github.com/bromite/bromite) * [Iridium Browser](https://iridiumbrowser.de/) * The users for testing and debugging, [contributing code](https://github.com/ungoogled-software/ungoogled-chromium/graphs/contributors), providing feedback, or simply using ungoogled-chromium in some capacity. ## Related Projects List of known projects that fork or use changes from ungoogled-chromium: * [Bromite](https://github.com/bromite/bromite) (Borrows some patches. Features builds for Android) * [ppc64le fork](https://github.com/leo-lb/ungoogled-chromium) (Fork with changes to build for ppc64le CPUs) ## License BSD-3-clause. See [LICENSE](LICENSE) --- ## File: devutils/third_party/README.md This directory contains third-party libraries used by devutils. Contents: * [python-unidiff](https://github.com/matiasb/python-unidiff) * For parsing and modifying unified diffs. --- ## File: devutils/README.md # Developer utilities for ungoogled-chromium This is a collection of scripts written for developing on ungoogled-chromium. See the descriptions at the top of each script for more information. --- ## File: docs/building.md # Building ungoogled-chromium The recommended way to build ungoogled-chromium is by consulting [the repository for your supported platform (links here)](platforms.md). * *Linux users*: If your distribution is not listed, you will need to use Portable Linux. If you want to add ungoogled-chromium to your existing Chromium build process, see the next section. Additionally, you may reference the repositories for supported platforms for inspiration. ## Integrating ungoogled-chromium into your Chromium build process Typically, ungoogled-chromium is built from [code in platform-specific repositories](platforms.md). However, ungoogled-chromium can also be included in part or in whole into any custom Chromium build. In this section, **we will assume you already have a process to make your own Chromium builds**. **NOTE**: You may need additional patches and/or build configuration for [your supported platform](platforms.md) because this repository does not contain all the code necessary for all platforms. Before continuing, you may find it helpful to have a look through [the design documentation](design.md). The following procedure outline the essential steps to build Chromium will all of ungoogled-chromium's features. **They are not sufficient to build ungoogled-chromium on their own**. 1. Ensure Chromium is downloaded, such as by `depot_tools`. In most of our supported platforms, we instead use a custom tool to do this. ```sh mkdir -p build/download_cache ./utils/downloads.py retrieve -c build/download_cache -i downloads.ini ./utils/downloads.py unpack -c build/download_cache -i downloads.ini -- build/src ``` 2. Prune binaries ```sh ./utils/prune_binaries.py build/src pruning.list ``` 3. Apply patches ```sh ./utils/patches.py apply build/src patches ``` 4. Substitute domains ```sh ./utils/domain_substitution.py apply -r domain_regex.list -f domain_substitution.list -c build/domsubcache.tar.gz build/src ``` 5. Build GN. If you are using `depot_tools` to checkout Chromium or you already have a GN binary, you should skip this step. ```sh mkdir -p build/src/out/Default cd build/src ./tools/gn/bootstrap/bootstrap.py --skip-generate-buildfiles -j4 -o out/Default/ ``` 6. Invoke the build: ``` mkdir -p build/src/out/Default # NOTE: flags.gn contains only a subset of what is needed to run the build. cp flags.gn build/src/out/Default/args.gn cd build/src # If you have additional GN flags to add, make sure to add them now. ./out/Default/gn gen out/Default --fail-on-unused-args ninja -C out/Default chrome chromedriver chrome_sandbox ``` ## Building FAQ ### My build keeps crashing because I run out of RAM! How can I fix it? Here are several ways to address this, in decreasing order of preference: 1. Decrease the number of parallel threads to Ninja (the `-j` flag) 2. Add swap space --- ## File: docs/contributing.md # Contributing This document contains our criteria and guidelines for contributing to ungoogled-chromium. If you have **small contributions that don't fit our criteria**, consider adding them to [ungoogled-software/contrib](https://github.com/ungoogled-software/contrib) or [our Wiki](https://github.com/ungoogled-software/ungoogled-chromium-wiki) instead. If you are a developer of an **officially-supported platform**, be sure to check out the [Platform Repository Standards and Guidelines](repo_management.md). List of contents: * [How to help](#how-to-help) * [Submitting changes](#submitting-changes) * [Criteria for new features](#criteria-for-new-features) ### How to help Generally, ungoogled-chromium needs contributors to help: * Keep up-to-date with the latest stable Chromium, and any problematic changes in the new version that needs modification. * Help with issues marked with the `help wanted` tag (usually either questions for other users, or request for help from other developers) * Review Pull Requests from other contributors * Implement feature requests ("enhancements" in the Issue Tracker), large or small. * Implement issues marked with the `backlog` tag (that are closed). * If it requires new code, please read through the [Submitting changes](#submitting-changes) section below. In addition, anyone is free to help others in need of support in the Issue Tracker. If there are fixes, tweaks, or additions you want to make, continue onto the following section. ### Submitting changes Please submit all changes via Pull Requests. Guidelines: * You are welcome to submit minor changes, such as bug fixes, documentation fixes, and tweaks. * If your change has an associated issue, please let others know that you are working on it. * If you want to submit a new feature, please read through the [Criteria for new features](#criteria-for-new-features) below. * When in doubt about the acceptance of a change, you are welcome to ask via an issue first. ### Criteria for new features 1. New features should not detract from the default Chromium experience, unless it falls under the project's main objectives (i.e. removing Google integration and enhancing privacy). * For larger features, please propose them via an issue first. 2. New features should live behind a setting that is **off by default**. * Settings are usually added via a command-line flag and `chrome://flags` entries. See [the relevant section in docs/developing.md](developing.md#adding-command-line-flags-and-chromeflags-options) for more information. * Unless there are significant benefits, adding the setting to `chrome://settings` is *not recommended* due to the additional maintenance required (caused by the infrastructure that backs preferences). **NOTE**: In the event that the codebase changes significantly for a non-essential patch (i.e. a patch that does not contribute to the main objectives of ungoogled-chromium), it will be removed until someone updates it. --- ## File: docs/default_settings.md # Default Settings Vanilla Chromium settings are not often changed by ungoogled-chromium, however there are some exceptions. Below is a list of the documented changes to the default Chromium settings. Setting | New State | Location -- | -- | -- Allow sites to check if you have payment methods saved | Disabled | chrome://settings/payments Ask where to save each file before downloading | Enabled | chrome://settings/downloads Auto sign-in | Disabled | chrome://settings/passwords Block third-party cookies | Enabled | chrome://settings/cookies Continue running background apps when Chromium is closed | Disabled | chrome://settings/system Hyperlink auditing (\) | Disabled | NA Link Doctor | Disabled | NA Offer to save passwords | Disabled | chrome://settings/passwords Payment autofill | Disabled | chrome://settings/payments Preload pages | Disabled | chrome://settings/performance Search suggestions | Disabled | chrome://settings/syncSetup Show bookmark bar | Enabled | chrome://settings/appearance Third-party sign-in | Disabled | `--enable-features=FedCm` WebRTC IP handling policy | Disable Non-Proxied UDP | `--webrtc-ip-handling-policy` --- ## File: docs/design.md # Design This document contains a high-level technical description of ungoogled-chromium and its components. ## Overview ungoogled-chromium consists of the following major components: * [Configuration](#configuration) * [Configuration files](#configuration-files) * [Source file processors](#source-file-processors) * [Patches](#patches) * [Packaging](#packaging) The following sections describe each component. ## Configuration Configuration is a broad term that refers to patches, build flags, and metadata about Chromium source code. It consists of the following components: * [Configuration files](#configuration-files) * [Source file processors](#source-file-processors) * [Patches](#patches) The following sections describe each component in more depth. ### Configuration Files Configuration files (or config files) are files that store build configuration and source code changes for a build. **IMPORTANT**: For consistency, all config files must be encoded in UTF-8. List of configuration files: * `chromium_version.txt` - The Chromium version used by ungoogled-chromium * `revision.txt` - The revision of the changes on top of the given Chromium version. * `pruning.list` - [See the Source File Processors section](#source-file-processors) * `domain_regex.list` - [See the Source File Processors section](#source-file-processors) * `domain_substitution.list` - [See the Source File Processors section](#source-file-processors) * `downloads.ini` - Archives to download and unpack into the buildspace tree. This includes code not bundled in the Chromium source code archive that is specific to a non-Linux platform. On platforms such as macOS, this also includes a pre-built LLVM toolchain for convenience (which can be removed and built from source if desired). * `flags.gn` - GN arguments to set before building. ### Source File Processors Source file processors are utilities that directly manipulate the Chromium source tree before building. Currently, there are two such utilities: binary pruning, and domain substitution. **Binary Pruning**: Strips binaries from the source code. This includes pre-built executables, shared libraries, and other forms of machine code. Most are substituted with system or user-provided equivalents, or are built from source; those binaries that cannot be removed do not contain machine code. The list of files to remove are determined by the config file `pruning.list`. This config file is generated by `devutils/update_lists.py`. **Domain Substitution**: Replaces Google and several other web domain names in the Chromium source code with non-existent alternatives ending in `qjz9zk`. These changes are mainly used as a backup measure to detect potentially unpatched requests to Google. Note that domain substitution is a crude process, and *may not be easily undone*. With a few patches from ungoogled-chromium, any requests with these domain names sent via `net::URLRequest` in the Chromium code are blocked and notify the user via a info bar. Similar to binary pruning, the list of files to modify are listed in `domain_substitution.list`; it is also updated with `devutils/update_lists.py`. The regular expressions to use are listed in `domain_regex.list`; the search and replacement expressions are delimited with a pound (`#`) symbol. The restrictions for the entries are as follows: * All replacement expressions must end in the TLD `qjz9zk`. * The search and replacement expressions must have a one-to-one correspondence: no two search expressions can match the same string, and no two replacement expressions can result in the same string. ### Patches All of ungoogled-chromium's patches for the Chromium source code are located in `patches/`. This directory conforms to the default GNU Quilt format. That is: * All patches must reside inside `patches/` * There is a `patches/series` text file that defines the order to apply all the patches. These patches are listed as a relative path from the `patches` directory. * Lines starting with the pound symbol (`#`) are ignored * For lines with patch paths: If there is a space followed by a pound symbol, the text after the patch path will be ignored. All patch files in ungoogled-chromium must satisfy these formatting requirements: * Patch filenames must end with the extension `.patch` * The content must be in [unified format](https://en.wikipedia.org/wiki/Diff_utility#Unified_format). * All paths in the hunk headers must begin after the first slash (which corresponds to the argument `-p1` for GNU patch). * All patches must apply cleanly (i.e. no fuzz). * It is recommended that hunk paths have the `a/` and `b/` prefixes, and a context of 3 (like the git default). * All patches must be encoded in UTF-8 (i.e. same encoding as config files). Patches are categorized into two directories directly under `patches/`: 1. **core**: Changes regarding background requests, code specific to Google web services, or code using pre-made binaries. They must be kept up-to-date with all of the changes in Chromium. 2. **extra**: Changes to features regarding control and transparency. They are not guaranteed to persist across updates to Chromium. Within each category, patches are grouped by the following: * `debian/` - Patches from Debian's Chromium * Patches are not modified unless they conflict with Inox's patches * These patches are not Debian-specific. For those, see the `debian/patches` directory * `inox-patchset/` - Contains a modified subset of patches from Inox patchset. * Some patches such as those that change branding are omitted * Patches are not modified unless they do not apply cleanly onto the version of Chromium being built * Patches are from [inox-patchset's GitHub](https://github.com/gcarq/inox-patchset) * [Inox patchset's license](https://github.com/gcarq/inox-patchset/blob/master/LICENSE) * `bromite/` - Patches from [Bromite](https://github.com/bromite/bromite) * `iridium-browser/` - Contains a modified subset of patches from Iridium Browser. * Some patches such as those that change branding or URLs to point to Iridium's own servers are omitted * Patches are not modified unless they conflict with Debian's or Inox's patches * Patches are from the `patchview` branch of Iridium's Git repository. [Git webview of the patchview branch](https://git.iridiumbrowser.de/cgit.cgi/iridium-browser/?h=patchview) * `opensuse/` - Patches from openSUSE's Chromium * `ubuntu/` - Patches from Ubuntu's Chromium * `ungoogled-chromium/` - Patches by ungoogled-chromium developers ## Packaging Packaging is the process of downloading, building, and producing a distributable package of ungoogled-chromium. Packaging files use the code from this repository to build ungoogled-chromium. Each platform and configuration has an associated packaging repository under the [ungoogled-software](https://github.com/ungoogled-software) organization. For more information about each packaging repository, see the [building documentation](building.md). Packaging generally consists of the major steps: 1. Download and unpack the source tree 2. Prune binaries 3. Apply patches 4. Substitute domains 5. Build GN via `tools/gn/bootstrap/bootstrap.py` 6. Run `gn gen` with the GN flags 7. Build Chromium via `ninja` 8. Create package(s) of build output (usually in `out/Default`) --- ## File: docs/developing.md # Development notes and procedures This document contains an assortment of information for those who want to develop ungoogled-chromium. Information targeted towards developers *and* other users live in [the Wiki](https://ungoogled-software.github.io/ungoogled-chromium-wiki/). Contents: * [Branches](#branches) * [Adding command-line flags and chrome://flags options](#adding-command-line-flags-and-chromeflags-options) * [Workflow of updating to a new Chromium version](#workflow-of-updating-to-a-new-chromium-version) ## Branches Development is focused on `master`, and any changes in there should not break anything unless platforms break during a Chromium version rebase. Larger feature changes or hotfixes must be done in a separate branch. Once they are ready, then a Pull Request can be made onto `master` (for contributors with write access, merging directly via a git client is fine). After the branch is merged, it should be removed. ## Adding command-line flags and `chrome://flags` options See `docs/how_to_add_your_feature_flag.md` in the Chromium source tree for the steps needed. Note that updating `tools/metrics/histograms/enums.xml` is not required. For new flags, first add a constant to `third_party/ungoogled/ungoogled_switches.cc` (by modifying patch `resources/patches/ungoogled-chromium/add-third-party-ungoogled.patch`). Then, use this constant in the steps outlined above. ## Workflow of updating to a new Chromium version Tested on Debian 12 (bookworm). Exact instructions should work on any other Linux or macOS system with the proper dependencies. To gain a deeper understanding of this updating process, have a read through [docs/design.md](design.md). ### Dependencies * [`quilt`](http://savannah.nongnu.org/projects/quilt) * This is available in most (if not all) Linux distributions, and also Homebrew on macOS. * This utility facilitates most of the updating process, so it is important to learn how to use this. The manpage for quilt (as of early 2017) lacks an example of a workflow. There are multiple guides online, but [this guide from Debian](https://wiki.debian.org/UsingQuilt) and [the referenced guide on that page](https://raphaelhertzog.com/2012/08/08/how-to-use-quilt-to-manage-patches-in-debian-packages/) are the ones referenced in developing the current workflow. * Python 3.10 or newer * `httplib2` and `six` are also required if you wish to utilize a source clone instead of the source tarball. `pysocks` is required for versions of `httplib2` v0.30.0 or later. ### Downloading the source code #### Source tarball download (recommended): ```sh mkdir -p build/download_cache ./utils/downloads.py retrieve -i downloads.ini -c build/download_cache ./utils/downloads.py unpack -i downloads.ini -c build/download_cache build/src ``` #### Source clone: ```sh ./utils/clone.py -o build/src ``` ### Updating lists The utility `devutils/update_lists.py` automates this process. By default, it will update the files in the local repo. Pass in `-h` or `--help` for available options. ```sh ./devutils/update_lists.py -t build/src ``` The resulting source tree in `build/src` *will not* have binaries pruned or domains substituted. ### Updating patches **IMPORTANT**: Make sure domain substitution has not been applied before updating patches. 1. Run `source devutils/set_quilt_vars.sh` (or `source devutils/set_quilt_vars.fish` if you are using the fish shell) * This will setup quilt to modify patches directly in `patches/` 2. Go into the source tree: `cd build/src` 3. Use `quilt` to refresh all patches: `quilt push -a --refresh` * If an error occurs, go to the next step. Otherwise, skip to Step 5. 4. Use `quilt` to fix the broken patch: 1. Run `quilt push -f` 2. Edit the broken files as necessary by adding (`quilt edit ...` or `quilt add ...`) or removing (`quilt remove ...`) files as necessary * When removing large chunks of code, remove each line instead of using language features to hide or remove the code. This makes the patches less susceptible to breakages when using quilt's refresh command (e.g. quilt refresh updates the line numbers based on the patch context, so it's possible for new but desirable code in the middle of the block comment to be excluded.). It also helps with readability when someone wants to see the changes made based on the patch alone. 3. Refresh the patch: `quilt refresh` 4. Go back to Step 3. 5. Run `quilt pop -a` 6. Go back to ungoogled-chromium repo: `cd ../..` 7. Run `devutils/validate_config.py`. If any warnings are printed, address them; otherwise, continue to Step 8. 8. Run `devutils/validate_patches.py -l build/src`. If errors occur, go back to Step 3. This should leave unstaged changes in the git repository to be reviewed, added, and committed. ### Steps for fixing patches after a failed build attempt If domain substitution is not applied, then the steps from the previous section will work for revising patches. If domain substitution is applied, then the steps for the initial update will not apply since that would create patches which depend on domain substitution. Here is a method of dealing with this: 1. Revert domain substitution: `./utils/domain_substitution.py revert -c CACHE_PATH_HERE build/src` 2. Follow the patch updating section above 3. Reapply domain substitution: `./utils/domain_substitution.py apply -r domain_regex.list -f domain_substitution.list -c CACHE_PATH_HERE build/src` 4. Reattempt build. Repeat steps as necessary. ### Next steps * Submit a Pull Request of these changes to the ungoogled-chromium repo. * Once the PR is merged, update the repositories of each platform repository that you are maintaining under the `ungoogled-software` organization. --- ## File: docs/flags.md # List of flags and switches This is an exhaustive list of command-line switches and flags introduced by ungoogled-chromium. Each switch has a corresponding entry on the `chrome://flags` page which can be filtered by searching for `ungoogled-chromium`. If a switch requires a value, you must specify it with an `=` sign; e.g. flag `--foo` with value `bar` should be written as `--foo=bar`. > **NOTE**: If you add a command-line argument that is also in `chrome://flags`, the flag's state will not be indicated in `chrome://flags`. There is no universal way to ensure command-line flags are taking effect, but you can find if they're being seen by checking `chrome://version`. - ### Available on all platforms `Switch                                          ` | Description -- | -- `--disable-beforeunload` | Disables JavaScript dialog boxes triggered by `beforeunload` `--disable-grease-tls` | Disables GREASE for TLS. Combined with `--http-accept-header` allows browser to look more like a tor-browser. See https://github.com/ungoogled-software/ungoogled-chromium/issues/783 for more details. `--disable-search-engine-collection` | Disable automatic search engine scraping from webpages. `--extension-mime-request-handling` | Change how extension MIME types (CRX and user scripts) are handled. Acceptable values are `download-as-regular-file` or `always-prompt-for-install`. Leave unset to use normal behavior. `--fingerprinting-canvas-image-data-noise` | (Added flag to Bromite feature) Implements fingerprinting deception for Canvas image data retrieved via JS APIs. In the data, at most 10 pixels are slightly modified. `--fingerprinting-canvas-measuretext-noise` | (Added flag to Bromite feature) Scale the output values of Canvas::measureText() with a randomly selected factor in the range -0.0003% to 0.0003%, which are recomputed on every document initialization. `--fingerprinting-client-rects-noise` | (Added flag to Bromite feature) Implements fingerprinting deception of JS APIs `getClientRects()` and `getBoundingClientRect()` by scaling their output values with a random factor in the range -0.0003% to 0.0003%, which are recomputed for every document instantiation. `--force-punycode-hostnames` | Convert all Internationalized Domain Names to punycode (ASCII representation of Unicode). See https://github.com/ungoogled-software/ungoogled-chromium/issues/370 for more details. `--hide-crashed-bubble` | Hides the bubble box with the message "Restore Pages? Chromium didn't shut down correctly." that shows on startup after the browser did not exit cleanly. `--http-accept-header` | Changes the default value of the `Accept` HTTP header sent with HTTP requests. Combined with `--disable-grease-tls` allows browser to look more like a tor-browser. See https://github.com/ungoogled-software/ungoogled-chromium/issues/783 for more details. `--keep-old-history` | Disables deletion of local browser history after 90 days `--max-connections-per-host` | (from Bromite) Configure the maximum allowed connections per host. Valid values are `6` and `15` `--omnibox-autocomplete-filtering` | Restrict omnibox autocomplete results to a combination of search suggestions (if enabled), bookmarks, and internal chrome pages. Accepts `search`, `search-bookmarks`, `search-chrome`, and `search-bookmarks-chrome`. `--popups-to-tabs` | Makes popups open in new tabs. `--disabling-javascript-optimization-disables-jit` | Disables JIT too if the "JavaScript optimization" setting is turned off - ### Available only on desktop `Switch                      ` | Description -- | -- `--bookmark-bar-ntp` | Sets the visibility of the bookmark bar on the New Tab Page. Only takes the value `never`. `--close-confirmation` | Show a warning prompt when closing the browser window. Accepts `last` (prompt when closing the last window with several tabs) and `multiple` (prompt only if more than one window is open). `--close-window-with-last-tab` | Determines whether a window should close once the last tab is closed. Only takes the value `never`. `--custom-ntp` | Allows setting a custom URL for the new tab page. Value can be internal (e.g. `about:blank` or `chrome://new-tab-page`), external (e.g. `example.com`), or local (e.g. `file:///tmp/startpage.html`). This applies for incognito windows as well when not set to a `chrome://` internal page. `--enable-incognito-themes` | Allows themes to change the appearance of Incognito windows. `--hide-extensions-menu` | Hides the extensions container. This includes the puzzle piece icon as well as any pinned extensions. `--hide-fullscreen-exit-ui` | Hides the "X" that appears when the mouse cursor is moved towards the top of the window in fullscreen mode. Additionally, this hides the "Press F11 to exit full screen" popup. `--hide-tab-close-buttons` | Hides the close buttons on tabs. `--remove-grab-handle` | Removes the reserved empty space in the tabstrip for moving the window. `--scroll-tabs` | Determines if scrolling will cause a switch to a neighboring tab if the cursor hovers over the tabs, or the empty space beside the tabs. The flag requires one the values: `always`, `never`, `incognito-and-guest`. When omitted, the default is to use platform-specific behavior, which is currently enabled only on desktop Linux. `--show-avatar-button` | Sets visibility of the avatar button. The flag requires one of the values: `always`, `incognito-and-guest` (only show Incognito or Guest modes), or `never`. `--tab-hover-cards` | Allows removing the tab hover cards or using a tooltip as a replacement. This can be set with the values `none` or `tooltip`. - #### Available only on Windows `Switch              ` | Description -- | -- `--disable-encryption` | Disable encryption of cookies, passwords, and settings which uses a generated machine-specific encryption key. This is used to enable portable user data directories. `--disable-machine-id` | Disables use of a generated machine-specific ID to lock the user data directory to that machine. This is used to enable portable user data directories. ## Feature flags Feature flags are similar to switches with the difference being that they are passed as values for the `--enable-features` switch. Multiple features can be passed at the same time by separating them with a comma, e.g. `--enable-features=flag1,flag2,flag3`. These are also available on the `chrome://flags` page. - ### Available on all platforms Feature | Description -- | -- `MinimalReferrers` | Removes all cross-origin referrers and strips same-origin referrers down to the origin. Has lower precedence than `NoCrossOriginReferrers`. `NoCrossOriginReferrers` | Removes all cross-origin referrers. Has lower precedence than `NoReferrers`. `NoReferrers` | Removes all referrers. `ReducedSystemInfo` | Reduces the amount of system information obatainable through headers and javascript, also causes hardwareConcurrency to respond with two cores. `RemoveClientHints` | Removes client hints (information sent to servers about your system, similar to a user agent). `SetIpv6ProbeFalse` | Forces the result of the browser's IPv6 probing (i.e. IPv6 connectivity test) to be unsuccessful. This causes IPv4 addresses to be prioritized over IPv6 addresses. Without this flag, the probing result is set to be successful, which causes IPv6 to be used over IPv4 when possible. `SpoofWebGLInfo` | Return generic values for WebGLDebugRendererInfo to remove a potential data leak while preventing potential website breakage. `IncreaseIncognitoStorageQuota` | Makes Incognito and Guest profiles compute the storage quota with the same algorithm that regular profiles use. This makes it harder for websites to detect Incognito mode, but may allow sites to induce heavy memory pressure. - ### Available only on desktop Feature | Description -- | -- `ClearDataOnExit` | Clears all browsing data on exit. `DisableLinkDrag` | Prevents dragging of links and selected text. Allows selecting text from a middle of a link. Also allows starting selection without first clearing the existing one. This behaviour is similar to the one from older Opera. See https://github.com/ungoogled-software/ungoogled-chromium/pull/2080 and https://github.com/ungoogled-software/ungoogled-chromium/discussions/2055 for more information. `DisableQRGenerator` | Disables the QR generator for sharing page links. ## Flags for existing switches Chromium contains switches that do no have corresponding entries in `chrome://flags`. For convenience, ungoogled-chromium has created entries for some of the commonly-used switches. - ### Available on all platforms `Switch                      ` | Description -- | -- `--disable-top-sites` | Disables the top sites and most visited entries on the new tab page. `--disable-webgl` | Disable all versions of WebGL. `--enable-low-end-device-mode` | Force low-end device mode when set. `--force-dark-mode` | Forces dark mode in UI for platforms that support it. `--no-default-browser-check` | Disables the default browser check. `--no-pings` | Don't send hyperlink auditing pings. `--webrtc-ip-handling-policy` | Restrict which IP addresses and interfaces WebRTC uses. - ### Available only on desktop `Switch                      ` | Description -- | -- `--incognito` | Start in Incognito. `--start-maximized` | Starts the browser maximized, regardless of any previous settings. --- ## File: docs/platforms.md # Supported Platforms This page lists platforms officially supported by ungoogled-chromium, and their associated repositories. * Android: [ungoogled-chromium-android](https://github.com/ungoogled-software/ungoogled-chromium-android) * Arch Linux: [ungoogled-chromium-archlinux](https://github.com/ungoogled-software/ungoogled-chromium-archlinux) * Debian, Ubuntu, and derivatives: [ungoogled-chromium-debian](https://github.com/ungoogled-software/ungoogled-chromium-debian) * Fedora and CentOS: [ungoogled-chromium-fedora](https://github.com/ungoogled-software/ungoogled-chromium-fedora) * Portable Linux (for any Linux distro): [ungoogled-chromium-portablelinux](https://github.com/ungoogled-software/ungoogled-chromium-portablelinux) * Windows: [ungoogled-chromium-windows](https://github.com/ungoogled-software/ungoogled-chromium-windows) * macOS: [ungoogled-chromium-macos](https://github.com/ungoogled-software/ungoogled-chromium-macos) ## 2. Official Technical Reference & Guides (ungoogled-software/ungoogled-software.github.io) # Website for ungoogled-chromium This is a basic website for ungoogled-chromium, based upon [Hydra by CloudCannon](https://github.com/CloudCannon/hydra-jekyll-template). ## Develop This website was built with [Jekyll](https://jekyllrb.com/) version 3. but should support newer versions as well. Install the dependencies with [Bundler](https://bundler.io/): ~~~bash $ bundle install ~~~ Run `jekyll` commands through Bundler to ensure you're using the right versions: ~~~bash $ bundle exec jekyll serve ~~~ Changes made while `jekyll serve` runs will cause Jekyll to regenerate the site automatically (while auto-regeneration is enabled, which is the default) ### Posts * Add, update or remove a post in the *Posts* collection. * The **Staff Author** field links to members in the **Staff** collection. * Documentation pages are organised in the navigation by category, with URLs based on the path inside the `_docs` folder. * Change the defaults when new posts are created in `_posts/_defaults.md`. ### Staff * Reused around the site to save multiple editing locations. * Add `excluded_in_search: true` to any documentation page's front matter to exclude that page in the search results. ### Navigation * Exposed as a data file to give clients better access. * Set in the *Data* / *Navigation* section. ### Footer * Exposed as a data file to give clients better access. * Set in the *Data* / *Footer* section.