BCC #2 -- chromium research resources
"BCC" stands for "Browser Contribution/Crash Club" :)
I wanna leave notes about how to research on Chrome.
This post may be updated regularly.
Find the code and commits
Chromium Code Search
url: https://source.chromium.org/chromium
- Terms in the code tend to be defined closely the same as in spec. You should google unfamiliar terms firstly. Class names, var names, etc.
- After jumping around many times, you may reach to dead ends. In many cases, this is a call to a Mojo obj. IPC. The dead ends are usually in the dir, gen/.... You can find the other edge of another process by searching ... of the dir name with a bit modification.
- You can change the hash, tag and branch. Be careful when researching on recent features.
Chromium dash
url: https://chromiumdash.appspot.com/
- You can search commits by username. It's especially useful when you wanna know about how the feature works in details by seeing commits one by one.
- You have to know username of the committer. Sometimes Chromium Platform Status is useful to find the owners. Sometimes directly googling works.
When reading the code on local
- While Chromium Code Search is really useful, you sometimes have to read the code on local. In this case, indexing is MUST.
- remote index is also available. But it doesn't support iOS, mac & windows targets yet (as of 2025/1/23).
Build it on local
- Basically, the official instruction is well-maintained.
- It's famous that building Chromium on local is hyper-time-consuming. Be careful, you may have to start research on the next day :)
- Don't forget to use ccache!! (mac: https://chromium.googlesource.com/chromium/src/+/main/docs/ccache_mac.md)
- If you use Mac, these can be also useful, though they are in Japanese.
IDE
- CLion works. VSCode also.
- I once used VSCode. But I'm now using CLion cuz its mouse-gesture feature is surprisingly helpful :)
- There is a doc for setting CLion for chromium: https://chromium.googlesource.com/chromium/src.git/+/master/docs/clion.md
- for debugging, please refer to the below debugging section.
- "Optional Steps" in the doc is worth checking imo.
Debugging
- on mac, you may basically use lldb. Check it out the lldb doc: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/lldbinit.md
- There is one for gdb also.
- CLion uses its bundled lldb and, as far as i tried, ~/.lldbinit settings explained in the doc doesn't work with it. So I run script sys.path[:0] = ['/<your-path>/chromium/src/tools/lldb'] and script import lldbinit on lldb, after CLion lldb debug session starts.
Use ASan build
where to get
Chromium (Chrome) can be built with ASan. You have to just configure and check.
Or, the builds are provided. Alesandro's blog is a nice source.
However, in the case of Mac, the build from the above page sometimes doesn't work. So it could be better to use a python script the Chrome team provides. The script sometimes downloads a build different from the latest, though I don't know why.
how to run on Mac (I'm a Mac user.)
- unzip the file
- run it
./chromium-134.0.6973.0-mac-asan/Chromium.app/Contents/MacOS/Chromium
Sometimes, you encounter the error like this.
malloc: nano zone abandoned due to inability to reserve vm space.
There is a case where setting MallocNanoZone env to 0 can solve the situation.
MallocNanoZone=0 ./chromium-134.0.6973.0-mac-asan/Chromium.app/Contents/MacOS/Chromium
diff from the latest stable
The version of ASan build is diff from the one of the latest stable release. So, when you research on recently added features like an experimental API, you should check the version carefully. Implementation of such features tends to change frequently.
Happy Hunting :)
Use Proxy
Run chromium with the following and it connects to local proxy.
--proxy-server="127.0.0.1:8080" --proxy-bypass-list="<-loopback>"
Use CodeQL
- It's nice to use codeQL. Please refer to here to begin: https://chromium.googlesource.com/chromium/src/+/refs/tags/126.0.6436.1/tools/codeql/README.md
- There seem to be a lot of files not fully analyzed in the official database. You can roughly check them by the below query. For example, its result includes many files under third_party/blink/renderer/core/paint.
import cpp
from File f
where
f.getBaseName().regexpMatch(".*cc") and
not exists(FunctionCall fc | fc.getFile() = f)
select f
Brave??
build
trouble-shooting
The official says...
$ npm install
$ npm run init
$ npm run build
But sometimes you encounter an error for npm install caused by @brave/leo, their design library(maybe?). You can bypass it by removing it at the moment and install after npm run init.
$ npm install
# if you have an error caused by @brave/leo here, uninstall it.
$ npm uninstall @brave/leo
$ npm run init
# add @brave/leo to package.json again after `npm run init` finishes.
# Then let's build.
$ npm run build
args
npm run build is essentially build/commands/scripts/commands.js. You can see its args there. For example, --is_asan enables ASan :)