Introduction

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:

• It works well as an editor (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 3.6 (Helios) and 3.7 (Indigo) are known to work with Chromium for Linux.

1. Download the distribution appropriate for your OS. For example, for Linux 64bit/Java 64bit, use the Linux 64 bit package from http://www.eclipse.org/downloads/ (Eclipse Packages Tab -> Linux 64 bit (link in bottom right)).
• Tip: The packaged version of eclipse in distros (e.g. Ubuntu Karmic) may not work correctly with the latest CDT plugin (installed below). Best to get them all from the same source.
2. 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.

Googlers: The Eclipse UI will be much more responsive if you do not install the usual set of Google-supplied plug-ins. Just uncheck all the boxes at first launch.

A short word about paths

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

• Make sure there is no 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.)
• You should start Eclipse from the source root. You might want to add an icon to your task bar as launcher. It should point to a shell script which will set the current path to your source base, and then start Eclipse. The result would probably look like this:

~/.bashrc
cd /usr/local/google/chromium/src
export PATH=/home/skuhne/depot_tools:/usr/local/google/goma/goma:/opt/eclipse:/usr/local/symlinks:/usr/local/scripts:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
/opt/eclipse/eclipse -vm /usr/bin/java

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 your checkout directory (e.g. /work/chromium), or place it on another disk for a small performance boost. Placing it on an NFS share is not recommended.

Install the C Development Tools

1. From the Help menu, select Install New Software...
1. Select the URL for the CDT, http://download.eclipse.org/tools/cdt/releases/helios
1. If it's not there you can click Add... and add it.
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 > Show Perspective > Other... > C/C++ to switch to the C++ perspective (window layout).

Create your project(s)

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. There are two ways to do this: load everything and blacklist files (easier to set up, control-click works everywhere, but includes more files than strictly necessary) or load only the subprojects you need (harder to set up, control-click might not work everywhere, but UI performs better).

Option 1: One big project

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"
4. Provide a path to the code, like /work/chromium/src
5. Select toolchain: Linux GCC
6. Click Finish.

Eclipse will try to build the project with make, and it will fail. That's OK - Eclipse's C++ indexer is independent of the makefile-based builds. You should also turn off automatic workspace refresh and automatic building, as Eclipse tries to do these too often and gets confused:

1. From the Project menu, turn off "Build automatically", then
2. Open Window > Preferences
3. Search for "workspace"
4. Eclipse 3.6: Turn off "automatic refresh"
5. Eclipse 3.7: Turn off "Refresh using native hooks or polling"

Next, we need to cut down the number of files Eclipse tries to process. In the Project Explorer on the left side:

1. Right-click on "src" and select "Properties..."
2. Open Resources > Resource Filters
3. Add the following inclusion filter:
1. Files, all children, name matches, regular expression ".*\.(c|cc|cpp|h|mm|inl|idl|js|css|html|gyp|gypi|grd)"
4. Add the following exclusion filter:
1. Folders, all children, name matches, regular expression "out\..*|\.git|\.svn|LayoutTests"

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

We also need to give Eclipse a hint about where our header files live:

1. Right-click on "src" and select "Properties..."
2. Open C++ General > Paths and Symbols
3. Select the "Includes" tab
4. Add /path/to/chromium/src to all languages/configurations (it will ask)
5. Add /path/to/chromium/src/testing/gtest/include as well.
6. Click "OK".
7. Eclipse will ask if you want to rebuild the index. Click "Yes".

In theory Eclipse will discover paths and symbols during your first build, but the above lets you get the indexer going without building.

Finally, right-click on the "src" project, hit refresh, then let the C++ indexer run. It will take a while (10s of minutes).

Option 2: Small linked projects

You'll create projects for the Chromium components you work on. Here's how to create a project for 'base'

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: "base"
4. Provide a path to the code, like /work/chromium/src/base
5. Select toolchain: Linux GCC
6. Click Finish.

Eclipse will try to build the project with make, and it will fail. That's OK - Eclipse's C++ indexer is independent of the makefile-based builds. Turn off automatic building:

1. From the Project menu, turn off "Build automatically"

Eclipse will run the Code indexer automatically, and when it's finished, ctrl-clicking on many types and variables will work to jump to the declaration. Also ctrl-shift-R will bring up the file quick-find box that will auto-complete (and supports wildcards). ctrl-shift-T works similarly with types and classes.

If you want references from files in one package to files in another to work for navigation (ctrl-click), you'll want to add references between projects. For example, "chrome" should probably reference all other projects you've created. To do this,

1. Return to the project properties page
2. Select Project References
3. Check each project this one should reference.

The proper dependency list is hard to discover. You'll get pretty far if you make "chrome" depend on everything you add, and then also ensure everything you add depends on "base".

Building

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. Paste in your path with the ninja and gold directories.

To create a Make target: To create a Make target:

1. From the Window menu, select Show Views->Make Targets
2. In the Make Targets 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. "make -j BUILDTYPE=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).

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 configuration 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/mi and unclick "Stop on startup in (main)" unless you want this.
6. Under the source tab, remove all source look ups and add an Absolute File Path (you won't enter a path).
7. Set a breakpoint somewhere in your code and click the debug icon to start debugging.