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.

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.

In the text box entitled Command to get compiler specs append “-std=c++11” (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.

If you aren't working on WebKit, adding |WebKit will remove more files

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:

Open Window > Preferences

Search for “Indexer”

Turn on “Allow heuristic resolution of includes”

Select “Use active build configuration”

Set Cache limits > Index database > Limit relative... to 20%

Set Cache limits > Index database > Absolute limit to 256 MB

Click “Apply and Close”

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

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.

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”

Repeat the above for:

/path/to/chromium/src/testing/gtest/include

You may also find it helpful to define some symbols.

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”

Repeat for ENABLE_EXTENSIONS 1

Repeat for HAS_OUT_OF_PROC_TEST_RUNNER 1

Click “OK”.

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.

echo $PATH from a shell and copy it to the clipboard

Open Window > Preferences > C/C++ > Build > Environment

Select “Replace native environment with specified one” (since gold and ninja must be at the start of your path)

Click “Add...”

For name, enter PATH

For value, paste in your path with the ninja and gold directories.

Click “OK”

To create a Make target:

From the Window menu, select Show View > Make Target

In the Make Target view, right-click on the project and select New...

name the target (e.g. base_unittests)

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).

Return to the project properties page a under the C/C++ Build, change the Build Location/Build Directory to be /path/to/chromium/src

In theory ${workspace_loc} should work, but it doesn't for me.

If you put your workspace in /path/to/chromium, then ${workspace_loc:/src} will work too.

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.):

Set a breakpoint somewhere in your code and click the debug icon to start debugging.

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.

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).

This generates /out/Debug/eclipse-cdt-settings.xml which is used below.

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:

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).

Import paths and symbols

Right click on the project and select Properties > C/C++ General > Paths and Symbols

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.

Install the latest version of Eclipse IDE for C/C++ developers (Juno SR1 at the time of this writing)

Setup build to generate a build log that includes the g++ command lines for the files you want to index:

Project Properties -> C/C++ Build

Uncheck “Use default build command”

Enter your build command, eg: ninja -v

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.

Build directory: your build path including out/Debug

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.

Build: potentially change all to the target you want to analyze, eg. chrome

Deselect ‘clean’

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):

Project properties -> C/C++ General -> Preprocessor includes

Providers -> CDT GCC Build Output Parser -> Compiler command pattern

(\[.*\] )?((gcc)|([gc]\+\+)|(clang(\+\+)?))

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).

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:

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

From the toolbar at the top, click the Project -> Properties and go to C/C++Build.

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.

Under Builder settings tab, unclick “Use default build command” and type as build command the full path to your depot_tools/cpplint.py

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.

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.

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.