Life of A Chromium Developer
Life of A Chromium Developer
tl;dr
Summary in command line form
Subversion Workflow
Get into work...
$gclientsync
Try server reports your patch failed because you forgot a file...
$svnaddforgotten_file.cc $gclchangemy_new_feature
Git Workflow
Get into work...
$gitpull--rebase&&gclientsync
Try server reports your patch failed because you forgot a file...
$gitaddforgotten_file.cc $gitcommit
Commit Workflow
LGTM! But hold before committing let's check the tree... Red? Wait until tree goes green. Green? Before committing make sure... ...your most recent try server attempt has passed ...you're in IRC or generally available on IM ...you're not leaving to catch a bus and will be at your desk Good? OK let's commit!
(svn)$gclcommitmy_new_feature(git)$gitcldcommit
Handy Links
Documentation dev.chromium.org Bugs bugs.chromium.org or crbug.com Source src.chromium.org Buildbots build.chromium.org Code Reviews codereview.chromium.org IRC #chromium on freenode.net Mailing list [email protected]
Overview
Lots of information ahead!
Overview
How does one get involved in Chromium development? Usually, you do some variant on the following work flow: 1.Get a machine that can build Chromium Get the code Modify and build the code Test code Upload and review code Commit patch and waiting game
1. Development Machine
Because it takes a special kind of machine to build Chromium
Development Machine
Chromium is a large project! ~5000 build objects ~100 library objects 1 massive linked executable (~1.3GB on Linux Debug) Why a massive executable? Easy to update! Faster to load! Hard to link :( Even if you're building a 32-bit executable, you need a 64-bit machine since linking requires >4GB virtual memory.
Development Machine
General requirements: Lots of cores Lots of RAM Second hard drive for source code and building Google Employees: Request machines and software from http://goto/stuff Apple software can be found at http://goto/apple Windows: Z600 Win7 64-bit Visual Studio 2008 Follow Windows instructions
Development Machine
Mac OS X: Mac Pro Snow Leopard Xcode 3.2 or newer Follow Mac OS X instructions Linux: Z600 gold 64-bit Ubuntu Lucid or newer Follow Linux instructions
The first command creates a subdirectory "depot_tools" with a checkout of Depot Tools. The second command places the utilities in your path. Note because it uses `pwd`, it should be invoked in the directory above "depot_tools."
Creating a .gclient
The .gclient file specifies where to get the core Chromium code. This command (all on one line) will create a default .gclient: gclientconfig http://src.chromium.org/svn/trunk/src http://chromium-status.appspot.com/lkgr Read get the code setup for most up-to-date instructions.
What this does: Gets the "lkgr" from safesync_url Creates a subdirectory named src if it doesn't exist Does an svn checkout of the url, at the "lkgr". lkgr = "Last Known Good Revision", the last revision to pass all the automated build tests.
Parallel build across ## machines or processors (do this! will take hours otherwise)
$make-j##chrome
Builds to src/out/ directory, e.g. src/out/Debug/chrome For clean build, delete out/ directory (rarely needed)
Can also build from Xcode. Builds to src/xcodebuild/ directory, e.g. src/xcodebuild/Debug/Chromium.app/Chromium Other targets are stored in .xcodeproj files in relevant folders
$devenv.com/buildDebugchrome.sln/projectchrome.vcproj
Random C++ errors from a fresh copy of source Check waterfall to see if the tree is red. If so, try updating the code when the tree is green and build again. Confusing link errors on a checkout that used to work Try deleting your output directory to force a clean build. If using Visual Studio, make sure you quit before syncing.
Debugging
Debugger needs to attach to browser and renderer process. But by default, only the browser process is attached... To attach renderer process, either: Run with --single-process flag (easier, but unsupported and known to be buggy) Manually attach renderer process to debugger (trickier; instructions depend on debugger) See platform-dependent pages for more details: linux, mac, win
4. Testing
Testing Overview
Chromium has a lot of tests! Roughly broken down into following categories: Unit tests UI tests Performance tests Layout tests We also run some tests through Valgrind to catch memory and threading bugs. In general, developers submit patches to the try server to build and fully test changes on all platforms.
Testing Overview
Most tests are written in C++ using gtest and are hosted in Chromium's repository. Layout tests are written in HTML/CSS/Javascript and are hosted in WebKit's repository. It's typically enough to build the tests for the code you're modifying and run them as opposed to the entire test suite. Ask your team mates which tests you should build and run!
Try Server
The try server is the easiest way to test your change on all platforms. Highly recommended! The try server takes your change, applies it to a clean checkout of the source, compiles every possible target, then runs most (not all!) tests for each platform, and emails you the results. To submit your change to the try server: Subversion: gcltry[changelistname] Git: checkout branch you want to try and run gittry Requires commit access! You may also email [email protected] for try server access
Try Server
However the try server doesn't work for all types of changes: Applying SVN properties Binary content Patches containing CRLF characters It still works for the vast majority of cases, so use it! It's bad form to commit a change that breaks something because you didn't feel like waiting for try server results. Read try server usage for more information.
Flakiness
Sometimes the tests fail for unrelated reasons. It usually happens for larger tests, which have a lot of reasons to fail: there might be some problem on the machine running tests the browser may crash randomly there may be a race condition in the browser or test Flaky failures are bad. We shouldn't need to wonder whether a given test failure is real or flaky. A test failure should always mean broken code.
Fighting flakiness
File bugs for intermittent test failures. Use Tests-Flaky bug label. Write solid test code. o Would you use a Sleep in browser code to "wait" for events? Then don't use it in tests. o Most test infrastructure helpers should be synchronous. For example, when NavigateToURL returns, the navigation is finished. Write smaller tests. o Start with a unit test. Only if needed, use a UI test. o In-process browser tests are good compromise: they launch a full browser, but you can access all the internals in the same process.
Uploading code
Once you're happy with your change and tested it, you're ready for review! If you have never uploaded code before, go to Rietveld and log in with your chromium.org account or a Google account of your choosing. Upload your change using the following: Subversion: gclupload[changelistname] Git: checkout appropriate branch and run gitclupload If prompted, enter the same credentials you used to log into Rietveld above.
Uploading code
Write a meaningful and descriptive changelist description and fill in the BUG= and TEST= fields. If a bug doesn't exist, go ahead and file one just for your change. View your uploaded change in Rietveld (URL should be printed to console after running gclupload/gitclupload).
Finding reviewers
Best to ask your team mates or inspect commit logs: svnlog/annotate[path] gitlog/annotate[path] Use "annotate" links on files at http://src.chromium.org/ If you're feeling crafty you can also use one-liners: gitlog--format=format:"%an"[path]|\ sort|uniq-c|sort-n It's your responsibility to find qualified reviewers for your change!
Tips
Follow the style guide!!!
Write a descriptive, easy to understand, change description. Always try to include tests when possible. Keep your changes small. It's much easier for reviewers to understand and review your change. Split up unrelated changes. Before attempting a big change, email your reviewers and discuss to make sure your approach is good. Read contributing code for more information.
Guidelines
Do the right thing for the project, not the fastest thing to get code checked in. If you touch code you're not familiar with (e.g. IPC, TabContents, testing infrastructure), add people who know that code as reviewers, even if the change seems simple. Similarly, if you're asked to review code you're not familiar with, add better reviewers, even if the change seems simple. Never commit a CL if there are unresolved comments from one of the reviewers, even if others said "LGTM".
6. Committing code
Committing code
If you don't have commit access, one of your reviewers should land your change for you. If you do have commit access, first check the tree... Red? Wait until tree goes green. Green? Before committing make sure... ...your most recent try server attempt has passed ...you're in IRC or generally available on IM ...you're not leaving to eat lunch or catch a bus
Committing code
All good? OK let's commit! Subversion: gclcommitmy_new_feature Git: checkout appropriate branch and run gitcldcommit Make sure to keep watching the tree to make sure your change successfully builds without breaking anything.
Troubleshooting
In open source, no one can hear you scream
THE END
Start writing code!