Chromium Developer Documentation

Google Chrome is built with open source code from Chromium.

Except as otherwise noted, the content of this page is licensed under a Creative Commons Attribution 2.5 license, and examples are licensed under the BSD License.

Getting Started

x
If you're serious about learning how Chromium works, this is the page for you. You'll get the Chromium code and build it. Then you'll use the Visual Studio 2005 debugger to see how the browser works — in particular, how it responds to common user actions.

Note: This page is aimed at developers and testers who have Windows and want to inspect running code. If you're not ready to set up a build environment, you can read the documentation. If you don't have Windows, check out the build instructions for Mac and Linux.

Get the software you need

This section tells you how to set up your Windows build environment. If you have problems or want further details, see Build Instructions (Windows).

Prerequisite software

First, your computer must have the following software installed:
  • Windows XP (SP2 or later) or Windows Vista
  • Microsoft Visual Studio 2005 (8.0)

Additional (free) downloads

Once Visual Studio is installed, you need to download and install some more software.

  1. Download and install Microsoft Visual Studio 2005 Service Pack 1.
    Depending on your computer, installation can take about an hour, and you might need to reboot.

  2. Download and install the Microsoft Windows SDK.
    You might need to reboot. You can save space by not installing the documentation and code samples.

    Note:
    Although the SDK says it's for Vista, it works on both XP and Vista. If you already have the Microsoft 2008 SDK, you don't need to install a new one.

  3. Integrate the SDK with Visual Studio:

    Start > All Programs > Microsoft Windows SDK > Visual Studio Registration > Integrate Windows SDK with Visual Studio 2005


  4. Get the Chromium depot_tools.

Chromium code

  1. Check out the source code using either the bootstrap tarball or a direct svn checkout.

  2. Update it to the latest version.

Build and launch Chromium

Once you have all the software and code, you can build Chromium and launch it in debug mode.
  1. Launch Visual Studio.

  2. Choose File > Open Project/Solution..., go to the src\chrome directory (under c:\chromiumtrunk or wherever you put the Chromium files), and open the file chrome.sln.

  3. In the Solution Explorer, go to the App directory, right-click chrome_exe, and choose Set as StartUp Project.

  4. Set the user profile used by your build of Chromium:

    1. Right-click chrome_exe, and choose Properties.

    2. In the left column, choose Configuration Properties > Debugging.

    3. In the right column, change the value of Command Arguments to something like this:

      --user-data-dir=c:\tmp\DebugProfile


      Click Ok. Chromium creates the specified profile directory (c:\tmp\DebugProfile in the previous example) if the directory doesn't already exist.

      Note:
      If you don't set the profile, then if you try to launch Chromium when Google Chrome or Chromium is already running, a new window comes up in the already running browser. This behavior ensures exclusive access to the user profile, but it means that you can't debug your version of Chromium!

      Warning: If the latest build of Chromium has a new profile format, Google Chrome and older versions of Chromium might not be able to read that format. Unless you set the profile, you could lose your Google Chrome profile data.

  5. Press F5, which builds the chrome_exe solution and launches Chromium in debug mode. When you're asked whether to build out-of-date projects, choose Yes.

  6. Building takes 15-40 minutes. When the build completes, a browser window appears on your desktop.

    If the build fails or a new browser window does not appear, go to Build Instructions (Windows) for help.

Take the tour

The easiest way to start getting familiar with Chromium is to follow what it does in response to user actions.

User action: Entering URLs

You can easily find the code that's executed when the user enters a URL at the address bar.
  1. Open (Ctrl+O) the file src\chrome\browser\autocomplete\autocomplete_edit.cc.

  2. Place a breakpoint at the AutocompleteEdit::AcceptInput method.
    The AcceptInput method is called whenever the user enters a URL.

  3. Go to your Chromium browser window, type in a web address such as google.com, and press Return. The UI should freeze when the breakpoint is hit.

    Note: If the UI doesn't freeze, then you probably didn't set the profile used by your build of Chromium. Please do so (see Step 4 of Build and launch Chromium) or close all Google Chrome and Chromium windows on your desktop. Then go back to Visual Studio and press F5 again to run the browser within the debugger.

  4. Take a look at the call stack (Debug > Windows > Call Stack). It shows you the path that the event took from the window system to the Chromium code that starts processing the user-entered URL.

  5. Step through the code (F10), looking at the Locals tab to see the values of variables such as url, until you reach the line that invokes the OpenURL method.

  6. Look at the code and the Locals tab to see the values of the arguments to OpenURL. You can see that the URL has been fleshed out (from "google.com" to "http://google.com/", for example), the transition is set to 1 (PageTransition::LINK), and so on. Because you entered the URL by typing, rather than clicking an item in the drop-down, the next-to-last variable is set to AutocompletePopup::kNoMatch.

  7. To find out more about page transitions, select the word PageTransition, right-click, and choose Go To Definition. You'll see the definition of PageTransition in src\chrome\common\page_transition_types.h. As the source code and comments show, page transitions describe what triggered the page visit. Transitions include clicks on links, typed-in URLs (like the one in this case), form submissions, reloads, and more.

  8. Go back to the autocomplete_edit.cc tab, and step into the OpenURL method (F11). When you find yourself looking at code that's too low level, step out (Shift-F11) and step again (F11). Continue stepping through the code to follow what happens as the page is loaded.

  9. When you're ready to go on, press F5 to continue executing the browser.

  10. Optional: Try other ways of entering a URL. For example:
  • Start typing in a URL, but instead of pressing Enter, use the mouse to click a URL from the drop-down. Compare the call stack and variable values to the ones that you saw previously.

  • Enter one character or word -- one you haven't used before, such as x -- into the URL field. Note that the variable alternative_nav_url soon has a value, such as http://x/. Also note that the transition is 5, indicating that the URL has been generated (PageTransition::GENERATED).

  • Drag a URL into the browser. Note that the call stack is different, since AcceptInput is called by a drop event handler.
For more information, see the Navigating from the URL bar section of Getting Around the Chromium Source Code.

User action: Clicking links

The browser's response to clicks on links is a bit complicated, due to Chromium's multi-process, multi-threaded architecture.
  1. Open (Ctrl+O) the file src\chrome\browser\browser.cc.

  2. Place a breakpoint at the Browser::NavigationStateChanged method.

  3. Click a link in any page. You'll hit the breakpoint.

  4. Look at the call stack. You'll see method calls related to message passing between threads in the same process (such as MessageLoop::QueueOrRunTask; see Threading) and between processes (such as RenderViewHost::OnMessageReceived; see Multi-process Architecture and Inter-process Communication).

  5. Press F5 to start executing again. You'll immediately hit another breakpoint, as the tab redraws itself.

Feature: Browser commands

Often, the user can request an operation in more than one way. For example, the user can reload a page by pressing the Reload button or by pressing F5. To avoid duplicating code, many operations are handled by common code, in the form of commands.
  1. Open (Ctrl+O) the file src\chrome\browser\browser_commands.cc.

  2. Place a breakpoint at the Browser::ExecuteCommand method.

  3. In the browser, press the star button to the left of the address bar. You'll hit the breakpoint.

  4. Look at the call stack. It includes a chain of mouse-release event handlers, including BaseButton::OnMouseReleased.

  5. In the Locals tab, look at the value of id. It identifies the operation that the user requested.

  6. Step into the case statement (IDC_STAR) that handles this operation. Note that the action is being recorded into user metrics, and then the code to perform the action is called.

  7. Select IDC_STAR, right-click, and choose Go To Definition. You'll see its definition (and those of many other commands) in chrome_dll_resource.h.

  8. Press F5 to continue executing the browser.

  9. Press Ctrl+D, the keyboard alternative for star. You'll hit the breakpoint again.

  10. Look at the call stack. This time, it contains mostly calls related to inter-process and thread-to-thread communication. The only keyboard event handler that's visible in the call stack is WebContents::HandleKeyboardEvent.

  11. Note that the value of id is the same as before, so the same code will be executed as when you used the star button.

  12. Optional: Look at other browser commands, including some menu commands. For example:
  • Ctrl+T and the New tab menu item
  • Reload button and F5

What next?

Now that you've built Chromium and stepped through some of its code, here are some suggestions for what you might want to do now.

  Sign in   Home   Sitemap   Terms   Report Abuse   Print  |  Powered by Google Sites