Chromium Docs

Linux Eclipse Dev

Eclipse can be used on Linux (and probably Windows and Mac) as an IDE for developing Chromium. It‘s unpolished, but here’s what works:

  • Editing code works well (especially if you're used to it or Visual Studio).
  • Navigating around the code works well. There are multiple ways to do this (F3, control-click, outlines).
  • Building works fairly well and it does a decent job of parsing errors so that you can click and jump to the problem spot.
  • Debugging is hit & miss. You can set breakpoints and view variables. STL containers give it (and gdb) a bit of trouble. Also, the debugger can get into a bad state occasionally and eclipse will need to be restarted.
  • Refactoring seems to work in some instances, but be afraid of refactors that touch a lot of files.

Setup

Get & Configure Eclipse

Eclipse 4.6.1 (Neon) is known to work with Chromium for Linux.

  • Download the distribution appropriate for your OS. For example, for Linux 64-bit/Java 64-bit, use the Linux 64 bit package (Eclipse Packages Tab -> Linux 64 bit (link in bottom right)).
    • Tip: The packaged version of eclipse in distros may not work correctly with the latest CDT plugin (installed below). Best to get them all from the same source.
    • Googlers: The version installed on Goobuntu works fine. The UI will be much more responsive if you do not install the google3 plug-ins. Just uncheck all the boxes at first launch.
  • Unpack the distribution and edit the eclipse/eclipse.ini to increase the heap available to java. For instance:
    • Change -Xms40m to -Xms1024m (minimum heap) and -Xmx256m to -Xmx3072m (maximum heap).
    • Googlers: Edit ~/.eclipse/init.sh to add this:
export ECLIPSE_MEM_START="1024M"
export ECLIPSE_MEM_MAX="3072M"

The large heap size prevents out of memory errors if you include many Chrome subprojects that Eclipse is maintaining code indices for.

  • Turn off Hyperlink detection in the Eclipse preferences. (Window -> Preferences, search for "Hyperlinking, and uncheck “Enable on demand hyperlink style navigation”).

Pressing the control key on (for keyboard shortcuts such as copy/paste) can trigger the hyperlink detector. This occurs on the UI thread and can result in the reading of jar files on the Eclipse classpath, which can tie up the editor due to the size of the classpath in Chromium.

A short word about paths

Before you start setting up your work space - here are a few hints:

  • Don‘t put your checkout on a remote file system (e.g. NFS filer). It’s too slow both for building and for Eclipse.
  • Make sure there is no file system link in your source path because Ninja will resolve it for a faster build and Eclipse / GDB will get confused. (Note: This means that the source will possibly not reside in your user directory since it would require a link from filer to your local repository.)

Run Eclipse & Set your workspace

Run eclipse/eclipse in a way that your regular build environment (export CC, CXX, etc...) will be visible to the eclipse process.

Set the Workspace to be a directory on a local disk (e.g. /work/workspaces/chrome). Placing it on an NFS share is not recommended -- it‘s too slow and Eclipse will block on access. Don’t put the workspace in the same directory as your checkout.

Install the C Development Tools (“CDT”)

  1. From the Help menu, select Install New Software...
    1. Select the ‘Work with’ URL for the CDT If it's not there you can click Add... and add it. See https://eclipse.org/cdt/downloads.php for up to date versions, e.g. with CDT 8.7.0 for Eclipse Mars, use http://download.eclipse.org/tools/cdt/releases/8.7
    2. Googlers: We have a local mirror, but be sure you run prodaccess before trying to use it.
  2. Select & install the Main and Optional features.
  3. Restart Eclipse
  4. Go to Window > Open Perspective > Other... > C/C++ to switch to the C++ perspective (window layout).
  5. Right-click on the “Java” perspective in the top-right corner and select “Close” to remove it.

Create your project(s)

First, turn off automatic workspace refresh and automatic building, as Eclipse tries to do these too often and gets confused:

  1. Open Window > Preferences
  2. Search for “workspace”
  3. Turn off “Build automatically”
  4. Turn off “Refresh using native hooks or polling”
  5. Click “Apply”

Create a single Eclipse project for everything:

  1. From the File menu, select New > Project...
  2. Select C/C++ Project > Makefile Project with Existing Code
  3. Name the project the exact name of the directory: “src” (or “WebKit” if you mainly work in Blink and want a faster experience)
  4. Provide a path to the code, like /work/chromium/src (or /work/chromium/src/third_party/WebKit)
  5. Select toolchain: Linux GCC
  6. Click Finish.

Chromium uses C++14, so tell the indexer about it. Otherwise it will get confused about things like std::unique_ptr.

  1. Right-click on “src” and select “Properties...”
  2. Navigate to C/C++ General > Preprocess Include Paths, Macros etc. > Providers
  3. Select CDT GCC Built-in Compiler Settings
  4. In the text box entitled Command to get compiler specs append “-std=c++14” (leaving out the quotes)

Chromium has a huge amount of code, enough that Eclipse can take a very long time to perform operations like “go to definition” and “open resource”. You need to set it up to operate on a subset of the code.

In the Project Explorer on the left side:

  1. Right-click on “src” and select “Properties...”
  2. Open Resource > Resource Filters
  3. Click “Add Filter...”
  4. Add the following filter:
    • Include only
    • Files, all children (recursive)
    • Name matches .*\.(c|cc|cpp|h|mm|inl|idl|js|json|css|html|gyp|gypi|grd|grdp|gn|gni|mojom) regular expression
  5. Add another filter:
    • Exclude all
    • Folders
    • Name matches out_.*|\.git|web_tests regular expression
      • If you aren't working on WebKit, adding |blink will remove more files
  6. Click “Apply and Close”

Don't exclude the primary “out” directory, as it contains generated header files for things like string resources and Eclipse will miss a lot of symbols if you do.

Eclipse will refresh the workspace and start indexing your code. It won't find most header files, however. Give it more help finding them:

  1. Open Window > Preferences
  2. Search for “Indexer”
  3. Turn on “Allow heuristic resolution of includes”
  4. Select “Use active build configuration”
  5. Set Cache limits > Index database > Limit relative... to 20%
  6. Set Cache limits > Index database > Absolute limit to 256 MB
  7. Click “Apply and Close”

Now the indexer will find many more include files, regardless of which approach you take below.

Eclipse will still complain about unresolved includes or invalid declarations (semantic errors or code analysis errors in the Problems tab), which you can set eclipse to ignore:

  1. Right-click on “src” and select “Properties...”
    • Open C++ General > Code Analysis
    • Change the severity from Error to Warning for each of the settings that you want eclipse to ignore.

Optional: Manual header paths and symbols

You can manually tell Eclipse where to find header files, which will allow it to create the source code index before you do a real build.

  1. Right-click on “src” and select “Properties...”
    • Open C++ General > Paths and Symbols > Includes
    • Click “GNU C++”
    • Click “Add...”
    • Add /path/to/chromium/src
    • Check “Add to all configurations” and “Add to all languages”
  2. Repeat the above for:
    • /path/to/chromium/src/testing/gtest/include

You may also find it helpful to define some symbols.

  1. Add OS_LINUX:
    • Select the “Symbols” tab
    • Click “GNU C++”
    • Click “Add...”
    • Add name OS_LINUX with value 1
    • Click “Add to all configurations” and “Add to all languages”
  2. Repeat for ENABLE_EXTENSIONS 1
  3. Repeat for HAS_OUT_OF_PROC_TEST_RUNNER 1
  4. Click “OK”.
  5. Eclipse will ask if you want to rebuild the index. Click “Yes”.

Let the C++ indexer run. It will take a while (10s of minutes).

Optional: Building inside Eclipse

This allows Eclipse to automatically discover include directories and symbols. If you use gold or ninja (both recommended) you'll need to tell Eclipse about your path.

  1. echo $PATH from a shell and copy it to the clipboard
  2. Open Window > Preferences > C/C++ > Build > Environment
  3. Select “Replace native environment with specified one” (since gold and ninja must be at the start of your path)
  4. Click “Add...”
  5. For name, enter PATH
  6. For value, paste in your path with the ninja and gold directories.
  7. Click “OK”

To create a Make target:

  1. From the Window menu, select Show View > Make Target
  2. In the Make Target view, right-click on the project and select New...
  3. name the target (e.g. base_unittests)
  4. Unclick the Build Command: Use builder Settings and type whatever build command you would use to build this target (e.g. ninja -C out/Debug base_unittests).
  5. Return to the project properties page a under the C/C++ Build, change the Build Location/Build Directory to be /path/to/chromium/src
    1. In theory ${workspace_loc} should work, but it doesn't for me.
    2. If you put your workspace in /path/to/chromium, then ${workspace_loc:/src} will work too.
  6. Now in the Make Targets view, select the target and click the hammer icon (Build Make Target).

You should see the build proceeding in the Console View and errors will be parsed and appear in the Problems View. (Note that sometimes multi-line compiler errors only show up partially in the Problems view and you'll want to look at the full error in the Console).

(Eclipse 3.8 has a bug where the console scrolls too slowly if you're doing a fast build, e.g. with goma. To work around, go to Window > Preferences and search for “console”. Under C/C++ console, set “Limit console output” to 2147483647, the maximum value.)

Optional: Multiple build targets

If you want to build multiple different targets in Eclipse (chrome, unit_tests, etc.):

  1. Window > Show Toolbar (if you had it off)
  2. Turn on special toolbar menu item (hammer) or menu bar item (Project > Build configurations > Set Active > ...)
    1. Window > Customize Perspective... > “Command Groups Availability”
    2. Check “Build configuration”
  3. Add more Build targets
    1. Project > Properties > C/C++ Build > Manage Configurations
    2. Select “New...”
    3. Duplicate from current and give it a name like “Unit tests”.
    4. Change under “Behavior” > Build > the target to e.g. unit_tests.

You can also drag the toolbar to the bottom of your window to save vertical space.

Optional: Running inside eclipse

Running inside eclipse is fairly straightforward:

  1. Create a C/C++ Application:
    1. Run > Run configurations
    2. Double click on C/C++ Application
    3. Pick a name (e.g. shell)
    4. Point to C/C++ Application (e.g. src/out/Default/content_shell)
    5. Click Debug to run the program.

Optional: Debugging

  1. From the toolbar at the top, click the arrow next to the debug icon and select Debug Configurations...
  2. Select C/C++ Application and click the New Launch Configuration icon. This will create a new run/debug con figuration under the C/C++ Application header.
  3. Name it something useful (e.g. base_unittests).
  4. Under the Main Tab, enter the path to the executable (e.g. .../out/Debug/base_unittests)
  5. Select the Debugger Tab, select Debugger: gdb and unclick “Stop on startup in (main)” unless you want this.
  6. Set a breakpoint somewhere in your code and click the debug icon to start debugging.

Multi-process debugging

If you set breakpoints and your debugger session doesn't stop it is because both chrome and content_shell spawn sub-processes. To debug, you need to attach a debugger to one of those sub-processes.

Eclipse can attach automatically to forked processes (Run -> Debug configurations -> Debugger tab), but that doesn't seem to work well.

The overall idea is described here , but one way to accomplish this in eclipse is to run two Debug configurations:

  1. Create a C/C++ Application:
    1. Run > Debug configurations
    2. Double click on C/C++ Application
    3. Pick a name (e.g. shell)
    4. Point to C/C++ Application (e.g. src/out/Default/content_shell)
    5. In the arguments tab, add the following the to program arguments: --no-sandbox --renderer-startup-dialog test.html
    6. Click Debug to run the program.
    7. That will run the application and it will stop with a message like the following: Renderer (239930) paused waiting for debugger to attach. Send SIGUSR1 to unpause.
    8. 239930 is the number of the process running waiting for the signal.
  2. Create a C/C++ Attach to Application:
    1. Run > Debug configurations
    2. Double click on C/C++ Attach to Application
    3. Pick a name (e.g. shell proc)
    4. Click Debug to run the configuration.
    5. In the Select Processes dialog, pick the process that was spawned above (if you type content_shell it will filter by name)
    6. Click on Debugger console to access the gdb console.
    7. Send the original process a signal signal SIGUSR1
    8. That should unblock the original process and you should now be able to set breakpoints.

Optional: Accurate symbol information

If setup properly, Eclipse can do a great job of semantic navigation of C++ code (showing type hierarchies, finding all references to a particular method even when other classes have methods of the same name, etc.). But doing this well requires the Eclipse knows correct include paths and pre-processor definitions. After fighting with with a number of approaches, I've found the below to work best for me.

  1. From a shell in your src directory, run gn gen --ide=eclipse out/Debug/ (replacing Debug with the output directory you normally use when building).
    1. This generates /out/Debug/eclipse-cdt-settings.xml which is used below.
    2. This creates a single list of include directories and preprocessor definitions to be used for all source files, and so is a little inaccurate. Here are some tips for compensating for the limitations:
      1. If you care about blink, move ‘third_party/WebKit/Source’ to the top of the list to better resolve ambiguous include paths (eg. config.h).
  2. Import paths and symbols
    1. Right click on the project and select Properties > C/C++ General > Paths and Symbols
    2. Click Restore Defaults to clear any old settings
    3. Click Import Settings... > Browse... and select <project root>/out/Debug/eclipse-cdt-settings.xml
    4. Click the Finish button. The entire preferences dialog should go away.
    5. Right click on the project and select Index > Rebuild

Alternative: Per-file accurate include/pre-processor information

Instead of generating a fixed list of include paths and pre-processor definitions for a project (above), it is also possible to have Eclipse determine the correct setting on a file-by-file basis using a built output parser. I (rbyers) used this successfully for a long time, but it doesn't seem much better in practice than the simpler (and less bug-prone) approach above.

  1. Install the latest version of Eclipse IDE for C/C++ developers (Juno SR1 at the time of this writing)
  2. Setup build to generate a build log that includes the g++ command lines for the files you want to index:
    1. Project Properties -> C/C++ Build
      1. Uncheck “Use default build command”
      2. Enter your build command, eg: ninja -v
        1. Note that for better performance, you can use a command that doesn‘t actually builds, just prints the commands that would be run. For ninja/make this means adding -n. This only prints the compile commands for changed files (so be sure to move your existing out directory out of the way temporarily to force a full “build”). ninja also supports “-t commands” which will print all build commands for the specified target and runs even faster as it doesn’t have to check file timestamps.
      3. Build directory: your build path including out/Debug
        1. Note that for the relative paths to be parsed correctly you can‘t use ninja’s -C <dir> to change directories as you might from the command line.
      4. Build: potentially change all to the target you want to analyze, eg. chrome
      5. Deselect ‘clean’
    2. If you're using Ninja, you need to teach eclipse to ignore the prefix it adds (eg. [10/1234] to each line in build output):
      1. Project properties -> C/C++ General -> Preprocessor includes
      2. Providers -> CDT GCC Build Output Parser -> Compiler command pattern
      3. (\[.*\] )?((gcc)|([gc]\+\+)|(clang(\+\+)?))
      4. Note that there appears to be a bug with “Share setting entries between projects” - it will keep resetting to off. I suggest using per-project settings and using the “folder” as the container to keep discovered entries (“file” may work as well).
    3. Eclipse / GTK has bugs where lots of output to the build console can slow down the UI dramatically and cause it to hang (basically spends all it's time trying to position the cursor correctly in the build console window). To avoid this, close the console window and disable automatically opening it on build:
      1. Preferences->C/C++->Build->Console -> Uncheck “Open console when building”
      2. note you can still see the build log in <workspace>/.metadata/.plugins/org.eclipse.cdt.ui
  3. Now build the project (select project, click on hammer). If all went well:
    1. Right click on a cpp file -> properties -> C/C++ general -> Preprocessor includes -> GNU C++ -> CDT GCC Build output Parser
    2. You will be able to expand and see all the include paths and pre-processor definitions used for this file
  4. Rebuild index (right-click on project, index, rebuild). If all went well:
    1. Open a CPP file and look at problems windows
    2. Should be no (or very few) errors
    3. Should be able to hit F3 on most symbols and jump to their definitioin
    4. CDT has some issues with complex C++ syntax like templates (eg. PassOwnPtr functions)
    5. See this page for more information.

Optional: static code and style guide analysis using cpplint.py

  1. From the toolbar at the top, click the Project -> Properties and go to C/C++Build.
    1. Click on the right side of the pop up windows, “Manage Configurations...”, then on New, and give it a name, f.i. “Lint current file”, and close the small window, then select it in the Configuration drop down list.
    2. Under Builder settings tab, unclick “Use default build command” and type as build command the full path to your depot_tools/cpplint.py
    3. Under behaviour tab, unselect Clean, select Build(incremental build) and in Make build target, add --verbose=0 ${selected_resource_loc}
    4. Go back to the left side of the current window, and to C/C++Build -> Settings, and click on error parsers tab, make sure CDT GNU C/C++ Error Parser, CDT pushd/popd CWD Locator are set, then click Apply and OK.
  2. Select a file and click on the hammer icon drop down triangle next to it, and make sure the build configuration is selected “Lint current file”, then click on the hammer.
  3. Note: If you get the cpplint.py help output, make sure you have selected a file, by clicking inside the editor window or on its tab header, and make sure the editor is not maximized inside Eclipse, i.e. you should see more subwindows around.

Additional tips

  1. Mozilla's Eclipse CDT guide is helpful:
  2. For improved performance, I use medium-granularity projects (eg. one for WebKit/Source) instead of putting all of ‘src/’ in one project.
  3. Running content_shell as opposed to all of chrome is a lot faster/smaller.