Discharge7443/brave-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] Format README.md (#36844)

Browse Source 
This PR removes the exclusion of `README.md` from `.prettierignore`.
This exclusion was possibly meant to not alter the root `README.md`, but
it was also indiscriminately exclusing any `README.md` in subpaths.

With this change, we enable the auto format for all `README.md` files,
including the one in the root path, as there is no good reason not to.

Bug: N/A
This commit is contained in:
cdesouza-chromium
2026-06-01 16:00:04 +01:00
committed by GitHub
parent 4c8878f1b2
commit 2ae8b2603b
19 changed files with 560 additions and 414 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.prettierignore
+1 -1
View File
@@ -28,10 +28,10 @@
# Ignore some markdown files:
.github/PULL_REQUEST_TEMPLATE.md
CONTRIBUTING.md
README.md
browser/ui/commander/fuzzy_finder.md
browser/ui/views/brave_ads/overview.md
components/ai_chat/core/browser/tools/tools.md
browser/brave_vpn/win/brave_vpn_wireguard_service/README.md
# Ignored top-level files:
.clang-tidy
README.md
+85 -40
View File
@@ -2,21 +2,27 @@
# Brave Core
Brave Core is a set of changes, APIs, and scripts used for customizing Chromium to make the Brave browser. Please also check https://github.com/brave/brave-browser which only holds the issues, releases and the wiki.
Brave Core is a set of changes, APIs, and scripts used for customizing Chromium
to make the Brave browser. Please also check
https://github.com/brave/brave-browser which only holds the issues, releases and
the wiki.
## Overview
This repository holds the build tools needed to build the Brave desktop browser for all platforms. In particular, it fetches and syncs code from the projects defined in `package.json` and `src/brave/DEPS`:
This repository holds the build tools needed to build the Brave desktop browser
for all platforms. In particular, it fetches and syncs code from the projects
defined in `package.json` and `src/brave/DEPS`:
- [Chromium](https://chromium.googlesource.com/chromium/src.git)
- Fetches code via `depot_tools`.
- Sets the branch for Chromium (ex: 65.0.3325.181).
- [brave-core](https://github.com/brave/brave-core)
- Mounted at `src/brave`.
- Maintains patches for 3rd party Chromium code.
- [adblock-rust](https://github.com/brave/adblock-rust)
- Implements Brave's adblock engine.
- Linked through [brave/adblock-rust-ffi](https://github.com/brave/brave-core/tree/master/components/adblock_rust_ffi).
- [Chromium](https://chromium.googlesource.com/chromium/src.git)
- Fetches code via `depot_tools`.
- Sets the branch for Chromium (ex: 65.0.3325.181).
- [brave-core](https://github.com/brave/brave-core)
- Mounted at `src/brave`.
- Maintains patches for 3rd party Chromium code.
- [adblock-rust](https://github.com/brave/adblock-rust)
- Implements Brave's adblock engine.
- Linked through
[brave/adblock-rust-ffi](https://github.com/brave/brave-core/tree/master/components/adblock_rust_ffi).
## Resources
@@ -27,13 +33,15 @@ This repository holds the build tools needed to build the Brave desktop browser
## Downloads
You can [visit our website](https://brave.com/download) to get the latest stable release.
You can [visit our website](https://brave.com/download) to get the latest stable
release.
## Contributing
Please see the [contributing guidelines](./CONTRIBUTING.md).
Our [Wiki](https://github.com/brave/brave-browser/wiki) also has some useful technical information, especially about setting the development environment.
Our [Wiki](https://github.com/brave/brave-browser/wiki) also has some useful
technical information, especially about setting the development environment.
## Security Policy
@@ -41,12 +49,19 @@ Please see the [security policy](./SECURITY.md).
## Community
[Join the Q&A community](https://community.brave.app/) if you'd like to get more involved with Brave. You can [ask for help](https://community.brave.app/c/support-and-troubleshooting),
[discuss features you'd like to see](https://community.brave.app/c/brave-feature-requests), and a lot more. We'd love to have your help so that we can continue improving Brave.
[Join the Q&A community](https://community.brave.app/) if you'd like to get more
involved with Brave. You can
[ask for help](https://community.brave.app/c/support-and-troubleshooting),
[discuss features you'd like to see](https://community.brave.app/c/brave-feature-requests),
and a lot more. We'd love to have your help so that we can continue improving
Brave.
You can also ask questions and interact in the [`community-guest`](https://bravesoftware.slack.com) channel on Brave Software's Slack.
You can also ask questions and interact in the
[`community-guest`](https://bravesoftware.slack.com) channel on Brave Software's
Slack.
Help us translate Brave to your language by submitting translations at https://explore.transifex.com/brave/brave_en/.
Help us translate Brave to your language by submitting translations at
https://explore.transifex.com/brave/brave_en/.
Follow [@brave](https://x.com/brave) on X for important news and announcements.
@@ -62,7 +77,8 @@ Follow the instructions for your platform:
## Clone and initialize
Once you have the prerequisites installed, you can get the code and initialize the build environment.
Once you have the prerequisites installed, you can get the code and initialize
the build environment.
```bash
git clone git@github.com:brave/brave-core.git path-to-your-project-folder/src/brave
@@ -75,8 +91,10 @@ npm install
npm run init
```
brave-core based android builds should use `npm run init -- --target_os=android --target_arch=arm` (or whichever CPU type you want to build for)
brave-core based iOS builds should use `npm run init -- --target_os=ios`
brave-core based android builds should use
`npm run init -- --target_os=android --target_arch=arm` (or whichever CPU type
you want to build for) brave-core based iOS builds should use
`npm run init -- --target_os=ios`
You can also set the target_os and target_arch for init and build using:
@@ -85,9 +103,11 @@ npm config set target_os android
npm config set target_arch arm
```
Additional config needed to build are documented at https://github.com/brave/brave-browser/wiki/Build-configuration
Additional config needed to build are documented at
https://github.com/brave/brave-browser/wiki/Build-configuration
Internal developers can find more information at https://github.com/brave/internal/wiki/Build-configuration
Internal developers can find more information at
https://github.com/brave/internal/wiki/Build-configuration
## Build Brave
@@ -105,13 +125,20 @@ To do a release build:
npm run build Release
```
brave-core based android builds should use `npm run build -- --target_os=android --target_arch=arm` or set the npm config variables as specified above for `init`
brave-core based android builds should use
`npm run build -- --target_os=android --target_arch=arm` or set the npm config
variables as specified above for `init`
brave-core based iOS builds should use the Xcode project found in `ios/brave-ios/App`. You can open this project directly or run `npm run ios_bootstrap -- --open_xcodeproj` to have it opened in Xcode. See the [iOS Developer Environment](https://github.com/brave/brave-browser/wiki/iOS-Development-Environment#Building) for more information on iOS builds.
brave-core based iOS builds should use the Xcode project found in
`ios/brave-ios/App`. You can open this project directly or run
`npm run ios_bootstrap -- --open_xcodeproj` to have it opened in Xcode. See the
[iOS Developer Environment](https://github.com/brave/brave-browser/wiki/iOS-Development-Environment#Building)
for more information on iOS builds.
### Build Configurations
Running a release build with `npm run build Release` can be very slow and use a lot of RAM, especially on Linux with the Gold LLVM plugin.
Running a release build with `npm run build Release` can be very slow and use a
lot of RAM, especially on Linux with the Gold LLVM plugin.
To run a statically linked build (takes longer to build, but starts faster):
@@ -125,7 +152,8 @@ To run a debug build (Component build with is_debug=true):
npm run build -- Debug
```
NOTE: the build will take a while to complete. Depending on your processor and memory, it could potentially take a few hours.
NOTE: the build will take a while to complete. Depending on your processor and
memory, it could potentially take a few hours.
## Run Brave
@@ -137,34 +165,39 @@ To start the build:
`npm run sync -- [--force] [--init] [--create] [brave_core_ref]`
**This will attempt to stash your local changes in brave-core, but it's safer to commit local changes before running this**
**This will attempt to stash your local changes in brave-core, but it's safer to
commit local changes before running this**
`npm run sync` will (depending on the below flags):
1. 📥 Update sub-projects (chromium, brave-core) to latest commit of a git ref (e.g. tag or branch)
1. 📥 Update sub-projects (chromium, brave-core) to latest commit of a git ref
(e.g. tag or branch)
2. 🤕 Apply patches
3. 🔄 Update gclient DEPS dependencies
4. ⏩ Run hooks (e.g. to perform `npm install` on child projects)
| flag | Description |
|---|---|
|`[no flags]`|updates chromium if needed and re-applies patches. If the chromium version did not change, it will only re-apply patches that have changed. Will update child dependencies **only if any project needed updating during this script run**. <br> **Use this if you want the script to manage keeping you up to date instead of pulling or switching branches manually. **|
|`--force`|updates both _Chromium_ and _brave-core_ to the latest remote commit for the current brave-core branch and the _Chromium_ ref specified in brave-core/package.json (e.g. `master` or `74.0.0.103`). Will re-apply all patches. Will force update all child dependencies. <br> **Use this if you're having trouble and want to force the branches back to a known state. **|
|`--init`|force update both _Chromium_ and _brave-core_ to the versions specified in brave-core/package.json and force updates all dependent repos - same as `npm run init`|
|`--sync_chromium (true/false)`|Will force or skip the chromium version update when applicable. Useful if you want to avoid a minor update when not ready for the larger build time a chromium update may result in. A warning will be output about the current code state expecting a different chromium version. Your build may fail as a result.|
|`-D, --delete_unused_deps`|Will delete from the working copy any dependencies that have been removed since the last sync. Mimics `gclient sync -D`.|
| flag | Description |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `[no flags]` | updates chromium if needed and re-applies patches. If the chromium version did not change, it will only re-apply patches that have changed. Will update child dependencies **only if any project needed updating during this script run**. <br> **Use this if you want the script to manage keeping you up to date instead of pulling or switching branches manually. ** |
| `--force` | updates both _Chromium_ and _brave-core_ to the latest remote commit for the current brave-core branch and the _Chromium_ ref specified in brave-core/package.json (e.g. `master` or `74.0.0.103`). Will re-apply all patches. Will force update all child dependencies. <br> **Use this if you're having trouble and want to force the branches back to a known state. ** |
| `--init` | force update both _Chromium_ and _brave-core_ to the versions specified in brave-core/package.json and force updates all dependent repos - same as `npm run init` |
| `--sync_chromium (true/false)` | Will force or skip the chromium version update when applicable. Useful if you want to avoid a minor update when not ready for the larger build time a chromium update may result in. A warning will be output about the current code state expecting a different chromium version. Your build may fail as a result. |
| `-D, --delete_unused_deps` | Will delete from the working copy any dependencies that have been removed since the last sync. Mimics `gclient sync -D`. |
Run `npm run sync brave_core_ref` to checkout the specified _brave-core_ ref and update all dependent repos including chromium if needed.
Run `npm run sync brave_core_ref` to checkout the specified _brave-core_ ref and
update all dependent repos including chromium if needed.
## Scenarios
#### Create a new branch:
```bash
> cd src/brave
src/brave> git checkout -b branch_name
```
#### Checkout an existing branch or tag:
```bash
src/brave> git fetch origin
src/brave> git checkout [-b] branch_name
@@ -175,6 +208,7 @@ src/brave> npm run sync
```
#### Update the current branch to the latest remote:
```bash
src/brave> git pull
src/brave> npm run sync
@@ -184,6 +218,7 @@ src/brave> npm run sync
```
#### Reset to latest brave-core master (via `init`, will always result in a longer build and will remove any pending changes in your brave-core working directory):
```bash
src/brave> git checkout master
src/brave> git pull
@@ -191,6 +226,7 @@ src/brave> npm run sync -- --init
```
#### When you know that DEPS didn't change, but .patch files did (quickest attempt to perform a mini-sync before a build):
```bash
src/brave> git checkout featureB
src/brave> git pull
@@ -200,15 +236,24 @@ src/brave> npm run apply_patches
## Enabling third-party APIs
1. **Google Safe Browsing**: Get an API key with SafeBrowsing API enabled from https://console.developers.google.com/. Update the `GOOGLE_API_KEY` environment variable with your key as per https://www.chromium.org/developers/how-tos/api-keys to enable Google SafeBrowsing.
1. **Google Safe Browsing**: Get an API key with SafeBrowsing API enabled from
https://console.developers.google.com/. Update the `GOOGLE_API_KEY`
environment variable with your key as per
https://www.chromium.org/developers/how-tos/api-keys to enable Google
SafeBrowsing.
## Development
- [Security rules from Chromium](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/docs/security/rules.md)
- [IPC review guidelines](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/security/ipc-reviews.md) (in particular [this reference](https://docs.google.com/document/d/1Kw4aTuISF7csHnjOpDJGc7JYIjlvOAKRprCTBVWw_E4/edit#heading=h.84bpc1e9z1bg))
- [Brave's internal security guidelines](https://github.com/brave/internal/wiki/Pull-request-security-audit-checklist) (for employees only)
- [IPC review guidelines](https://chromium.googlesource.com/chromium/src/+/HEAD/docs/security/ipc-reviews.md)
(in particular
[this reference](https://docs.google.com/document/d/1Kw4aTuISF7csHnjOpDJGc7JYIjlvOAKRprCTBVWw_E4/edit#heading=h.84bpc1e9z1bg))
- [Brave's internal security guidelines](https://github.com/brave/internal/wiki/Pull-request-security-audit-checklist)
(for employees only)
- [Rust usage](https://github.com/brave/brave-core/blob/master/docs/rust.md)
## Troubleshooting
See [Troubleshooting](https://github.com/brave/brave-browser/wiki/Troubleshooting) for solutions to common problems.
See
[Troubleshooting](https://github.com/brave/brave-browser/wiki/Troubleshooting)
for solutions to common problems.
browser/ai_chat/tools/README.md
+9 -3
View File
@@ -1,9 +1,15 @@
# AI Chat Browser Tools
Place subclasses of ai_chat::Tool here that require access to things in {chrome,brave}/browser.
Place subclasses of ai_chat::Tool here that require access to things in
{chrome,brave}/browser.
## Content Agent Tools
A set of tools whose purpose is to act on web content. These most often utilize the chromium actor framework to create a Task for a conversation, add 1 or more Tabs to that Task and perform actions against 1 of those Tabs.
A set of tools whose purpose is to act on web content. These most often utilize
the chromium actor framework to create a Task for a conversation, add 1 or more
Tabs to that Task and perform actions against 1 of those Tabs.
These tools should be owned by the ContentAgentToolProvider which can own the shared state between these tools for a single conversation, and provide information about the current Task and available Tabs to all the related tools via ContentAgentTaskProvider.
These tools should be owned by the ContentAgentToolProvider which can own the
shared state between these tools for a single conversation, and provide
information about the current Task and available Tabs to all the related tools
via ContentAgentTaskProvider.
browser/history_embeddings/README.md
+76 -85
View File
@@ -4,116 +4,109 @@ Brave's local embedder for history embeddings (semantic history search).
## Overview
Upstream Chromium's history embeddings uses `OptimizationGuide` to
deliver TFLite model files to `ChromePassageEmbeddingsServiceController`,
which binds its `service_remote_` to a `PassageEmbeddingsService`
(`services/passage_embeddings/`) running in a separate utility process.
The upstream-owned `SchedulingEmbedder` drives the job queue and calls
into that service.
Upstream Chromium's history embeddings uses `OptimizationGuide` to deliver
TFLite model files to `ChromePassageEmbeddingsServiceController`, which binds
its `service_remote_` to a `PassageEmbeddingsService`
(`services/passage_embeddings/`) running in a separate utility process. The
upstream-owned `SchedulingEmbedder` drives the job queue and calls into that
service.
Brave replaces only the transport: `BravePassageEmbeddingsServiceController`
subclasses `PassageEmbeddingsServiceController` and swaps in an
in-process `BravePassageEmbeddingsService` that hosts a WASM
EmbeddingGemma worker inside a background WebContents on the guest
OTR profile. The upstream `SchedulingEmbedder` (priority re-sort,
partial-progress resumption, performance-scenario awareness) is
unchanged.
subclasses `PassageEmbeddingsServiceController` and swaps in an in-process
`BravePassageEmbeddingsService` that hosts a WASM EmbeddingGemma worker inside a
background WebContents on the guest OTR profile. The upstream
`SchedulingEmbedder` (priority re-sort, partial-progress resumption,
performance-scenario awareness) is unchanged.
The upstream extraction pipeline is enabled by chromium_src overrides of
`OptimizationGuideKeyedServiceFactory`, `PageContentAnnotationsServiceFactory`,
and `PageContentExtractionServiceFactory` to check `kHistoryEmbeddings`
instead of the upstream feature flags.
and `PageContentExtractionServiceFactory` to check `kHistoryEmbeddings` instead
of the upstream feature flags.
## Why `BindPassageEmbedder` instead of mojo `LoadModels`
Upstream's `mojom::PassageEmbeddingsService::LoadModels` is shaped for
upstream's embedder: two `ReadOnlyFile` fields (tflite model +
sentencepiece tokenizer) and a `PassageEmbedderParams` of tflite-specific
knobs (thread counts per priority, cache size, GPU flag). EmbeddingGemma
needs five files (`weights`, `weights_dense1`, `weights_dense2`,
`tokenizer`, `config`) with different semantics, and none of the
`PassageEmbedderParams` tuning applies to our WASM renderer. There's no
clean way to map our inputs onto the upstream struct short of patching
the mojom.
upstream's embedder: two `ReadOnlyFile` fields (tflite model + sentencepiece
tokenizer) and a `PassageEmbedderParams` of tflite-specific knobs (thread counts
per priority, cache size, GPU flag). EmbeddingGemma needs five files (`weights`,
`weights_dense1`, `weights_dense2`, `tokenizer`, `config`) with different
semantics, and none of the `PassageEmbedderParams` tuning applies to our WASM
renderer. There's no clean way to map our inputs onto the upstream struct short
of patching the mojom.
The mojom also exists to cross a sandbox boundary — upstream runs its
`PassageEmbeddingsService` in a utility process. `BravePassageEmbeddingsService`
lives in the browser process, same process as the controller, so the
mojo pipe adds serialization cost without any isolation benefit.
lives in the browser process, same process as the controller, so the mojo pipe
adds serialization cost without any isolation benefit.
The only useful piece `LoadModels` would carry for us is the
`PendingReceiver<PassageEmbedder>` that hooks the controller's
`embedder_remote_` up to the service. `BindPassageEmbedder(receiver,
callback)` carries exactly that and nothing more. The renderer's model
files are delivered separately through `PassageEmbedderFactory::Init` as
`embedder_remote_` up to the service. `BindPassageEmbedder(receiver, callback)`
carries exactly that and nothing more. The renderer's model files are delivered
separately through `PassageEmbedderFactory::Init` as
`local_ai::mojom::ModelFiles` (five `BigBuffer` fields), read from the
component-updater install directory surfaced by `LocalModelsUpdaterState`.
`BravePassageEmbeddingsService` still implements the upstream mojom for
completeness (its `LoadModels` override forwards to `BindPassageEmbedder`
after discarding the unused params), but the controller calls
`BindPassageEmbedder` directly. The base class's `service_remote_` is
left unbound; the `embedder_remote_` idle handler tears the whole
service down so the WASM renderer is freed.
completeness (its `LoadModels` override forwards to `BindPassageEmbedder` after
discarding the unused params), but the controller calls `BindPassageEmbedder`
directly. The base class's `service_remote_` is left unbound; the
`embedder_remote_` idle handler tears the whole service down so the WASM
renderer is freed.
## Why fire `EmbedderMetadataUpdated` from the constructor
`SchedulingEmbedder` waits for `EmbedderMetadataUpdated` before it
dispatches any work. Upstream fires it from `MaybeUpdateModelInfo()`
when optimization_guide delivers model files. Brave has no dynamic
model info — our metadata is static (`version=1`, `output_size=768`,
`threshold=0.45`) and always valid — so the controller fires the
notification once in its constructor. The chromium_src include shim
declares `BravePassageEmbeddingsServiceController` as a `friend class`
on the base so we can reach `observer_list_` and `embedder_remote_`
without touching the upstream header (see
`SchedulingEmbedder` waits for `EmbedderMetadataUpdated` before it dispatches
any work. Upstream fires it from `MaybeUpdateModelInfo()` when
`optimization_guide` delivers model files. Brave has no dynamic model info — our
metadata is static (`version=1`, `output_size=768`, `threshold=0.45`) and always
valid — so the controller fires the notification once in its constructor. The
`chromium_src` include shim declares `BravePassageEmbeddingsServiceController`
as a `friend class` on the base so we can reach `observer_list_` and
`embedder_remote_` without touching the upstream header (see
[`chromium_src/.../passage_embeddings_service_controller.h`](../../chromium_src/components/passage_embeddings/core/passage_embeddings_service_controller.h)).
## Key Files
- **`brave_passage_embeddings_service.{h,cc}`** — In-process
implementation of `passage_embeddings::mojom::PassageEmbeddingsService`.
Exposes a direct `BindPassageEmbedder(receiver, model_files, cb)`
entry point used by the controller; constructs a
`BraveBatchPassageEmbedder` around the supplied files. Also exposes
`BindLocalAIReceiver(...)` which the controller forwards to from
`UntrustedLocalAIUI::BindInterface` so the WASM page can register its
- **`brave_passage_embeddings_service.{h,cc}`** — In-process implementation of
`passage_embeddings::mojom::PassageEmbeddingsService`. Exposes a direct
`BindPassageEmbedder(receiver, model_files, cb)` entry point used by the
controller; constructs a `BraveBatchPassageEmbedder` around the supplied
files. Also exposes `BindLocalAIReceiver(...)` which the controller forwards
to from `UntrustedLocalAIUI::BindInterface` so the WASM page can register its
`PassageEmbedderFactory`.
- **`brave_batch_passage_embedder.{h,cc}`** — In-process
implementation of `passage_embeddings::mojom::PassageEmbedder` and
`local_ai::mojom::LocalAIService`. Owns the full renderer-side
lifecycle for a single load: the guest-OTR background WebContents
that hosts the WASM worker, the `LocalAIService` receiver set the
WASM page uses to register its `PassageEmbedderFactory`, and the
`factory->Init` + `factory->Bind` handshake. Initialization is gated
on an explicit `LoadPhase` (`kCreatingContents → kAwaitingFactory →
kInitializing → kReady`); the model files arrive via the ctor, and
Init runs as soon as the renderer registers its factory. Translates
upstream's batch mojom to the renderer's one-passage-at-a-time
interface, processing passages sequentially so callbacks resolve
with embeddings in order.
- **`brave_batch_passage_embedder.{h,cc}`** — In-process implementation of
`passage_embeddings::mojom::PassageEmbedder` and
`local_ai::mojom::LocalAIService`. Owns the full renderer-side lifecycle for a
single load: the guest-OTR background WebContents that hosts the WASM worker,
the `LocalAIService` receiver set the WASM page uses to register its
`PassageEmbedderFactory`, and the `factory->Init` + `factory->Bind` handshake.
Initialization is gated on an explicit `LoadPhase`
(`kCreatingContents → kAwaitingFactory → kInitializing → kReady`); the model
files arrive via the ctor, and Init runs as soon as the renderer registers its
factory. Translates upstream's batch mojom to the renderer's
one-passage-at-a-time interface, processing passages sequentially so callbacks
resolve with embeddings in order.
- **`brave_passage_embeddings_service_controller.{h,cc}`** — Singleton
subclass of `PassageEmbeddingsServiceController`. Observes
`LocalModelsUpdaterState` so it knows when the EmbeddingGemma
component is installed; `EmbedderReady()` returns true iff the
component is present, and `OnLocalModelsReady` fires
`EmbedderMetadataUpdated` on observer_list_ so SchedulingEmbedder
retries. Overrides `MaybeLaunchService()`/`ResetServiceRemote()`
to construct/destroy the in-process service, and
`GetEmbeddings()` to short-circuit with `kModelUnavailable` when not
ready, otherwise post the disk read for the five EmbeddingGemma
files and hand them to `service_->BindPassageEmbedder()` once
- **`brave_passage_embeddings_service_controller.{h,cc}`** — Singleton subclass
of `PassageEmbeddingsServiceController`. Observes `LocalModelsUpdaterState` so
it knows when the EmbeddingGemma component is installed; `EmbedderReady()`
returns true iff the component is present, and `OnLocalModelsReady` fires
`EmbedderMetadataUpdated` on observer*list* so SchedulingEmbedder retries.
Overrides `MaybeLaunchService()`/`ResetServiceRemote()` to construct/destroy
the in-process service, and `GetEmbeddings()` to short-circuit with
`kModelUnavailable` when not ready, otherwise post the disk read for the five
EmbeddingGemma files and hand them to `service_->BindPassageEmbedder()` once
loaded.
## Related Files
- **`components/history_embeddings/content/brave_history_embeddings_service.h`**
— Template wrapping `ChromeHistoryEmbeddingsService` that overrides
`OnPassageVisibilityCalculated` to synthesize passing visibility
scores, since Brave doesn't use `PageContentAnnotationsService` for
content visibility filtering.
`OnPassageVisibilityCalculated` to synthesize passing visibility scores, since
Brave doesn't use `PageContentAnnotationsService` for content visibility
filtering.
- **`chromium_src/chrome/browser/history_embeddings/history_embeddings_service_factory.cc`**
— Override to use `BravePassageEmbeddingsServiceController` and
@@ -121,19 +114,17 @@ without touching the upstream header (see
- **`chromium_src/components/passage_embeddings/core/passage_embeddings_service_controller.h`**
— Chromium_src include shim. Adds `virtual` to
`EmbedderReady`/`GetEmbedderMetadata`/`GetEmbeddings` via
`#define`s, and declares
`friend class BravePassageEmbeddingsServiceController` by
macro-injecting it through the `EmbedderRunning` anchor (same
idiom as `chromium_src/ui/android/view_android.h`).
`EmbedderReady`/`GetEmbedderMetadata`/`GetEmbeddings` via `#define`s, and
declares `friend class BravePassageEmbeddingsServiceController` by
macro-injecting it through the `EmbedderRunning` anchor (same idiom as
`chromium_src/ui/android/view_android.h`).
- **`chromium_src/chrome/browser/page_content_annotations/`** — Factory
overrides for `PageContentAnnotationsService`,
`PageContentExtractionService`, and `PageEmbeddingsService`.
overrides for `PageContentAnnotationsService`, `PageContentExtractionService`,
and `PageEmbeddingsService`.
- **`chromium_src/chrome/browser/optimization_guide/`** — Factory
override to enable `OptimizationGuideKeyedService` when
`kHistoryEmbeddings` is active.
- **`chromium_src/chrome/browser/optimization_guide/`** — Factory override to
enable `OptimizationGuideKeyedService` when `kHistoryEmbeddings` is active.
## Flow
browser/resources/brave_new_tab_page_refresh/README.md
+12 -12
View File
@@ -4,15 +4,15 @@
Brave NTP is a React application organized into the following folders:
* `assets`: Images and other resources (e.g. SVGs) that will be bundled into the
application
* `components`: The React components implementing the application view layer
* `components/common`: Generically useful helper views
* `context`: Providers and associated hooks for any context that will be made
available to the application or subtrees of the application
* `lib`: Small helper and utility modules
* `state`: App-wide state definitions and associated action interfaces. The
modules in this folder should not contain dependencies on React or the view
layer.
* `stories`: Storybook stories used for rapid UI development, along with
supporting action handlers.
- `assets`: Images and other resources (e.g. SVGs) that will be bundled into the
application
- `components`: The React components implementing the application view layer
- `components/common`: Generically useful helper views
- `context`: Providers and associated hooks for any context that will be made
available to the application or subtrees of the application
- `lib`: Small helper and utility modules
- `state`: App-wide state definitions and associated action interfaces. The
modules in this folder should not contain dependencies on React or the view
layer.
- `stories`: Storybook stories used for rapid UI development, along with
supporting action handlers.
build/chromium/resources/README.md
+2 -1
View File
@@ -1 +1,2 @@
This directory contains resource files that should overwrite upstream. It is for resource files only (jpg, svg, xml, etc...)
This directory contains resource files that should overwrite upstream. It is for
resource files only (jpg, svg, xml, etc...)
components/brave_account/endpoint_client/README.md
+37 -16
View File
@@ -1,6 +1,7 @@
# Endpoint Client
This component provides a **generic, type-safe client abstraction** for calling HTTP endpoints.
This component provides a **generic, type-safe client abstraction** for calling
HTTP endpoints.
It centralizes and standardizes:
@@ -12,7 +13,8 @@ It centralizes and standardizes:
## Motivation
Without a shared abstraction, each endpoint reimplements the same mechanics described above.
Without a shared abstraction, each endpoint reimplements the same mechanics
described above.
This repetition leads to:
@@ -21,11 +23,14 @@ This repetition leads to:
- fragile, stringly-typed JSON construction/parsing
- avoidable runtime failures
This abstraction consolidates these concerns behind a compile-time-validated interface and enforces correctness guarantees through C++ `concept`s and `base::expected<>`.
This abstraction consolidates these concerns behind a compile-time-validated
interface and enforces correctness guarantees through C++ `concept`s and
`base::expected<>`.
## Usage
`Client<>` integrates with the JSON schema/IDL compiler, which auto-generates request and response types implementing `ToValue()` and `FromValue()`.
`Client<>` integrates with the JSON schema/IDL compiler, which auto-generates
request and response types implementing `ToValue()` and `FromValue()`.
Hand-written types are supported, but the IDL workflow is recommended.
@@ -77,7 +82,8 @@ namespace endpoints {
};
```
Use the `generated_types` template in your `BUILD.gn` to generate C++ request/response classes from the IDL.
Use the `generated_types` template in your `BUILD.gn` to generate C++
request/response classes from the IDL.
`BUILD.gn`:
@@ -107,7 +113,9 @@ using LoginInit = BraveEndpoint<
} // namespace brave_account::endpoints
```
The `BraveEndpoint<>` template simplifies defining endpoints for Brave services. It uses `brave_domains::GetServicesDomain()` under the hood to automatically resolve the service domain to the correct environment.
The `BraveEndpoint<>` template simplifies defining endpoints for Brave services.
It uses `brave_domains::GetServicesDomain()` under the hood to automatically
resolve the service domain to the correct environment.
For non-Brave services, you can define an endpoint manually:
@@ -126,7 +134,8 @@ struct MyEndpoint {
### 2. Send the request and receive the response
`Client<>` enforces type safety: only the declared request type is accepted, and only the declared response type is returned.
`Client<>` enforces type safety: only the declared request type is accepted, and
only the declared response type is returned.
```cpp
LoginInit::Request request;
@@ -161,7 +170,9 @@ Client<LoginInit>::Send(
### 3. Adding request headers and receiving response headers
`Client<>` accepts requests with headers and can return responses with headers if you wrap your request or response types with `WithHeaders<>` — the same type safety applies.
`Client<>` accepts requests with headers and can return responses with headers
if you wrap your request or response types with `WithHeaders<>` — the same type
safety applies.
```cpp
// Request with headers
@@ -190,7 +201,8 @@ Client<MyEndpoint>::Send(
### 4. Cancelable requests
By default, requests are non-cancelable. To make a request cancelable, use the `RequestCancelability::kCancelable` template parameter:
By default, requests are non-cancelable. To make a request cancelable, use the
`RequestCancelability::kCancelable` template parameter:
```cpp
RequestHandle request_handle =
@@ -201,18 +213,23 @@ RequestHandle request_handle =
request_handle.reset(); // cancels the request
```
`RequestHandle` is a type-erased `std::unique_ptr<>` to the underlying `network::SimpleURLLoader` with a sequence-aware deleter, so you can safely pass it across sequences. Destroying the handle cancels the request.
`RequestHandle` is a type-erased `std::unique_ptr<>` to the underlying
`network::SimpleURLLoader` with a sequence-aware deleter, so you can safely pass
it across sequences. Destroying the handle cancels the request.
---
### 5. Mocking endpoints in tests
`Client<>::Send<>()` depends only on a `network::SharedURLLoaderFactory`, so in tests you can construct and configure a `network::TestURLLoaderFactory`, then pass `test_url_loader_factory_.GetSafeWeakWrapper()` to the code under test.
`Client<>::Send<>()` depends only on a `network::SharedURLLoaderFactory`, so in
tests you can construct and configure a `network::TestURLLoaderFactory`, then
pass `test_url_loader_factory_.GetSafeWeakWrapper()` to the code under test.
Helpers for registering typed mock responses are available in
Helpers for registering typed mock responses are available in
`//brave/components/endpoint_client:test_support`.
This allows you to simulate transport errors, HTTP failures, and both success/error bodies without introducing additional mock layers.
This allows you to simulate transport errors, HTTP failures, and both
success/error bodies without introducing additional mock layers.
```cpp
MockResponseFor<LoginInit>(test_url_loader_factory_,
@@ -228,7 +245,9 @@ MockResponseFor<LoginInit>(test_url_loader_factory_,
#### When an interceptor is required
If multiple endpoints in your test share the same URL and differ only by HTTP method, use a `network::TestURLLoaderFactory` interceptor to match the outgoing request to the expected endpoint:
If multiple endpoints in your test share the same URL and differ only by HTTP
method, use a `network::TestURLLoaderFactory` interceptor to match the outgoing
request to the expected endpoint:
```cpp
test_url_loader_factory_.SetInterceptor(
@@ -250,6 +269,8 @@ test_url_loader_factory_.SetInterceptor(
## Contributing
The `Client<>` API surface and behavioral semantics are intentionally constrained, with ongoing plans to extend its capabilities as needed.
The `Client<>` API surface and behavioral semantics are intentionally
constrained, with ongoing plans to extend its capabilities as needed.
To keep the design coherent, please discuss proposed changes before opening pull requests against `//brave/components/endpoint_client`.
To keep the design coherent, please discuss proposed changes before opening pull
requests against `//brave/components/endpoint_client`.
components/brave_policy/README.md
+9 -4
View File
@@ -1,7 +1,12 @@
There are 2 types of policy providers.
- BraveBrowserPolicyProvider: There is only one of these providers and it manages policies that are stored globally in local state.
- BraveProfilePolicyProvider: There is one of these providers per profile and it manages policies that are stored in profile prefs.
- BraveBrowserPolicyProvider: There is only one of these providers and it
manages policies that are stored globally in local state.
- BraveProfilePolicyProvider: There is one of these providers per profile and it
manages policies that are stored in profile prefs.
Policies are defined in `components/policy/resources/templates/policy_definitions/BraveSoftware/` and the YAML file has a `per_profile` attribute which associates it accordingly to the browser or profile provider.
Both of these providers will be used for Brave Origin, but also for other work within Brave.
Policies are defined in
`components/policy/resources/templates/policy_definitions/BraveSoftware/` and
the YAML file has a `per_profile` attribute which associates it accordingly to
the browser or profile provider. Both of these providers will be used for Brave
Origin, but also for other work within Brave.
components/challenge_bypass_ristretto/rust/cxx/README.md
+2 -1
View File
@@ -1,3 +1,4 @@
# challenge-bypass-ristretto-cxx
Experimental safe C++ wrappers to expose functionality from challenge-bypass-ristretto, using [cxx](https://cxx.rs/).
Experimental safe C++ wrappers to expose functionality from
challenge-bypass-ristretto, using [cxx](https://cxx.rs/).
components/p3a/constellation/README.md
+8 -3
View File
@@ -1,6 +1,11 @@
# Constellation CXX binding
This is a CXX binding for a [Rust library](https://github.com/brave/constellation) implementing the Constellation threshold aggregation mechanism.
It allows clients to submit ordered, granular data at the highest that is possible whilst maintaining crowd-based anonymity for P3A metrics.
This is a CXX binding for a
[Rust library](https://github.com/brave/constellation) implementing the
Constellation threshold aggregation mechanism. It allows clients to submit
ordered, granular data at the highest that is possible whilst maintaining
crowd-based anonymity for P3A metrics.
For usage, see the Constellation [README](https://github.com/brave/constellation) and comments in rs/cxx/src/lib.rs.
For usage, see the Constellation
[README](https://github.com/brave/constellation) and comments in
rs/cxx/src/lib.rs.
components/psst/README.md
+93 -43
View File
@@ -3,41 +3,71 @@
The feature helps tweak privacy settings on popular websites.
## Spec
https://docs.google.com/document/d/1ccnBWBV_KkknZpZYxcOXTwtfIiaSzeLS5dMd08N2pbs/edit?tab=t.0
# PSST Common Workflow
1. The user opens any website.
2. PSST feature detects that it is supported website (it means that browser loads PSST CRX component and find the appropriate user and policy scripts).
3. The browser injects the user script into the page. The primary goal of the user script is to ensure that the user is signed in to the current website and return a list of URLs where we should apply the privacy settings.
- the results of the user script execution we process here:</br> `PsstTabWebContentsObserver::OnUserScriptResult`
2. PSST feature detects that it is supported website (it means that browser
loads PSST CRX component and find the appropriate user and policy scripts).
3. The browser injects the user script into the page. The primary goal of the
user script is to ensure that the user is signed in to the current website
and return a list of URLs where we should apply the privacy settings.
- the results of the user script execution we process here:</br>
`PsstTabWebContentsObserver::OnUserScriptResult`
4. If the user is not signed in, we just break the flow.
5. To inform the user that the PSST feature is available for a given website, we display an infobar: `Brave can help you optimize this site's privacy settings. Would you like to review Brave's suggestions?`
6. If the user accepts the infobar prompt, we pass the list of URLs further and display a consent modal dialog. In this dialog, the user can choose their preferred privacy settings and track the progress of the operation.
7. When the user clicks the OK button, we inject the policy script and execute it.
8. The policy script does the next things:
- saves the list of URLs (tasks) to local storage to be available after the next navigation;
- calculates current progress;
- takes the first URL (URL_1) and marks it as current;
- navigates to that URL;
- returns the progress and applied tasks list to the back-end: `PsstTabWebContentsObserver::OnPolicyScriptResult(int nav_entry_id,base::Value script_result)`</br>
where after deserialization and validation, we update the flow's status on the consent dialog, by calling the UI delegate's method:</br>
`UpdateTasks(long progress,const std::vector<PolicyTask>& applied_tasks)`</br>
9. When navigation to URL_1 is complete, and it is a supported website, the user script is injected and executed. Then the same happens as in points #3,4.
10. Since the workflow is running and the consent dialog is visible, we inject the policy script.
11. Once injected, the policy script loads saved URLs (tasks) from local storage, takes the current' URL (see p. #7), and applies the privacy setting.
12. Once the privacy setting is applied, the policy script marks the current URL as applied, takes the next one from the available URL (task) list and marks it as current, saves all the info to local storage, and navigates to the new current one.
13. Then we enumerate each available URL in the list and do the same as in points #8-11.
14. When all tasks are completed, the user sees all status and progress information in the consent dialog.
5. To inform the user that the PSST feature is available for a given website, we
display an infobar:
`Brave can help you optimize this site's privacy settings. Would you like to review Brave's suggestions?`
6. If the user accepts the infobar prompt, we pass the list of URLs further and
display a consent modal dialog. In this dialog, the user can choose their
preferred privacy settings and track the progress of the operation.
7. When the user clicks the OK button, we inject the policy script and execute
it.
8. The policy script does the next things:
- saves the list of URLs (tasks) to local storage to be available after the
next navigation;
- calculates current progress;
- takes the first URL (URL_1) and marks it as current;
- navigates to that URL;
- returns the progress and applied tasks list to the back-end:
`PsstTabWebContentsObserver::OnPolicyScriptResult(int nav_entry_id,base::Value script_result)`</br>
where after deserialization and validation, we update the flow's status on
the consent dialog, by calling the UI delegate's method:</br>
`UpdateTasks(long progress,const std::vector<PolicyTask>& applied_tasks)`</br>
9. When navigation to URL_1 is complete, and it is a supported website, the user
script is injected and executed. Then the same happens as in points #3,4.
10. Since the workflow is running and the consent dialog is visible, we inject
the policy script.
11. Once injected, the policy script loads saved URLs (tasks) from local
storage, takes the current' URL (see p. #7), and applies the privacy
setting.
12. Once the privacy setting is applied, the policy script marks the current URL
as applied, takes the next one from the available URL (task) list and marks
it as current, saves all the info to local storage, and navigates to the new
current one.
13. Then we enumerate each available URL in the list and do the same as in
points #8-11.
14. When all tasks are completed, the user sees all status and progress
information in the consent dialog.
### Workflow failure cases
1. <a id="script-times-out"></a>The script times out or page crashes.</br> This happens when an injected script (either from a user or a policy) never finishes running. Common causes include an infinite loop, a promise that never resolves, or renderer crash can lead to the same situation, when we need to stop the process and notify the front end.
1. <a id="script-times-out"></a>The script times out or page crashes.</br> This
happens when an injected script (either from a user or a policy) never
finishes running. Common causes include an infinite loop, a promise that
never resolves, or renderer crash can lead to the same situation, when we
need to stop the process and notify the front end.
#### Handling Script Timeouts and page crashes
The `base::OneShotTimer timeout_timer_;` is used to handle cases when a script fails to finish running, (i.e. ["The script times out or page crashes"](#script-times-out)).</br>
Use the next method for script execution as it starts the timer first (with interval: 15 seconds):
The `base::OneShotTimer timeout_timer_;` is used to handle cases when a script
fails to finish running, (i.e.
["The script times out or page crashes"](#script-times-out)).</br> Use the next
method for script execution as it starts the timer first (with interval: 15
seconds):
```
void PsstTabWebContentsObserver::RunWithTimeout(
const int last_committed_entry_id,
@@ -51,20 +81,25 @@ void PsstTabWebContentsObserver::RunWithTimeout(
}
```
Parameters:</br>
`const int last_committed_entry_id` - the unique last committed entry ID;</br>
`const std::string& script` - the script to be injected;</br>
`InsertScriptInPageCallback callback` - callback function that handles the script result once it executes;
The `PsstTabWebContentsObserver::OnScriptTimeout` is special timeout handler, which stops the other script execution result handlers by calling the `weak_factory_.InvalidateWeakPtrs();`
Parameters:</br> `const int last_committed_entry_id` - the unique last committed
entry ID;</br> `const std::string& script` - the script to be injected;</br>
`InsertScriptInPageCallback callback` - callback function that handles the
script result once it executes;
The `PsstTabWebContentsObserver::OnScriptTimeout` is special timeout handler,
which stops the other script execution result handlers by calling the
`weak_factory_.InvalidateWeakPtrs();`
# PSST CRX Component
Contains set of rules and scripts for small number of very popular sites (Google, Facebook, Twitter, Twitch, etc.).
Each rule set would be managed in open source (similar to https://github.com/brave/adblock-lists), and shipped daily to users.
Contains set of rules and scripts for small number of very popular sites
(Google, Facebook, Twitter, Twitch, etc.). Each rule set would be managed in
open source (similar to https://github.com/brave/adblock-lists), and shipped
daily to users.
Component ID: `lhhcaamjbmbijmjbnnodjaknblkiagon`
Component version: `1`
- Component ID: `lhhcaamjbmbijmjbnnodjaknblkiagon`
- Component version: `1`
### Component's folder structure:
@@ -86,6 +121,7 @@ Component version: `1`
Contains a set of rules for each supported website:
Example:
```
[
{
@@ -115,13 +151,17 @@ Example:
#### user.js
Script which helps to find the user identifier for the currently-logged-in user on the current website. We need this in order to apply PSST.
The output of user script execution is JSON, which contains the following fields:
`user_id` - contains the identifier of the logged-in user for the current website.
`site_name` - site's name or description that will be shown on the consent dialog.
`tasks` - list of objects (url and description pairs) where `url` is the URL of the settings page for the website that we propose to change and its description.
Script which helps to find the user identifier for the currently-logged-in user
on the current website. We need this in order to apply PSST. The output of user
script execution is JSON, which contains the following fields: `user_id` -
contains the identifier of the logged-in user for the current website.
`site_name` - site's name or description that will be shown on the consent
dialog. `tasks` - list of objects (url and description pairs) where `url` is the
URL of the settings page for the website that we propose to change and its
description.
Example:
```
{
"user_id": <logged-in user identifier>,
@@ -131,15 +171,19 @@ Example:
url:<setting url, MUST BE UNIQUE>,
description:<setting description>,
},
....
....
]
}
```
#### policy.js
The policy script takes as parameter the list of tasks from the user script output and saves it to the local storage. When the policy script is executed and local storage already contains the tasks list it takes one task and processes it.
To pass parameter to the policy script we should prepend the script with the definition of the params variable, which contains tasks, returned by user script:
The policy script takes as parameter the list of tasks from the user script
output and saves it to the local storage. When the policy script is executed and
local storage already contains the tasks list it takes one task and processes
it. To pass parameter to the policy script we should prepend the script with the
definition of the params variable, which contains tasks, returned by user
script:
##### Policy script parameters:
@@ -155,6 +199,7 @@ const params = {
```
##### Policy script result:
The policy script returns the next object as result:
```
@@ -167,13 +212,18 @@ The policy script returns the next object as result:
}]
}
```
- `progress` - script calculates the percent of operation completion;
- `applied_tasks` - array of the completed tasks, each task is an object `url/description/error_description`
- `applied_tasks` - array of the completed tasks, each task is an object
`url/description/error_description`
# PSST Consent Dialog & Frontend Resources
The PSST feature includes a WebUI dialog for user interaction. All UI code and resources are located in:
The PSST feature includes a WebUI dialog for user interaction. All UI code and
resources are located in:
components/psst/resources/ui/
This dialog is responsible for displaying a list of tasks the PSST feature intends to apply, along with the progress and status for each task and the overall global progress.
This dialog is responsible for displaying a list of tasks the PSST feature
intends to apply, along with the progress and status for each task and the
overall global progress.
components/web_discovery/browser/anonymous_credentials/README.md
+4 -1
View File
@@ -1,5 +1,8 @@
# anonymous-credentials
Partial implementation of Direct Anonymous Attestation (DAA) for the Web Discovery Project. Only signer functions are available. Performs the same elliptic curve operations as the [original C library](https://github.com/whotracksme/anonymous-credentials).
Partial implementation of Direct Anonymous Attestation (DAA) for the Web
Discovery Project. Only signer functions are available. Performs the same
elliptic curve operations as the
[original C library](https://github.com/whotracksme/anonymous-credentials).
bn254 is the only supported curve for this library.
docs/README.md
+46 -40
View File
@@ -1,64 +1,70 @@
# Brave docs
This directory contains documentation for the Brave Browser. For additional resources outside this repository, go to:
This directory contains documentation for the Brave Browser. For additional
resources outside this repository, go to:
* [brave-browser/wiki](https://github.com/brave/brave-browser/wiki)
- [brave-browser/wiki](https://github.com/brave/brave-browser/wiki)
## Document Index
### Checking Out and Patching
* [Upgrading Chromium](chromium_version_upgrade.md) Upgrading `brave-core` to
a newer Chromium version.
* [Patching with `plaster`](plaster.md) A patching engine for semantical
patching of upstream Chromium.
* [WebUI Overriding](webui_overriding.md)
* [DevTools Frontend Patching](devtools_frontend_patching.md) Managing
changes to the upstream project.
- [Upgrading Chromium](chromium_version_upgrade.md) Upgrading `brave-core` to a
newer Chromium version.
- [Patching with `plaster`](plaster.md) A patching engine for semantical
patching of upstream Chromium.
- [WebUI Overriding](webui_overriding.md)
- [DevTools Frontend Patching](devtools_frontend_patching.md) Managing changes
to the upstream project.
### Tools
* [Claude Code Skills](claude_code_skills.md) - Slash commands for automating
common development tasks (commit, review, preflight, CI, and more).
- [Claude Code Skills](claude_code_skills.md) - Slash commands for automating
common development tasks (commit, review, preflight, CI, and more).
### Security and Privacy
* [Premium Account Privacy](premium_account_privacy.md) -
How blind tokens decouple payment identity from service usage.
* [Cryptographic Features](cryptography.md) - Cryptographic features in Brave
beyond standard Chromium encryption.
- [Premium Account Privacy](premium_account_privacy.md) - How blind tokens
decouple payment identity from service usage.
- [Cryptographic Features](cryptography.md) - Cryptographic features in Brave
beyond standard Chromium encryption.
### General Development
* [Running test suites](running_test_suites.md) - Selectively execute unit,
browser and typescript tests.
* [`gni` notes](gni_sources.md) - Brief notes on the use of `source.gni`
files in our code base.
* [Rust notes](rust.md) - General recommendations on integrating rust code
into `brave-core`
* [Adapting Chromium tests to the Brave Codebase](adapting_chromium_tests.md) -
Suggestions on how to make chromium test work on our test targets.
* [Ship a File to All Clients](ship_a_file_to_all_clients.md) - How to ship a
file to all clients via component updater.
* [Git Configuration](git_configuration.md) - General recommendations for
setting up and optimizing your Git environment.
* [Ignoring Files from Format and Presubmit Checks](ignoring_format_checks.md) -
How to exclude files from format and presubmit checks.
* [Siso Customization](siso_customization.md) - How we customize Siso to work
for us.
* [WebUI Frontend](./webui_frontend.md) - General Web UI, React, webpack
overview.
* [WebUI Testing](./webui_testing.md) - Guide to creating and running *.test.ts(x) suites.
* [WebUI Strings Overview](./webui_strings_explainer.md) - Including strings in a Web UI frontend.
- [Running test suites](running_test_suites.md) - Selectively execute unit,
browser and typescript tests.
- [`gni` notes](gni_sources.md) - Brief notes on the use of `source.gni` files
in our code base.
- [Rust notes](rust.md) - General recommendations on integrating rust code into
`brave-core`
- [Adapting Chromium tests to the Brave Codebase](adapting_chromium_tests.md) -
Suggestions on how to make chromium test work on our test targets.
- [Ship a File to All Clients](ship_a_file_to_all_clients.md) - How to ship a
file to all clients via component updater.
- [Git Configuration](git_configuration.md) - General recommendations for
setting up and optimizing your Git environment.
- [Ignoring Files from Format and Presubmit Checks](ignoring_format_checks.md) -
How to exclude files from format and presubmit checks.
- [Siso Customization](siso_customization.md) - How we customize Siso to work
for us.
- [WebUI Frontend](./webui_frontend.md) - General Web UI, React, webpack
overview.
- [WebUI Testing](./webui_testing.md) - Guide to creating and running
\*.test.ts(x) suites.
- [WebUI Strings Overview](./webui_strings_explainer.md) - Including strings in
a Web UI frontend.
## Creating Documentation
> [!IMPORTANT]
> If you add new documents, please also add a link to them in the Document
> Index below.
>
> If you add new documents, please also add a link to them in the Document Index
> below.
### Guidelines
* Markdown documents must follow the
[Markdown Style
Guide](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/markdown/markdown.md).
- Markdown documents must follow the
[Markdown Style Guide](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/markdown/markdown.md).
Use `npm run format` to auto format documents.
elevation_service/README.md
+21 -10
View File
@@ -4,26 +4,37 @@
### When does this get registered
This Windows-specific service is registered for system level installs. There are two ways a system level install can be done:
- UAC prompt raised during Brave install (ex: person has admin privs) and person clicks `Yes` to accept escalation.
- Brave installer executable is invoked with `--system-level` argument in command line which has admin privs.
This Windows-specific service is registered for system level installs. There are
two ways a system level install can be done:
- UAC prompt raised during Brave install (ex: person has admin privs) and person
clicks `Yes` to accept escalation.
- Brave installer executable is invoked with `--system-level` argument in
command line which has admin privs.
### What is the service used for?
Currently, the elevation service is only used to install the `Brave VPN` services once the browser detects the product was purchased.
Currently, the elevation service is only used to install the `Brave VPN`
services once the browser detects the product was purchased.
### Debugging
The service executable is inside the versioned folder of Brave. It's possible to debug the service interactively by using the following procedure:
The service executable is inside the versioned folder of Brave. It's possible to
debug the service interactively by using the following procedure:
1. Open `regedit.exe`
2. Navigate to `[HKEY_CLASSES_ROOT\AppID\{5693E62D-00D6-4421-AFE8-58F3C947436A}]` (or if building another channel, [check here to find the right AppID](https://github.com/brave/brave-core/blob/master/chromium_src/chrome/install_static/chromium_install_modes.cc)).
3. Delete the `LocalService` value (should be set to something like `BraveDevelopmentElevationService`) and create a new String value called `RunAs` with the data value set to `Interactive User`.
2. Navigate to
`[HKEY_CLASSES_ROOT\AppID\{5693E62D-00D6-4421-AFE8-58F3C947436A}]` (or if
building another channel,
[check here to find the right AppID](https://github.com/brave/brave-core/blob/master/chromium_src/chrome/install_static/chromium_install_modes.cc)).
3. Delete the `LocalService` value (should be set to something like
`BraveDevelopmentElevationService`) and create a new String value called
`RunAs` with the data value set to `Interactive User`.
4. Open an admin `cmd.exe` instance.
5. Navigate to the path where you built the elevation service executable (ex: `C:\brave\src\out\Component`).
5. Navigate to the path where you built the elevation service executable (ex:
`C:\brave\src\out\Component`).
6. Launch the exe via `elevation_service.exe --console`.
7. After debugging, don't forget to undo step 3.
These steps will let you run a locally compiled version of elevation service. This is very helpful for debugging or tracing the logic there.
These steps will let you run a locally compiled version of elevation service.
This is very helpful for debugging or tracing the logic there.
tools/cr/README.md
+29 -29
View File
@@ -1,14 +1,15 @@
# `tools/cr`
Python tooling maintained by the Chromium Rebase team to support upgrading
`brave-core` to new Chromium versions and to manage the patches and shadow
files that live on top of upstream.
`brave-core` to new Chromium versions and to manage the patches and shadow files
that live on top of upstream.
All scripts here are intended to run via `vpython3`; the `.vpython3` spec in
this directory pulls in `rich`, `requests`, and the other wheels they need.
Most scripts accept `--verbose` to switch logging to `DEBUG`.
this directory pulls in `rich`, `requests`, and the other wheels they need. Most
scripts accept `--verbose` to switch logging to `DEBUG`.
> [!IMPORTANT]
>
> Before adding or editing Python in this directory, read
> [Python dos and donts](python_dos_and_donts.md).
@@ -16,39 +17,38 @@ Most scripts accept `--verbose` to switch logging to `DEBUG`.
These are the user-facing scripts in this directory:
* **🚀Brockit** — End-to-end rebase orchestration. Updates the Chromium
version, regenerates patches and strings, and walks the rebase forward.
* **🩹Plaster** — Applies and regenerates "plaster" files: semantic patches
against upstream Chromium sources.
* `post_presubmit.py` — Posts and refreshes GitHub PR comments from a
`npm run presubmit` JSON dump.
* `find_rebase_commits.py` — Resolves a Chromium rebase tag (e.g.
`cr148`) to an `oldest..newest` git commit range.
* `prune_test_filters.py` — Detects and (optionally) removes obsolete
entries from the current platform's test-filter files.
- **🚀Brockit** — End-to-end rebase orchestration. Updates the Chromium version,
regenerates patches and strings, and walks the rebase forward.
- **🩹Plaster** — Applies and regenerates "plaster" files: semantic patches
against upstream Chromium sources.
- `post_presubmit.py` — Posts and refreshes GitHub PR comments from a
`npm run presubmit` JSON dump.
- `find_rebase_commits.py` — Resolves a Chromium rebase tag (e.g. `cr148`) to an
`oldest..newest` git commit range.
- `prune_test_filters.py` — Detects and (optionally) removes obsolete entries
from the current platform's test-filter files.
## Library modules
Shared abstractions used by the entry points and tests:
* `repository.py` — `Repository` instances (`repository.brave`,
`repository.chromium`) for paths and for running git commands at any repo.
* `terminal.py` — Rich console, baseline logging config, and subprocess
utilities.
* `vpython_utils.py` — Provides `vpython3` path.
* `patchfile.py` — Patch file abstraction handling patches that failed to
apply.
* `git_status.py` — Parser for `git status --porcelain` output.
* `versioning.py` — Chromium version number parsing.
* `vscode.py` — IPC for opening files in VS Code in the integrated terminal.
- `repository.py` — `Repository` instances (`repository.brave`,
`repository.chromium`) for paths and for running git commands at any repo.
- `terminal.py` — Rich console, baseline logging config, and subprocess
utilities.
- `vpython_utils.py` — Provides `vpython3` path.
- `patchfile.py` — Patch file abstraction handling patches that failed to apply.
- `git_status.py` — Parser for `git status --porcelain` output.
- `versioning.py` — Chromium version number parsing.
- `vscode.py` — IPC for opening files in VS Code in the integrated terminal.
## Subdirectories
* `alias/` — `git cr` git-alias subcommands (`commit`, `mv`,
`follow-renames`, ...). See [`alias/README.md`](alias/README.md).
* `test/` — Shared test fixtures, including `FakeChromiumRepo`.
* `toolchain/` — Scripts to build platform-specific toolchains when
rebasing Chromium.
- `alias/` — `git cr` git-alias subcommands (`commit`, `mv`, `follow-renames`,
...). See [`alias/README.md`](alias/README.md).
- `test/` — Shared test fixtures, including `FakeChromiumRepo`.
- `toolchain/` — Scripts to build platform-specific toolchains when rebasing
Chromium.
## Tests
tools/cr/alias/README.md
+47 -52
View File
@@ -13,10 +13,10 @@ python3 tools/cr/alias/cmd.py setup-alias
git cr install-hook
```
* `setup-alias` writes a `cr` entry to `.git/config`. After this, `git cr`
works in this repository.
* `install-hook` installs `commit-msg.py` as the repository's `commit-msg`
hook. This is necessary to use `git cr commit`
- `setup-alias` writes a `cr` entry to `.git/config`. After this, `git cr` works
in this repository.
- `install-hook` installs `commit-msg.py` as the repository's `commit-msg` hook.
This is necessary to use `git cr commit`
Once installed, run `git cr` to see the available commands.
@@ -34,8 +34,8 @@ git cr commit --issue 12345 -m "Resolve crash on launch"
git cr commit --culprit abc123,def456 -m "Adjust to upstream API change"
```
[commit-msg hook behaviour](#commit-msg-hook-behaviour) section below for
more details.
[commit-msg hook behaviour](#commit-msg-hook-behaviour) section below for more
details.
### `git cr mv`
@@ -49,27 +49,24 @@ npm run build -- --target=brave:all
What it repairs after the rename:
* C++ include guards in moved `.h` files (regenerated to match the new
path).
* `#include <…>` shadow-include lines in moved `chromium_src/` files.
* `#include` / `#import` directives across `brave-core` (both quoted and
angle-bracket forms, including `.mojom` files and their derived
`*.mojom.h`, `*.mojom-blink.h`, etc.).
* `// path/to/file` style references inside C++ comments and `.gn`/`.gni`
files.
* `BUILD.gn` / `.gni` source-list entries in the ancestor chain of the
moved file.
* Quoted GN root references (`"//path/to/file"`) and relative GN
references in `.gn` / `.gni` files.
* Plaster files (`rewrite/…/foo.h.yaml`, or the deprecated
`rewrite/…/foo.h.toml`) and their associated patch files in
`patches/`. The new plaster file is re-applied so `patches/` is
refreshed.
- C++ include guards in moved `.h` files (regenerated to match the new path).
- `#include <…>` shadow-include lines in moved `chromium_src/` files.
- `#include` / `#import` directives across `brave-core` (both quoted and
angle-bracket forms, including `.mojom` files and their derived `*.mojom.h`,
`*.mojom-blink.h`, etc.).
- `// path/to/file` style references inside C++ comments and `.gn`/`.gni` files.
- `BUILD.gn` / `.gni` source-list entries in the ancestor chain of the moved
file.
- Quoted GN root references (`"//path/to/file"`) and relative GN references in
`.gn` / `.gni` files.
- Plaster files (`rewrite/…/foo.h.yaml`, or the deprecated
`rewrite/…/foo.h.toml`) and their associated patch files in `patches/`. The
new plaster file is re-applied so `patches/` is refreshed.
### `git cr follow-renames`
This command has some similarities to `git-cr-mv`, however its main role is
to correct move operations that occurred in upstream Chromium.
This command has some similarities to `git-cr-mv`, however its main role is to
correct move operations that occurred in upstream Chromium.
```sh
# All renames between two Chromium version tags (typical version bump):
@@ -82,23 +79,23 @@ git cr follow-renames 4f093f4239eb2814f57bc97ee593d7acd717ac42
This command does all the rewrites done by `git-cr-mv`, but it also does a few
extra things:
1. Move `chromium_src/<old>` to `chromium_src/<new>` and refresh its
include guard and shadow `#include` line.
1. Move `chromium_src/<old>` to `chromium_src/<new>` and refresh its include
guard and shadow `#include` line.
2. Move `rewrite/<old>.yaml` (or the deprecated `rewrite/<old>.toml`) to
`rewrite/<new>.yaml` (resp. `.toml`), delete the stale `patches/…`
patch file (and `.patchinfo`), then re-run plaster on the new
plaster file so a fresh patch is produced.
`rewrite/<new>.yaml` (resp. `.toml`), delete the stale `patches/…` patch file
(and `.patchinfo`), then re-run plaster on the new plaster file so a fresh
patch is produced.
3. Update every `#include`, `#import`, `// comment`, `BUILD.gn`, and `.gni`
reference across `brave-core` (same logic as `git cr mv`).
4. For any patch that is **not** managed by plaster, rewrite the patch's
`--- a/old`, `+++ b/new`, and `diff --git` lines, rename the file, and
try `git apply --3way` against the Chromium tree so conflicts surface
`--- a/old`, `+++ b/new`, and `diff --git` lines, rename the file, and try
`git apply --3way` against the Chromium tree so conflicts surface
immediately.
## Why the use of a git commit message hook
Chromium rebases usually involve hundreds of fixes to Brave. These fixes are
the result of the way Chromium evolves. Therefore, `cr` have to provide a
Chromium rebases usually involve hundreds of fixes to Brave. These fixes are the
result of the way Chromium evolves. Therefore, `cr` have to provide a
significant amount of information regading the project history when introducing
these fixes. This is vital when trying to understand when and why certain
changes were introduced in the project.
@@ -130,20 +127,20 @@ documentation. A few examples that we use it for:
### Every commit on a `cr` is expected to have a `[crXXX]` tag
The main covenience the hook provides, is the enforcement of `[cr149]` prefix
when working on `cr` branches, which easily catches one's attention when
looking on a blame. This branch tag is important for any commit that is not
too obvious to be part of a `cr` branch without it.
when working on `cr` branches, which easily catches one's attention when looking
on a blame. This branch tag is important for any commit that is not too obvious
to be part of a `cr` branch without it.
### Using commit tags to provide context
We should always try to provide tags, as a way to group changes together.
For examnple, when a change only matters on a single platform, an OS tag could
(e.g. `[android]`, `[ios]`, etc) can provide important context when reviewing
the change, and also make it easier similar changes.
We should always try to provide tags, as a way to group changes together. For
examnple, when a change only matters on a single platform, an OS tag could (e.g.
`[android]`, `[ios]`, etc) can provide important context when reviewing the
change, and also make it easier similar changes.
This is strongly encouraged. A single grep then yields every fix that
has touched the affected surface, and reviewers triaging a regression may be
able to take advantage of such extra context.
This is strongly encouraged. A single grep then yields every fix that has
touched the affected surface, and reviewers triaging a regression may be able to
take advantage of such extra context.
Adding additional tags is very simple:
@@ -153,22 +150,20 @@ Adding additional tags is very simple:
# [cr149][WIP] Guard against null TabStripModel
```
### Each change should reference at least one upstream culprit
Rebase branch can grow to hundreds of changes. For reviewers, and future code
archeologists, it is important that we provide the exact cause for introducing
a change into the branch. The upstream changes driving our fixes are referred
to as **culprits**, and the tooling provides ways to keep them in our history.
archeologists, it is important that we provide the exact cause for introducing a
change into the branch. The upstream changes driving our fixes are referred to
as **culprits**, and the tooling provides ways to keep them in our history.
`git cr commit --culprit <hash>` expands each hash into the commit message
of the fix being done. This allows us to have a record, but also to use
`git cr commit --culprit <hash>` expands each hash into the commit message of
the fix being done. This allows us to have a record, but also to use
`git log --grep` to find changes based on CL numbers or `crbug` issue numbers.
Auto-generated upgrade messages (`Update from Chromium …`,
`Update patches from Chromium …`, `Updated strings for Chromium …`) are
left verbatim so they remain easy to grep.
`Update patches from Chromium …`, `Updated strings for Chromium …`) are left
verbatim so they remain easy to grep.
We add culprits to commits using `git cr commit --culprit=[HASH,]`:
tools/cr/iwyu/README.md
+19 -18
View File
@@ -3,9 +3,9 @@
Two scripts that drive [include-what-you-use](https://include-what-you-use.org/)
over Brave sources:
* `build_iwyu.py` — builds the IWYU binary against Chromium's pinned Clang.
* `run_iwyu.py` — runs IWYU against an existing Brave build dir and applies
the suggested include fixes in place.
- `build_iwyu.py` — builds the IWYU binary against Chromium's pinned Clang.
- `run_iwyu.py` — runs IWYU against an existing Brave build dir and applies the
suggested include fixes in place.
IWYU is **not** part of the normal Brave build; run these scripts on demand.
@@ -34,8 +34,8 @@ Edit `brave/build/include_what_you_use_paths.cfg`. Each non-comment line is:
-path/to/disable
```
Paths are relative to `src/`. Longest-matching prefix wins, so you can
enable a directory and carve exceptions out of it:
Paths are relative to `src/`. Longest-matching prefix wins, so you can enable a
directory and carve exceptions out of it:
```
+brave/components/brave_ads/browser
@@ -44,9 +44,9 @@ enable a directory and carve exceptions out of it:
## Run IWYU
IWYU needs an existing Brave build in some `out/<config>` to pick up its
compile flags and generated headers, **and** several GN args have to be
flipped — without them IWYU crashes during analysis:
IWYU needs an existing Brave build in some `out/<config>` to pick up its compile
flags and generated headers, **and** several GN args have to be flipped —
without them IWYU crashes during analysis:
```sh
npm run build -- Static \
@@ -63,12 +63,13 @@ npm run build -- Static \
Required (IWYU crashes without these):
* `clang_use_chrome_plugins:false`.
* `force_enable_raw_ptr_exclusion:true`
* `enable_precompiled_headers:false`
* `treat_warnings_as_errors:false`
- `clang_use_chrome_plugins:false`.
- `force_enable_raw_ptr_exclusion:true`
- `enable_precompiled_headers:false`
- `treat_warnings_as_errors:false`
Then finally run `include-what-you-use` with `run_iwyu.py`, bearing in mind that `--out` is relative to `src/`, rather than the current directory.
Then finally run `include-what-you-use` with `run_iwyu.py`, bearing in mind that
`--out` is relative to `src/`, rather than the current directory.
```sh
vpython3 tools/cr/iwyu/run_iwyu.py --out out/Static --verbose
@@ -76,8 +77,8 @@ vpython3 tools/cr/iwyu/run_iwyu.py --out out/Static --verbose
This:
1. Generates a compile database from `out/<config>` and filters it to
sources enabled by `include_what_you_use_paths.cfg`.
1. Generates a compile database from `out/<config>` and filters it to sources
enabled by `include_what_you_use_paths.cfg`.
2. Runs `iwyu_tool.py` with our libc++ mapping file
(`brave/build/include_what_you_use_mappings.json5`).
3. Applies suggestions in place via `fix_includes.py`.
@@ -86,9 +87,9 @@ This:
Artifacts written next to the build:
* `out/<config>/iwyu_compile_commands.json` — filtered compile DB.
* `out/<config>/iwyu_suggestions.txt` — raw IWYU output, handy when a
rewrite looks wrong.
- `out/<config>/iwyu_compile_commands.json` — filtered compile DB.
- `out/<config>/iwyu_suggestions.txt` — raw IWYU output, handy when a rewrite
looks wrong.
## Defending an include from IWYU
tools/cr/toolchains/README.md
+33 -34
View File
@@ -1,14 +1,14 @@
# Browser Toolchain Scripts
This directory contains scripts for relating to the browser toolchains (compilers,
linkers, standard libraries, etc.) used by the Brave build.
This directory contains scripts for relating to the browser toolchains
(compilers, linkers, standard libraries, etc.) used by the Brave build.
## Design rules
Scripts here are designed to be launched with a single `curl` one-liner,
so they must be **self-contained in a single source file** with **no
dependencies outside the Python standard library**. Do not split logic across
helper modules or add third-party imports.
Scripts here are designed to be launched with a single `curl` one-liner, so they
must be **self-contained in a single source file** with **no dependencies
outside the Python standard library**. Do not split logic across helper modules
or add third-party imports.
Example invocation pattern:
@@ -24,8 +24,8 @@ curl -sL \
Bootstraps `depot_tools` on a fresh CI worker, and then runs a given python
script using `vpython3`. This allows for the toolchain python scripts to be run
across different environments with the same guarantees. Arguments after `--`
are forwarded verbatim.
across different environments with the same guarantees. Arguments after `--` are
forwarded verbatim.
```sh
curl -sSLf \
@@ -39,9 +39,9 @@ curl -sSLf \
### `build_rust_toolchain.py`
Builds and packages a minimal Rust toolchain subset for Chromium: the
`rust-lld` linker and the `wasm32-unknown-unknown` stage-1 standard-library
sysroot. The output is a `.tar.xz` archive ready for upload to GCS.
Builds and packages a minimal Rust toolchain subset for Chromium: the `rust-lld`
linker and the `wasm32-unknown-unknown` stage-1 standard-library sysroot. The
output is a `.tar.xz` archive ready for upload to GCS.
```sh
curl -sL \
@@ -75,8 +75,8 @@ that led to the creation of the toolchain.
toolchain at the same upstream Rust+Clang revisions. The script encodes it as
the final section of the tarball filename, so bumping it produces a fresh URL.
This control is important for cases where there are changes on our end for how
the toolchain should be generated, and a new distinct archive is necessary for
a toolchain already in use.
the toolchain should be generated, and a new distinct archive is necessary for a
toolchain already in use.
### `download_published_dep.py`
@@ -111,10 +111,10 @@ be extracted directly over it. Invoke with the target path, e.g.
### `build_xcode_toolchain.py`
Builds a hermetic, reproducible Xcode toolchain archive from
the local Xcode.app installation. The archive contains the subset of
files listed in Chromium's `build/xcode_binaries.yaml` plus the on-demand
Metal toolchain, with all archive metadata zeroed for reproducible builds.
macOS-only. Builds a hermetic, reproducible Xcode toolchain archive from the
local Xcode.app installation. The archive contains the subset of files listed in
Chromium's `build/xcode_binaries.yaml` plus the on-demand Metal toolchain, with
all archive metadata zeroed for reproducible builds.
```sh
curl -sL \
@@ -131,26 +131,25 @@ options. See the script's module docstring for the archive filename format.
### `xcode_accept_license.py`
macOS-only. Writes the two preference keys Apple's command-line tools
check for license acceptance
(`IDEXcodeVersionForAgreedToGMLicense` and `IDELastGMLicenseAgreedTo`)
into `/Library/Preferences/com.apple.dt.Xcode.plist`. Designed to be
installed at `/usr/local/bin/` and invoked under a narrowly-scoped
NOPASSWD sudoers grant so build hooks
(`brave/build/mac/download_hermetic_xcode.py`) can accept the license
without a password prompt.
macOS-only. Writes the two preference keys Apple's command-line tools check for
license acceptance (`IDEXcodeVersionForAgreedToGMLicense` and
`IDELastGMLicenseAgreedTo`) into
`/Library/Preferences/com.apple.dt.Xcode.plist`. Designed to be installed at
`/usr/local/bin/` and invoked under a narrowly-scoped NOPASSWD sudoers grant so
build hooks (`brave/build/mac/download_hermetic_xcode.py`) can accept the
license without a password prompt.
The script's own docstring covers manual install, the corresponding
sudoers entry, and the security model. Run with `--help` for the CLI.
The script's own docstring covers manual install, the corresponding sudoers
entry, and the security model. Run with `--help` for the CLI.
### `install_xcode_accept_license.py`
Installer/verifier for the helper above. Lays down both the script
(`/usr/local/bin/xcode_accept_license.py`, mode 0755 owned by
`root:wheel`) and the matching sudoers drop-in
(`/etc/sudoers.d/xcode_accept_license`, mode 0440 owned by root,
validated via `visudo -c`), then runs a non-destructive smoke test using
`sudo -n -l` to confirm the grant works without ever invoking the helper.
(`/usr/local/bin/xcode_accept_license.py`, mode 0755 owned by `root:wheel`) and
the matching sudoers drop-in (`/etc/sudoers.d/xcode_accept_license`, mode 0440
owned by root, validated via `visudo -c`), then runs a non-destructive smoke
test using `sudo -n -l` to confirm the grant works without ever invoking the
helper.
```sh
# install + verify
@@ -163,5 +162,5 @@ python3 install_xcode_accept_license.py --check-only --username $USER
python3 install_xcode_accept_license.py --uninstall
```
The script re-execs under sudo automatically if not invoked as root, so
there's no need to remember the `sudo` prefix.
The script re-execs under sudo automatically if not invoked as root, so there's
no need to remember the `sudo` prefix.
tools/perf/README.md
+27 -21
View File
@@ -2,18 +2,18 @@
## Job URLs
* [Window](<https://ci.brave.com/job/brave-browser-test-perf-windows/>)
* [MacOS](<https://ci.brave.com/job/brave-browser-test-perf-macos/>)
* [Android](<https://ci.brave.com/job/brave-browser-test-perf-android/>)
- [Window](https://ci.brave.com/job/brave-browser-test-perf-windows/)
- [MacOS](https://ci.brave.com/job/brave-browser-test-perf-macos/)
- [Android](https://ci.brave.com/job/brave-browser-test-perf-android/)
## S3 migration
Perf data is currently moving to AWS S3 `brave-perf-data` bucket.
The data is accessible via <https://perf-data.s3.brave.com/{path}>.
The current structure:
`./perf-profiles/`: test perf profiles
`./telemetry-perf-data/`: WPR files and other data are used by telemetry and
catapult code
Perf data is currently moving to AWS S3 `brave-perf-data` bucket. The data is
accessible via <https://perf-data.s3.brave.com/{path}>. The current structure:
- `./perf-profiles/`: test perf profiles
- `./telemetry-perf-data/`: WPR files and other data are used by telemetry and
catapult code
## S3 upload
@@ -22,25 +22,31 @@ The current structure:
## GSC manual upload (legacy)
`upload_to_google_storage.py --bucket=brave-telemetry <file>`
the script will produce `.sha1` automatically.
`upload_to_google_storage.py --bucket=brave-telemetry <file>` the script will
produce `.sha1` automatically.
## How to update or record WPR
Use `npm run perf_tests -- --mode record-wpr` instead of chromium `update_wpr` or `record_wpr`. It:
Use `npm run perf_tests -- --mode record-wpr` instead of chromium `update_wpr`
or `record_wpr`. It:
* downloads and runs both Brave and Chromium, combine .wpr files (to capture all browser-specific requests);
* adds pre-initialied profiles and Griffin/Finch experiments;
* does some pre runs to ensure that everything is initialized (aka online profile rebase)
* removes unwanted URLs from the final .wpr file.
- downloads and runs both Brave and Chromium, combine .wpr files (to capture all
browser-specific requests);
- adds pre-initialied profiles and Griffin/Finch experiments;
- does some pre runs to ensure that everything is initialized (aka online
profile rebase)
- removes unwanted URLs from the final .wpr file.
### Workflow
* Prepare a config (use configs/record-wpr.json5 as a base). One benchmark or storySet = one .wpr.
* Run `npm run perf_tests -- <config>.json5 --mode record-wpr --working-directory=.. --variations-repo-dir=..`;
* Run the matching benchmark locally to tests the created .wpr;
* Upload wpr files to the cloud storage: `ls ./brave/tools/perf/page_sets/data/*.wprgo | xargs <upload_cmd>`;
* Commit the changes, including a new `.sha1` files, to brave-core.
- Prepare a config (use configs/record-wpr.json5 as a base). One benchmark or
storySet = one .wpr.
- Run
`npm run perf_tests -- <config>.json5 --mode record-wpr --working-directory=.. --variations-repo-dir=..`;
- Run the matching benchmark locally to tests the created .wpr;
- Upload wpr files to the cloud storage:
`ls ./brave/tools/perf/page_sets/data/*.wprgo | xargs <upload_cmd>`;
- Commit the changes, including a new `.sha1` files, to brave-core.
## Updating profiles