Eclipse CDT

  • Revision slug: Eclipse_CDT
  • Revision title: Eclipse CDT
  • Revision id: 232689
  • Created:
  • Creator: Jonathan_Watt
  • Is current revision? No
  • Comment 50 words added

Revision Content

Introduction

Please contact Jonathan Watt before editing this page. In fact the instructions on this page are not working yet, so probably you shouldn't even bother reading it until this notice is removed. The old text on this page was years out of date and no longer correct/working. Jonathan is in the middle of a complete rewrite, but it's taking a fair bit of investigative work and coordination with the Eclipse CDT team to get various bugs worked and to get indexing working well with the Mozilla source.

Eclipse CDT (C/C++ Development Tools) is an open-source IDE for C and C++ development. It supports complex projects that have their own build system, like Mozilla. If you want to use an IDE for Mozilla C++ development with advanced code assistance (inheritance/call graph explorer, jump to definition, refactoring, autocomplete, syntax highlighting, etc.), then Eclipse CDT might be for you.

System requirements

Eclipse provides many features that you'll find yourself unable to live without once you start using them, but it does come with some fairly hefty system requirements. In order to index the Mozilla source it requires 2-3 GB of free RAM. If you don't already have 16 GB of RAM installed, Eclipse provides you with the perfect excuse to upgrade. :-)

Setup time

It will probably take you about an hour to set up Eclipse CDT for the first time and get its code assistance working well. (That assumes you already have a copy of the Mozilla source, and that it has been built and has a pre-existing object directory.)

Code assistance

Out of the box, Eclipse can provide some code assistance for the Mozilla source, but it will be fairly incomplete and often just plain broken. If you set up Eclipse as detailed below it will do a much, much better job.

Important background

To help you make sense of the instructions that follow (and so that you can modify them to meet your own needs if necessary) this section provides some background on what IDEs need in order to provide advanced code assistance, and what Eclipse CDT needs in particular.

To be able to provide really good code assistance for a project's source code, IDEs like Eclipse need to carry out a thorough static analysis of the project's source files to build up a picture of the code. (What Eclipse is trying to do when it "indexes" the source.) Static analysis involves parsing the source files, so naturally it can only produce good results if it has a sensible set of preprocessor defines, include paths and pre-include files for each source file. Since Eclipse doesn't initially have any of this information, the code assistance that it's able to provide out of the box is pretty broken.

For projects the size and complexity of Mozilla, it's impractical to manually configuring Eclipse with a valid set of defines and include paths for each different part of the source code. Happily, Eclipse makes manual configuration unnecessary. Like some other IDEs, for projects like Mozilla that have their own build system, Eclipse provides a tool that can collect the options that are passed to the compiler for each file that's compiled during an actual build. This process is sometimes called "build option discovery" or "compiler option discovery".

The way that Eclipse CDT does build option discovery is to scan the console output from a real build looking for lines where a compiler was invoked. For each line that invoked a compiler, it tries to figure out which source file was being built and what its include paths were. If relative paths are used to specify the source file or any of its include paths (common in Mozilla), and if you fail to take steps to make sure the build output specifies which directory the compiler is invoked from, this will not be possible. If Eclipse can successfully identify which source file was being compiled, then it can associate with that file the resolvable include paths, preprocessor defines and pre-include files that were passed to the compiler.

Note the requirements that this method of build option discovery imposes on us. First, Eclipse needs build console output for a complete build so that it can find the compiler options for as many source files as possible. The build must be explicitly instructed to output information that allows the directory that the compiler is being invoked from to be identified (i.e. 'make' must be instructed to output "Entering directory..."/"Leaving directory..." lines). Finally, the build must not be parallelized (since that would result in interleaving of build output from different directories, breaking resolution of relative paths by interleaving the "Entering directory..."/"Leaving directory..." lines) and the build must not be silenced/quietened.

Conversely, note this very carefully: if you configure Eclipse to invoke a build process that is parallelized, silenced, or that fails to identify the directory that the compiler is being run from, then it will mess up the compiler options that Eclipse associates with your files, and that in turn will significantly degrade the quality of the code assistance that Eclipse will provide after it next re-indexes the code.

Unfortunately, these requirements aren't a very good fit with the typical Mozilla developer's wish to minimize build times, which implies parallelized, silenced builds.

The consequences of the above observations are this:

  • It is strongly recommended that you invoke your normal (re)builds from the command line, externally of Eclipse.
  • Below we will configure Eclipse's build step so that you use it only occasionally to manually trigger a special "build" (actually a script that fakes a build) purely for the purposes of setting/updating the compiler options Eclipse associates with each source file.

(Not using Eclipse to build does lose you some minor benefits that Eclipse has to offer, but these are worth sacrificing for much better code assistance. See the "Build" section below if you're interested in what you lose. If you're interested in future improvements to Eclipse that would allow parallel builds to be run from inside Eclipse, see the "Isn't there a better method of build option discovery?" below.)

Installing Eclipse

These instructions currently direct you to install Eclipse Juno, a developer build of Eclipse. ("Juno" is the code name of the next version of Eclipse, coincidentally scheduled for released on June 27, 2012.) Using Juno is important because it contains improvements and fixes that allow it to provide much better code assistance for the Mozilla source.

Download "Eclipse IDE for C/C++ Developers" from the Eclipse Developer builds page, extract the file, and put the resulting directory somewhere sensible. (Consider renaming the Eclipse executable to "Eclipse-Juno-nightly" to remind you what version it is later.)

Don't start Eclipse yet.

Increasing memory limits

When Eclipse's indexer tries to process the Mozilla source, Eclipse will need considerably more memory than it allows itself out of the box. You should increase its memory limits using the eclipse.ini in your installation directory (or in Eclipse.app/Contents/MacOS on Mac). Set something like -Xms1G -Xmx3G -XX:MaxPermSize=1G (initial heap space of 1 GB, max heap space of 3 GB, max perm-gen space of 1 GB).

If you fail to increase these limits then you will find that Eclipse will tend to hang when you try to index or work with the Mozilla source.

Initial workspace preferences

For future reference, note that the workspace preferences are a separate thing to the project properties.

When you open Eclipse, it will ask you to "Select a workspace" (a directory where Eclipse will store files that it generates during indexing, etc.). It's recommended that you have a separate workspace for each Mozilla source tree, and that you choose a directory outside the Mozilla source. Something like $HOME/eclipse-workspaces/mozilla-tree-1, for example. After selecting an appropriate directory, click OK. Close the "Welcome" tab.

Before you proceed further, check that your changes to the memory limits have taken effect and are present in Eclipse/Help > About Eclipse > Installation Details > Configuration.

Whenever you create a new workspace for a Mozilla source tree, you should be sure to turn off the following two settings in the workspace preferences (Window > Preferences, or Eclipse > Preferences) before creating a project in that workspace:

  • in "General > Workspace", disable "Build automatically"
  • in "C/C++ > Indexer", disable "Automatically update the index"

Turning off automatic indexing prevents the CPU intensive indexer from running at various stages in the steps below before we're ready.

Eclipse CDT will format C/C++ code that you add as you type. However, it's default formats are not a good match to Mozilla's style rules. Download this first pass at an Eclipse formatter configuration for Mozilla C/C++ coding style, and install it by opening the workspace preferences, selecting "C/C++ > Code Style > Formatter", and then using the "Import" button to import that file. The "Active profile" field should then automatically change to "Mozilla". Depending on the area of the code that you work on, you may need to tweak this configuration using the "Edit" button. (Note that the format settings under "General > Editors > Text Editors" have no effect in C/C++ views, since the C/C++ settings are more specific and override those settings. However, you may still want to tweak those settings if you'll be editing other file types in Eclipse.)

Select "General > Workspace" and select "Refresh using native hooks or polling" and "Refresh on access" to prevent Eclipse giving you annoying "Resource is out of sync" messages when the source changes from under it due to Mercurial activity.

Select "General > Content Types", expand "Text > C Source File > C++ Source File", click "Add" and add "*.mm". Eclipse CDT doesn't currently understand Objective-C files (although there is a project that promises to add Objective-C support after the Juno release) so for now this is the best we can do to give Eclipse a chance of expanding content assistance into Objective-C files.

Select "C/C++ > Build > Console" and set "Limit console output (number of lines)" to something large, like "1000000".

Select "C/C++ > Editor" and set "Workspace default" to "Doxygen".

Select "C/C++ > Editor > Content Assist" and set the Auto-Activation delay to 0 so that autocomplete suggestions don't seem to be laggy. (Sadly there is no auto-activation option to activate autocomplete suggestion as soon as you type any alphabetical character to begin a symbol name like there is in other IDEs.)

Select "C/C++ > Editor > Save Actions" and deselect "Ensure newline at the end of file".

Select "C/C++ > Editor > Scalability" and set "Enable scalability mode when the number of lines in the file is more than:" to something larger, like 100000.

Select "C/C++ > Indexer" and set "Index unused headers".

Select "Run/Debug > Console" and deselect "Limit console output".

If you want to increase the text size in the editor, select "General > Appearance > Colors and Fonts", select "Basic > Text Font", and edit the font size.

Creating an Eclipse project

To create an Eclipse project for your Mozilla source tree select "File > New > Makefile Project with Existing Code". In the "Import Existing Code" window that opens, enter a meaningful Project Name that identifies your Mozilla source tree, set the code location to the root of your source tree, select an appropriate Toolchain (e.g. "MacOSX GCC"), and click Finish.

The status bar at the bottom right of the window should now show that Eclipse is "Refreshing the workspace" (gathering a list of all the files in the source tree). Click on the little green button beside this message to open the "Progress" tab, and keep an eye on the "Refreshing workspace" item as you continue with the steps below. (If an "indexing" item starts after the "Refreshing the workspace" item has finished, click the little red box beside that item to cancel it, since we want to configure the project before the indexer runs.)

Initial project properties

So that the indexer will run faster and give better results, you should add some resource filters to have Eclipse ignore certain files and directories. Note, you must not make Eclipse ignore your (main) object directory. That object directory is needed to resolve include paths to the various headers that the build process generates/copies there.

To create resource filters, open the project properties (different to the workspace preferences) by selecting Properties from the context menu for the project in the Project Explorer tab on the left, or by selecting Project > Properties from the menubar. Select "Resource > Resource Filters" on the left of the window that opens, then use the Add button to add the following filters:

  • Add an "Exclude all" filter for folders with a Project Relative Path matching ".hg". (This directory doesn't show in the Project Explorer tab, but Eclipse still indexes it without this filter!)
  • If you have secondary object directories (object directories that are not your only/the primary object directory) for the source tree that are inside the source tree (or if you might have such object directories in future), then add an "Exclude all", regular expression filter for folders with a Project Relative Path matching "obj(?!-debug(?:$|/)).+". This particular regular expression will exclude all directories begining with the string "obj" except "obj-debug", so if "obj-debug" is not the name of your main object directory, then adjust the regular expression as necessary.
  • Add a recursive, regular expression "Exclude all" filter for files with Name matching "^.+\.(?:rej|orig|o|pp|swp)$" to exclude .rej, .orig, .pp, .o and .swp files.
  • Add "Exclude all" filters for any other non-source directories (e.g. Xcode or MSVC project directories).

Click OK to close the filters window, wait for Eclipse to finish processing your filters, then make sure the filtered directories and files have disappeared from the Project Explorer tab on the left. Also check that your main object directory has not disappeared (assuming that it's in your source tree, and not outside it).

Reopen the project properties window and select "C/C++ General > Preprocessor include Paths, Macros etc.". Select the Providers tab. Make sure that "CDT GCC Build Output Parser" is selected, and that "CDT Managed Build Settings Entries" is not selected. Highlight (select) "CDT GCC Build Output Parser", then in the "Language Settings Provider Options" that appear below, make sure that "Share setting entries between projects (global provider)" is not ticked.

If the main object directory for your source tree is located somewhere outside the tree's top source directory, then select the Entries tab, select "GNU C++", select "CDT User Settings Entries", and click "Add". Change "Project Path" to "Filesystem" then select the {objdir}/dist/include directory in your main object directory and click OK. Repeat these steps, but this time for "GNU C" instead of "GNU C++". (See the "Headers are only parsed once" section below to understand why this step is important for people who have their object directory outside their source tree.)

Select "C/C++ Build" from the left of the project properties window. Select the "Builder Settings" tab, untick "Use default build command", set the build command to "bash -l -c 'just-print-mozilla-build.py'" (a script that we'll download in the next section), and set the build directory to "${ProjDirPath}/path/of/your/objdir/relative/to/the/root/of/your/src/tree". Select the "Behaviour" tab, delete the word "all" from the "Build (incremental build)" field, and disable the Clean checkbox.

Select "C/C++ Build > Settings" on the left, select the "Binary Parsers" tab and make sure that all the parsers are deselected. This prevents the (useless for  us) "Searching for binaries" action from constantly interrupting everything.

Getting code assistance working

You're now ready to get code assistance working. :-)

Build option discovery

This section requires that you have already built your mozilla source tree (so that you have an object directory for it), and it is strongly recommended that the object directory is up to date so that the just-print-mozilla-build.py script runs quickly.

As explained in the Code Assistance section above, to provide good code assistance Eclipse CDT needs to collect build information for the source files in the tree by processing a build log from a full, clean build that was made using -j1 -w. Since such a non-parallel, full build would take a very long time, we're going to cheat and set Eclipse's "Build" action to run jwatt's just-print-mozilla-build.py script instead of having it do a real build. This script should complete in less than a minute on a warm tree (if you're object directory is up to date), although Eclipse will take longer than that to process the "build output" it produces.

(Note that an object directory isn't just needed for this build option discovery step. Indexing also requires the object directory to produce good results, since most source files include headers (directly or indirectly) that have been copied to or generated in the object directory. So without an object directory Eclipse's ability to index the source and provide good code assistance will be significantly degraded.)

Download just-print-mozilla-build.py and change it's permissions to make it executable ('chmod a+x just-print-mozilla-build.py').

If you don't put just-print-mozilla-build.py somewhere in your PATH, then go back to the previous Project Configuration section where you set just-print-mozilla-build.py and specify its absolute path instead of just its name.

Now invoke the script by clicking the Build button (the button with the hammer symbol) or by selecting "Project > Build Project" from the main menu. That done, select the "Console" tab at the bottom of the main Eclipse window and you should see the build console output flying by as Eclipse processes it. It should take about 5-10 minutes for Eclipse to finish processing the output.

Building the index

Once you see the end of the build output in the Console tab and the Build item has disappeared from the Progress tab, you can start indexing the source. If indexing started automatically (see the Progress tab), cancel it, since there seems to be a bug that makes it give bad results when it starts automatically at this stage. Right click the project root in the Project Explorer tab and select "Index > Rebuild". You will now see "Indexing..." in the status bar at the bottom right. It will take 10 minutes or so on a decent developer machine for a full rebuild of the index.

Once the indexer has finished (keep an eye on the Progress tab), sanity check that everything went as it should have by right clicking the project in the Project Explorer tab and selecting "Index > Search For Unresolved Includes". If you get many more than 2000 unresolved includes (as of May 2012), then things have gone pretty wrong. You should be able to use the search results to help figure out what the problem is.

Assuming everything went as expected, you should now find that Eclipse's code assistance works a whole lot better. :-) To test out the code assistance, see the code assistance tips in the Usage Tips section below.

To improve code assistance even more, see the "Headers are only parsed once" subsection in the "Known Issues" section below.

Keeping the index up-to-date

As the source changes from day-to-day, you'll want to update the index to keep the code assistance working well.

Since the compiler options used to build the source change relatively infrequently, the "build" step above doesn't need to be rerun all that often. Re-run it (and then rebuild the index) once a week or so, or as necessary when you start to notice unnusual code assistance issues that aren't fixed by rebuilding the index alone.

Rebuilding the index itself is required much more frequently, since the source changes more frequently. In principle you can set the index to rebuild automatically by opening the workspace preferences, selecting "C/C++ > Indexer" and reenebling "Automatically update the index". However, you may find this too disruptive, since reindexing will then happen very frequently and code assistance can be broken while the index is rebuilding. The alternative is to leave that option disabled and update the index manually as necessary. To update the index manually, use the context menu in the Project Explorer tab on the left side of the window. To rebuild for changes in an individual directory (for example to take account of some changes that you yourself made) select "Index > Freshen All Files" on that directory. To rebuild the entire index (for example when you update from mozilla-central) select "Index > Rebuild" on the project root.

Usage tips

Below are some of the more useful user tips. (If you're thinking of adding tips, please first consider how widely useful they will be before adding to this already lengthy page.) For further documentation see the official Eclipse user guide and Eclipse CDT user guide.

Keyboard shortcuts

Regarding key bindings (keyboard shortcuts), the bindings given below are the defaults. You can change the key bindings by opening the workspace preferences (Eclipse > Preferences, or Window > Preferences) and selecting "General > Keys". You can set the scheme to "Emacs" or "Microsoft Visual Studio" if that's your thing, or change individual key bingings. When changing individual key bindings, note that bindings are context sensitive, and that any changes you make may be ignored if they conflict with existing bindings or if they are overriden by a binding for a more specific context. For example, changing the Find Next command to cmd-G/ctrl-G is not sufficient. For that to work you also either need to find the existing bindings for that key combination (using the Bindings column to sort by key combination helps with this) and remove them, or else you need to make your binding very specific by setting the "When" field to "C/C++ Editor" instead of the more general "Editing Text".

Opening files

You can quickly open a file by name using Cmd-Shift-R/Ctrl-Shift-R. Although Eclipse doesn't do fuzzy matching when you type a file name, it does allow you to use wildcards.

To quickly switch between a source file and its header file, use Ctrl-Tab.

To quickly switch to a recently viewed document use Cmd-F6/Ctrl-F6. If you want to change this awkward key binding, the command you need to rebind is "Next Editor".

To show a filterable list of open documents (similar to Emacs buffers), use Cmd-E/Ctrl-E.

If you click the yellow, double arrow button at the top of the Project Explorer tab on the left, it will keep the selected file in the Project Explorer tab in sync with the file that you're currently editing.

Organizing views

Use Ctrl-M to toggle maximization of the current editor view.

To tab to another view, use Cmd-F7/Ctrl-F7. This is useful if you have maximized the editor using Ctrl-M and you want to quickly see your search results, for example, without un-maximizing the editor.

To side-by-side edit the same file in two different tabs, select the tab of the file that you want to edit, then from the menu bar select "Window > New Editor". This will open another tab containing the same file. Now simply drag that tab to position it beside, above or below the original. Changes you make in one editor will be immediately reflected in the other.

Note that the Search, Call Hierarchy, etc. tabs have a "Pin" button that allows you to open multiple tabs of the same type. This is useful if you want to keep your existing search results open, for example, and have a new search open its in a separate tab rather than overriding the contents of the existing Search tab.

Code assistance

Warning: indexing, by its very nature, is specific to a given compiler configuration. Be aware that when Eclipse gives results for any of the actions that follow, it will not include results for sections of the code that are ifdef'ed out by the configuration used to create your object directory. For example, if you are using Mac and you search for callers of nsDisplayListBuilder::IsInTransform, the results will not include the caller in nsObjectFrame.cpp because that caller is wrapped in "#ifndef XP_MACOSX". For most people this won't bite them too often, but be sure to use Try before you push when changing symbols. ;-)

To jump to the definition of a symbol (or the declaration of a symbol if already at the definition), hover over the symbol, hold down the Ctrl key, move the mouse slightly to linkify the symbol, then click on it.

To do a C++ symbol search select "Search > C/C++" from the menubar, or use Ctrl-H and select the "C/C++" Search tab.

To get a list of autocomplete options in an editor, start typing the name of an identifier and then type Ctrl-Space. Unfortunately the autocomplete list cannot (currently) be configured to appear automatically as soon as you start typing a character that might be the start of an identifier name.

To see the callers of a method (and their callers, etc.), select the method and use the context menu to select "Open Call Hierarchy".

To see the inheritance tree for a class, select its name in an editor window and select "Open Type Hierarchy" from the context menu. Note that you can switch between "Show the Type Hierarchy", "Show the Supertype Hierarchy" and "Show the Subtype Hierarchy" using the buttons to the right of the "Type Hierarchy" tab.

To see the overrides of a virtual method, select that method's name in an editor window and select "Open Type Hierarchy" or "Quick Type Hierarchy" from the context menu. The results for "Open Type Hierarchy" will show all classes in the inheritance tree, and those methods that override the method will have a triangular red marker beside them. Select one of these classes and in the method pane to the right the method you searched for will be highlighted - double click to see its definition. The results for "Quick Type Hierarchy" will only show those classes in the inheritance tree that override the method. Double click on a class to go straight to its override's definition.

Building from Eclipse

In short, don't do this. Eclipse doesn't have good facilities for building incrementally in individual directories in the way that Mozilla developers generally require. More importantly, unless you're willing to screw up Eclipse's code assistance (in which case why bother using Eclipse) you're going to have to set Eclipse's "Build" step to do very slow, non-parallel, full rebuilds. (See the "Code assistance" section above.)

Nevertheless, if you understand the above warning and you still want to configure Eclipse's "Build" button to invoke a real bulid, then read on.

Basically you want to do something similar to the steps in the Initial project properties section above, but use "make -j1 -wB" (or just "make" if you don't care about keeping code assistance working) instead of using just-print-mozilla-build.py.

If you want to invoke "make -f client.mk" from your source directory instead of invoking make from your object directory, then in the "C/C++ Build" section of the project properties, set "Build command" to "make -f client.mk" and set "Build directory" to just "${ProjDirPath}" (this is the top of the source tree). Select the Behaviour tab and remove the "all" from the "Build (Incremental build)" field. Select "C/C++ Build > Build Variables", and add a variable "MOZCONFIG" and set it to the top source directory relative path of the mozconfig file you want to buid with. Set any other environment variables you want to set for the build, then close the project properties window.

Now when you hit the Build button (the little hammer icon) you should see the source build in the Console tab at the bottom of the window.

The benefit of building from inside Eclipse is that build errors will appear in the Problems tab at the bottom of the window, and from there you can double click on the build error and it will take you straight to the source line where the problem occurred. For this to work reliably though, you need to build with similar make flags to those used to create the build log in the instructions above. Specifically, in order to reliabaly identify the problem source file, you should not do a parallel build, and you should pass the -w flag to make so that it outputs "Entering"/"Leaving" lines. It also used to be necessary to add the following two lines to your mozconfig to make the compiler output errors all on a single line, but that may not be needed any more:

export CFLAGS="-fmessage-length=0"
export CPPFLAGS="-fmessage-length=0"

Debugging

To create a debug configuration, open the project properties window, and select "Run/Debug Settings" on the left. Click "New" then select "C/C++ Application". In the window that opens enter the path to your firefox binary (something like obj-debug/dist/NightlyDebug.app/Contents/MacOS/firefox) and select "Disable auto build". Select the Arguments tab and enter any args you want to pass to firefox (such as "--no-remote -p my-testing-profile"). If you're on Linux, you may also need to set the "Working directory" to "${ProjDirPath}/obj-debug/dist/bin", and then select the Environment tab and set LD_LIBRARY_PATH to ".:./plugins:.", and LIBRARY_PATH to ".:./components:.". (Is this really necessary? If so, why? Isn't LIBRARY_PATH for compile time, not run time, linking?)

In the workspace preferences, you may want to go to "C/C++ > Debug > GDB" and deselect "Stop on startup at" so that Eclipse won't automatically break in main() when it launches Firefox for debugging.

To debug, click the Debug button on the toolbar, or select "Run > Debug" from the menu bar.

It's not obvious, but you can get a gdb prompt in the console so that you can type gdb commands directly.

After you've finished debugging, you can get back to the C/C++ perspective via the menubar by selecting "Window > Open Perspective > C/C++".

Upgrading GDB on Mac

The ancient, barely maintained fork of GDB that comes with Xcode on Mac is really horrible. If you use Mac, you may want to build the latest FSF version of GDB and set Eclipse to use that GDB for debugging. One suggested configuration for building GDB is '--prefix="$HOME" --disable-debug --with-python=/usr' (create an optimized build with support for Python (so you can use python to much better control when you break etc.), and install it in $HOME/bin). That done, open the workspace preferences, select "C/C++ > Debug > GDB", and set "GDB Debugger" to the full path of your new gdb executable.

GDB unexpectedly detaching

If GDB starts ignoring your breakpoints, or unexpectedly terminates or detaches from the Firefox process, this may be caused by out of date breakpoints (breakpoints that you set during a previous debug session, after which you've since rebuilt). Remove any such breakpoints and restart your debug session.

Known Issues

There are various knows limitations and bugs when it comes to using Eclipse with Mozilla. Eclipse is open source, of course, so if anyone feels like doing a bit of Java hacking to fix these issues that'd be great. :-)

Headers are only parsed once

For performance reasons, Eclipse only processes header files that have include guards once, using the compiler options for the first source file it encounters that includes that header (Eclipse bug 380511). This is responsible for most of the parse errors in the source files displayed in Eclipse. The problem is that the compiler options for the original source file may ifdef out sections of the header that would not be ifdef'ed out - and in fact are required by - source files in other parts of the tree.

For example, in content/svg/content/src/nsSVGEllipseElement.cpp Eclipse shows a parse error due to NS_DOM_INTERFACE_MAP_ENTRY_CLASSINFO not being defined. This define is in nsDOMClassInfoID.h, which is included via the following include chain:

content/svg/content/src/nsSVGEllipseElement.cpp
 content/svg/content/src/nsSVGPathGeometryElement.h
  content/svg/content/src/nsSVGGraphicElement.h
   content/svg/content/src/nsSVGStylableElement.h
    content/svg/content/src/nsSVGElement.h
     content/base/src/nsGenericElement.h
      obj-debug/dist/include/nsDOMClassInfoID.h

In nsDOMClassInfoID.h the NS_DOM_INTERFACE_MAP_ENTRY_CLASSINFO define is behind an |ifdef _IMPL_NS_LAYOUT|. The properties for nsSVGEllipseElement.cpp show that this define was picked up by the build option discovery and set on nsSVGEllipseElement.cpp, but somehow it's not set for nsDOMClassInfoID.h. If you right click on nsDOMClassInfoID.h in the Project Explorer and select "Index > Create Parser Log File", the log shows "Context" is set to "accessible/src/base/AccEvent.cpp" and if you check the properties for AccEvent.cpp, indeed it is not built with the _IMPL_NS_LAYOUT define.

One way to mitigate this problem is to manually define defines on problem directories. For example, to solve the _IMPL_NS_LAYOUT issue described above you would use the context menu for the 'layout' directory in the Project Explorer tab to open the directory's properties. Select "C/C++ General > Prepocessor Include Paths, Macros etc.", and then select "GNU C++" and "CDT User Settings Entries". Click "Add", select "Preprocessor Macro" from the dropdown, then set Name to _IMPL_NS_LAYOUT and leave Value blank. Click OK twice to return to the main Eclipse window, and then use the context menu for the 'layout' directory to reindex the 'layout' directory and then to "Run C/C++ Code Analysis" on it.

This issue can also cause "Unresolved inclusion" errors in headers if the first time Eclipse sees the header is while indexing a file for which it doesn't have any build output parser data. (Since it then has no explicit include paths to search.) When this happens it causes a knock-on for all the files that include this header (directly or indirectly) since they too now have things missing. This problem is more important for people who have their object directory outside their source directory. When the object directory is inside the source directory (and not filtered out by a resource filter) then Eclipse's "Allow heuristic resolution of includes" (enabled by default) will generally allow the included headers to be found when processing source files that don't have build output parser data. When the object directory is outside the source directory though, the user needs to take extra steps to make sure the heuristic header resolution can find the headers. This is the reason that the instructions above instruct you to explicitly add {objdir}/dist/include to the project's "CDT User Setting Entries" if your object director is outside your source directory. Fixing Eclipse bug 381601 would considerably reduce the impact of this issue.

Searching

Free text search is not backed by a database, so it is extremely slow. Furthermore the results are not saved, so if you immediately search for the exact same text again without any changes to the source files having occurred, Eclipse will do a slow search all over again.

It is not easy to restrict searches to an ad-hoc directory, which is pretty annoying given how slow free text search is.

Search history in a project is not preserved across restarts.

Duplicate searches in history - even consecutive ones - are not coalesced.

Duplicate files

Sometimes when searching for files or symbols you will be given the option between a file in the source tree, and a file with the same name under the object directory. (Some source and header files are copied to the object directory by the build process, so we end up with copies in both places.) This will happen if your object directory is inside the source directory. If you don't want to switch to building your object directory outside the source tree, then this is just one of those things that you'll have to put up with. (If you do switch, not the instructions that will then apply to you in the project configuration section above!) Since the indexer needs to be able to resolve header files in the object directory in order to produce good results we can't have Eclipse ignore the object directory. But then there's no easy way to tell Eclipse that any given file in the object directory is actually just a copy of a given file in the source directory, and that it should always show the user the copy in the source directory while using the file in the object directory for indexing.

Building

Eclipse's support for incremental builds is nonexistant. It would be nice if Eclipse could at least pass information about what files have changed to the build process, which could then decide on a faster way to do the build (e.g., "just make in layout/"). I (roc) have actually written a small change to the CDT Make builder that lets you specify that as an option, in which case Eclipse sends the names of all changed files to your build tool. The build tool is a Perl script that figures out if a faster build is possible and if so, does it.

FAQ

Here are some frequenty asked questions.

Is there a Mercurial plugin for Eclipse?

There is MercurialEclipse, but probably most Mozilla developers will probably just prefer to use the command line. If you think we need our own documentation on MercurialEclipse, please consider adding a separate page for that tool since this page is long enough.

How can I delete my Eclipse project and start over?

If you followed the recommendation above of having one workspace per Mozilla tree, then this is easy. (If you didn't and you have projects for more than one source tree entangled in your workspace directory, well you're on your own.) Simply delete the .project and .cproject files and the .settings directory (if it exists) from the root of your Mozilla tree, and delete the workspace corresponding to the tree. That's it, you can now recreate an Eclipse project for your tree from scratch.

Isn't there a better method of build option discovery?

Yes, but Eclipse doesn't currently support it. Instead of reading build console output, Eclipse could use something like LD_PRELOAD to load its own little library into all the processes that are invoked as part of the build process. This library could then check whether the process is a compiler instance and, if so, use the processes' current working directory and the arguments that were passed to it to reliably obtain the information it needs for each source file that is compiled. This would simplify the instructions above since there would be no need to mess about with just-print-mozilla-build.py to avoid special non-parallelized, non-silenced builds. You could also build from Eclipse and get the benefits that brings.

How can I run a more recent CDT version?

If you have downloaded an Eclipse Developer build then you can use Eclipse's software update mechanism to update your developer snapshot to the latest nightly for that developer branch. To do that, do the following.

From Eclipse's "Help" menu select "Install New Software...", then in the "Install" window that opens, click "Available Software Sites". In the window that opens, click "Add", and in the prompt set Name to something like "Nightly" and Location to something like "http://download.eclipse.org/tools/cd...s/juno/nightly" (change "juno" to the current developer branch). Click "OK", then "OK" again. Type "Nightly" into the "Work with" field, and select the repository that you just added. (If it doesn't appear, close the window, reopen it from the Help menu, and try again.) A "CDT Main Features" option should now have been added in the area below. Tick this (all of its sub-options should then be ticked), click "Next" twice, accept the license agreement, and then click "Finish". Eclipse should now update itself and ask you to restart.

Troubleshooting: If you get an error when trying to update, try clicking "Available Software Sites" in the "Install" window, make sure "Juno" is still unticked, that  "Nightly" is ticked, highlight "Nightly", click "Reload", "OK", and then try again.

Troubleshooting

Here is a list of problems people have encountered, and suggestions for solutions.

Parser errors

Parser errors/warnings are indicated by red/yellow markers on files in the Project Explorer tab, and in the bar down the right hand side of source files. In the case of the latter you can click on the marker to jump to the line with the problem and then hover over the "bug" icon to get an explanation of the problem.

The parser error indicators don't seem to show (reliably?) until you open a source file, then error markers will be added for that file. To force all markers to show for a directory, right click that directory in the Project Explorer and select "Run C/C++ Code Analysis". As well as adding the markers, this will give you a list of the issues in the Problems tab at the bottom of the window where you can double click to jump to the location of any given issue.

Other things you can try when trying to figure out parser errors include:

  1. Select your project in the Project Explorer, then from the context menu select "Index > Search for Unresolved Includes".
  2. For problematic source files, select the file in the Project Explorer and from the context menu select "Index > Create Parser Log File".
  3. Select your project in the Project Explorer, then from the context menu select "Index > Rebuild". When the indexing is done open the log using "Window > Show View > Other > General > Error Log" and check the summary and look for exceptions.

Problem Occurred (Java heap space)

If Eclipse becomes glacially slow and then you get this error message, see the "Increasing memory limits" section above.

Resource is out of sync with the file system

If you get the message "Resource is out of sync with the file system", then you didn't set the "Refresh" options above in the "global configuration" section. Either set those, or else refresh the project (or an individual directory/file) manually using the Refresh item from the context menu in the Project Explorer tab.

Old

Everything that follows is old content that will be deleted (or integrated in).

GDB Timeouts

I don't think this is an issue any more in the last few Eclipse versions.

Out of the box, you may/will get GDB connection timeouts. This is because Eclipse is trying to push every subfolder in GDB's environment. The easiest way to resolve this issue is to remove any source entry from the debug configuration (Run->Open Debug Dialog...) in the Source tab. Doing so will unfortunately remove the binding between the binaries and the source code. To keep this feature working, you need to add a "Path Mapping" by clicking "Add..." in the Source tab. Once a "Path Mapping" is created, select "Edit..." and add an entry with these values

 Compilation path: / 
 Local file system path: /

This is the only known workaround to bind binaries to source files. It has been tested and works perfectly under Eclipse Europa (3.3.2) with Eclipse-CDT (4.0.3).

Revision Source

<h2 name="Using_Eclipse_CDT_for_Mozilla_development">Introduction</h2>
<div class="warning">Please contact <a href="/User:Jonathan_Watt" title="User:Jonathan Watt">Jonathan Watt</a> before editing this page. In fact the instructions on this page are not working yet, so probably you shouldn't even bother reading it until this notice is removed. The old text on this page was years out of date and no longer correct/working. Jonathan is in the middle of a complete rewrite, but it's taking a fair bit of investigative work and coordination with the Eclipse CDT team to get various bugs worked and to get indexing working well with the Mozilla source.</div>
<p><a class="external" href="http://eclipse.org/cdt">Eclipse CDT</a><span class="external"> (C/C++ Development Tools)</span> is an open-source IDE for C and C++ development. It supports complex projects that have their own build system, like Mozilla. If you want to use an IDE for Mozilla C++ development with advanced code assistance (inheritance/call graph explorer, jump to definition, refactoring, autocomplete, syntax highlighting, etc.), then Eclipse CDT might be for you.</p>
<h2>System requirements</h2>
<p class="warning">Eclipse provides many features that you'll find yourself unable to live without once you start using them, but it does come with some fairly hefty system requirements. In order to index the Mozilla source it requires <strong>2-3 GB of free RAM</strong>. If you don't already have 16 GB of RAM installed, Eclipse provides you with the perfect excuse to upgrade. :-)</p>
<h2 class="warning">Setup time</h2>
<p>It will probably take you about an hour to set up Eclipse CDT for the first time and get its code assistance working well. (That assumes you already have a copy of the Mozilla source, and that it has been built and has a pre-existing object directory.)</p>
<h2>Code assistance</h2>
<p>Out of the box, Eclipse can provide some code assistance for the Mozilla source, but it will be fairly incomplete and often just plain broken. If you set up Eclipse as detailed below it will do a much, much better job.</p>
<h3>Important background</h3>
<p>To help you make sense of the instructions that follow (and so that you can modify them to meet your own needs if necessary) this section provides some background on what IDEs need in order to provide advanced code assistance, and what Eclipse CDT needs in particular.</p>
<p>To be able to provide really good code assistance for a project's source code, IDEs like Eclipse need to carry out a thorough <a class="link-https" href="https://en.wikipedia.org/wiki/Static_program_analysis" title="https://en.wikipedia.org/wiki/Static_program_analysis">static analysis</a> of the project's source files to build up a picture of the code. (What Eclipse is trying to do when it "indexes" the source.) Static analysis involves parsing the source files, so naturally it can only produce good results if it has a sensible set of preprocessor defines, include paths and pre-include files for each source file. Since Eclipse doesn't initially have any of this information, the code assistance that it's able to provide out of the box is pretty broken.<br> <br> For projects the size and complexity of Mozilla, it's impractical to manually configuring Eclipse with a valid set of defines and include paths for each different part of the source code. Happily, Eclipse makes manual configuration unnecessary. Like some other IDEs, for projects like Mozilla that have their own build system, Eclipse provides a tool that can collect the options that are passed to the compiler for each file that's compiled during an actual build. This process is sometimes called "build option discovery" or "compiler option discovery".</p>
<p>The way that Eclipse CDT does build option discovery is to scan the console output from a real build looking for lines where a compiler was invoked. For each line that invoked a compiler, it tries to figure out which source file was being built and what its include paths were. <u>If relative paths are used to specify the source file or any of its include paths (common in Mozilla), and if you fail to take steps to make sure the build output specifies which directory the compiler is invoked from, this will not be possible.</u> <em>If</em> Eclipse can successfully identify which source file was being compiled, then it can associate with that file the <em>resolvable</em> include paths, preprocessor defines and pre-include files that were passed to the compiler.</p>
<p>Note the requirements that this method of build option discovery imposes on us. First, Eclipse needs build console output for a complete build so that it can find the compiler options for as many source files as possible. The build must be explicitly instructed to output information that allows the directory that the compiler is being invoked from to be identified (i.e. 'make' must be instructed to output "Entering directory..."/"Leaving directory..." lines). Finally, the build must not be parallelized (since that would result in interleaving of build output from different directories, breaking resolution of relative paths by interleaving the "Entering directory..."/"Leaving directory..." lines) and the build must not be silenced/quietened.</p>
<div class="warning">Conversely, note this very carefully: if you configure Eclipse to invoke a build process that is parallelized, silenced, or that fails to identify the directory that the compiler is being run from, then it <strong><u>will</u></strong> mess up the compiler options that Eclipse associates with your files, and that in turn will <strong><u>significantly</u></strong> degrade the quality of the code assistance that Eclipse will provide after it next re-indexes the code.</div>
<p>Unfortunately, these requirements aren't a very good fit with the typical Mozilla developer's wish to minimize build times, which implies parallelized, silenced builds.</p>
<p>The consequences of the above observations are this:</p>
<div class="warning"> <ul> <li>It is strongly recommended that you invoke your normal (re)builds from the command line, <strong>externally</strong> of Eclipse.</li> <li>Below we will configure Eclipse's build step so that you use it only occasionally to manually trigger a special "build" (actually a script that fakes a build) purely for the purposes of setting/updating the compiler options Eclipse associates with each source file.</li> </ul>
</div>
<p>(Not using Eclipse to build does lose you some minor benefits that Eclipse has to offer, but these are worth sacrificing for much better code assistance. See the "Build" section below if you're interested in what you lose. If you're interested in future improvements to Eclipse that would allow parallel builds to be run from inside Eclipse, see the "Isn't there a better method of build option discovery?" below.)</p>
<h2>Installing Eclipse</h2>
<p>These instructions currently direct you to install Eclipse Juno, a developer build of Eclipse. ("Juno" is the code name of the next version of Eclipse, coincidentally scheduled for released on June 27, 2012.) Using Juno is important because it contains improvements and fixes that allow it to provide much better code assistance for the Mozilla source.<br> <br> Download "Eclipse IDE for C/C++ Developers" from the <a class="external" href="http://www.eclipse.org/downloads/index-developer.php" title="http://www.eclipse.org/downloads/index-developer.php">Eclipse Developer builds</a> page, extract the file, and put the resulting directory somewhere sensible. (Consider renaming the Eclipse executable to "Eclipse-Juno-nightly" to remind you what version it is later.)</p>
<p>Don't start Eclipse yet.</p>
<h2>Increasing memory limits</h2>
<p class="warning">When Eclipse's indexer tries to process the Mozilla source, Eclipse will need considerably more memory than it allows itself out of the box. You should <a class="external" href="http://wiki.eclipse.org/FAQ_How_do_I_increase_the_heap_size_available_to_Eclipse%3F" title="http://wiki.eclipse.org/FAQ_How_do_I_increase_the_heap_size_available_to_Eclipse%3F">increase its memory limits using the <code>eclipse.ini</code></a> in your installation directory (or in Eclipse.app/Contents/MacOS on Mac). Set something like <code>-Xms1G -Xmx3G -XX:MaxPermSize=1G</code> (initial heap space of 1 GB, max heap space of 3 GB, max perm-gen space of 1 GB).</p>
<div class="warning">If you fail to increase these limits then you will find that Eclipse will tend to hang when you try to index or work with the Mozilla source.</div>
<h2>Initial workspace preferences</h2>
<p>For future reference, note that the workspace preferences are a separate thing to the project properties.</p>
<p>When you open Eclipse, it will ask you to "Select a workspace" (a directory where Eclipse will store files that it generates during indexing, etc.). It's recommended that you have a separate workspace for each Mozilla source tree, and that you choose a directory outside the Mozilla source. Something like $HOME/eclipse-workspaces/mozilla-tree-1, for example. After selecting an appropriate directory, click OK. Close the "Welcome" tab.</p>
<div class="warning">Before you proceed further, check that your changes to the memory limits have taken effect and are present in <code>Eclipse/Help &gt; About Eclipse &gt; Installation Details &gt; Configuration</code>.</div>
<p>Whenever you create a new workspace for a Mozilla source tree, you should be sure to turn off the following two settings in the workspace preferences (<code>Window &gt; Preferences</code>, or <code>Eclipse &gt; Preferences</code>) before creating a project in that workspace:</p>
<ul> <li>in "General &gt; Workspace", disable "Build automatically"</li> <li>in "C/C++ &gt; Indexer", disable "Automatically update the index"</li>
</ul>
<p>Turning off automatic indexing prevents the CPU intensive indexer from running at various stages in the steps below before we're ready.</p>
<p>Eclipse CDT will format C/C++ code that you add as you type. However, it's default formats are not a good match to <a href="/En/Developer_Guide/Coding_Style" title="/En/Mozilla_Coding_Style_Guide">Mozilla's style rules</a>. Download this <a href="/@api/deki/files/6241/=eclipse-formatter-for-mozilla.xml" title="https://developer.mozilla.org/@api/deki/files/6241/=eclipse-formatter-for-mozilla.xml">first pass at an Eclipse formatter configuration for Mozilla C/C++ coding style</a>, and install it by opening the workspace preferences, selecting "C/C++ &gt; Code Style &gt; Formatter", and then using the "Import" button to import that file. The "Active profile" field should then automatically change to "Mozilla". Depending on the area of the code that you work on, you may need to tweak this configuration using the "Edit" button. (Note that the format settings under "General &gt; Editors &gt; Text Editors" have no effect in C/C++ views, since the C/C++ settings are more specific and override those settings. However, you may still want to tweak those settings if you'll be editing other file types in Eclipse.)</p>
<p>Select "General &gt; Workspace" and select "Refresh using native hooks or polling" and "Refresh on access" to prevent Eclipse giving you annoying "Resource is out of sync" messages when the source changes from under it due to Mercurial activity.</p>
<p>Select "General &gt; Content Types", expand "Text &gt; C Source File &gt; C++ Source File", click "Add" and add "*.mm". Eclipse CDT doesn't currently understand Objective-C files (although there is <a class="external" href="http://code.google.com/p/objectiveclipse/" title="http://code.google.com/p/objectiveclipse/">a project that promises to add Objective-C support</a> after the Juno release) so for now this is the best we can do to give Eclipse a chance of expanding content assistance into Objective-C files.</p>
<p>Select "C/C++ &gt; Build &gt; Console" and set "Limit console output (number of lines)" to something large, like "1000000".</p>
<p>Select "C/C++ &gt; Editor" and set "Workspace default" to "Doxygen".</p>
<p>Select "C/C++ &gt; Editor &gt; Content Assist" and set the Auto-Activation delay to 0 so that autocomplete suggestions don't seem to be laggy. (Sadly there is no auto-activation option to activate autocomplete suggestion as soon as you type any alphabetical character to begin a symbol name like there is in other IDEs.)</p>
<p>Select "C/C++ &gt; Editor &gt; Save Actions" and deselect "Ensure newline at the end of file".</p>
<p>Select "C/C++ &gt; Editor &gt; Scalability" and set "Enable scalability mode when the number of lines in the file is more than:" to something larger, like 100000.</p>
<p>Select "C/C++ &gt; Indexer" and set "Index unused headers".</p>
<p>Select "Run/Debug &gt; Console" and deselect "Limit console output".</p>
<p>If you want to increase the text size in the editor, select "General &gt; Appearance &gt; Colors and Fonts", select "Basic &gt; Text Font", and edit the font size.</p>
<h2>Creating an Eclipse project</h2>
<p>To create an Eclipse project for your Mozilla source tree select "File &gt; New &gt; Makefile Project with Existing Code". In the "Import Existing Code" window that opens, enter a meaningful Project Name that identifies your Mozilla source tree, set the code location to the root of your source tree, select an appropriate Toolchain (e.g. "MacOSX GCC"), and click Finish.</p>
<p>The status bar at the bottom right of the window should now show that Eclipse is "Refreshing the workspace" (gathering a list of all the files in the source tree). Click on the little green button beside this message to open the "Progress" tab, and keep an eye on the "Refreshing workspace" item as you continue with the steps below. (If an "indexing" item starts after the "Refreshing the workspace" item has finished, click the little red box beside that item to cancel it, since we want to configure the project before the indexer runs.)</p>
<h2>Initial project properties</h2>
<p>So that the indexer will run faster and give better results, you should add some resource filters to have Eclipse ignore certain files and directories. Note, <em>you must <u>not</u> make Eclipse ignore your (main) object directory</em>. That object directory is needed to resolve include paths to the various headers that the build process generates/copies there.</p>
<p>To create resource filters, open the project properties (different to the workspace preferences) by selecting <code>Properties</code> from the context menu for the project in the Project Explorer tab on the left, or by selecting <code>Project &gt; Properties</code> from the menubar. Select "Resource &gt; Resource Filters" on the left of the window that opens, then use the Add button to add the following filters:</p>
<ul> <li>Add an "Exclude all" filter for folders with a <strong>Project Relative Path</strong> matching ".hg". (This directory doesn't show in the Project Explorer tab, but Eclipse still indexes it without this filter!)</li> <li>If you have secondary object directories (object directories that are <strong><u>not</u></strong> your only/the primary object directory) for the source tree that are <strong><u>inside</u></strong> the source tree (or if you might have such object directories in future), then add an "Exclude all", <strong>regular expression</strong> filter for folders with a <strong>Project Relative Path</strong> matching "obj(?!-debug(?:$|/)).+". This particular regular expression will exclude all directories begining with the string "obj" <strong>except</strong> "obj-debug", so if "obj-debug" is not the name of your main object directory, then adjust the regular expression as necessary.</li> <li>Add a <strong>recursive, regular expression</strong> "Exclude all" filter for files with <strong>Name</strong> matching "^.+\.(?:rej|orig|o|pp|swp)$" to exclude .rej, .orig, .pp, .o and .swp files.</li> <li>Add "Exclude all" filters for any other non-source directories (e.g. Xcode or MSVC project directories).</li>
</ul>
<p>Click OK to close the filters window, wait for Eclipse to finish processing your filters, then make sure the filtered directories and files have disappeared from the Project Explorer tab on the left. Also check that your <strong><u>main</u></strong> object directory has <u><strong>not</strong></u> disappeared (assuming that it's in your source tree, and not outside it).</p>
<p>Reopen the project properties window and select "C/C++ General &gt; Preprocessor include Paths, Macros etc.". Select the Providers tab. Make sure that "CDT GCC Build Output Parser" <strong>is</strong> selected, and that "CDT Managed Build Settings Entries" is <strong>not</strong> selected. Highlight (select) "CDT GCC Build Output Parser", then in the "Language Settings Provider Options" that appear below, make sure that "Share setting entries between projects (global provider)" is not ticked.</p>
<p>If the main object directory for your source tree is located somewhere <strong><u>outside</u></strong> the tree's top source directory, then select the Entries tab, select "GNU C++", select "CDT User Settings Entries", and click "Add". Change "Project Path" to "Filesystem" then select the {objdir}/dist/include directory in your main object directory and click OK. Repeat these steps, but this time for "GNU C" instead of "GNU C++". (See the "Headers are only parsed once" section below to understand why this step is important for people who have their object directory outside their source tree.)</p>
<p>Select "C/C++ Build" from the left of the project properties window. Select the "Builder Settings" tab, untick "Use default build command", set the build command to "bash -l -c 'just-print-mozilla-build.py'" (a script that we'll download in the next section), and set the build directory to "${ProjDirPath}/path/of/your/objdir/relative/to/the/root/of/your/src/tree". Select the "Behaviour" tab, delete the word "all" from the "Build (incremental build)" field, and disable the Clean checkbox.</p>
<p>Select "C/C++ Build &gt; Settings" on the left, select the "Binary Parsers" tab and make sure that all the parsers are deselected. This prevents the (useless for  us) "Searching for binaries" action from constantly interrupting everything.</p>
<h2>Getting code assistance working</h2>
<p>You're now ready to get code assistance working. :-)</p>
<h3>Build option discovery</h3>
<div class="warning">This section requires that you have already <a href="/En/Simple_Firefox_build" title="https://developer.mozilla.org/En/Simple_Firefox_build">built your mozilla source tree</a> (so that you have an object directory for it), and it is strongly recommended that the object directory is up to date so that the just-print-mozilla-build.py script runs quickly.</div>
<p>As explained in the Code Assistance section above, to provide good code assistance Eclipse CDT needs to collect build information for the source files in the tree by processing a build log from a full, clean build that was made using -j1 -w. Since such a non-parallel, full build would take a very long time, we're going to cheat and set Eclipse's "Build" action to run jwatt's just-print-mozilla-build.py script instead of having it do a real build. This script should complete in less than a minute on a warm tree (if you're object directory is up to date), although Eclipse will take longer than that to process the "build output" it produces.</p>
<p>(Note that an object directory isn't just needed for this build option discovery step. Indexing also requires the object directory to produce good results, since most source files include headers (directly or indirectly) that have been copied to or generated in the object directory. So without an object directory Eclipse's ability to index the source and provide good code assistance will be significantly degraded.)</p>
<p>Download <a class="link-https" href="https://hg.mozilla.org/users/jwatt_jwatt.org/eclipse-cdt-tools/raw-file/tip/just-print-mozilla-build.py" title="https://hg.mozilla.org/users/jwatt_jwatt.org/eclipse-cdt-tools/raw-file/tip/just-print-mozilla-build.py">just-print-mozilla-build.py</a> and change it's permissions to make it executable ('chmod a+x just-print-mozilla-build.py').</p>
<div class="warning">If you don't put just-print-mozilla-build.py somewhere in your PATH, then go back to the previous Project Configuration section where you set just-print-mozilla-build.py and specify its absolute path instead of just its name.</div>
<p>Now invoke the script by clicking the Build button (the button with the hammer symbol) or by selecting "Project &gt; Build Project" from the main menu. That done, select the "Console" tab at the bottom of the main Eclipse window and you should see the build console output flying by as Eclipse processes it. It should take about 5-10 minutes for Eclipse to finish processing the output.</p>
<h3>Building the index</h3>
<p>Once you see the end of the build output in the Console tab and the Build item has disappeared from the Progress tab, you can start indexing the source. If indexing started automatically (see the Progress tab), cancel it, since there seems to be a bug that makes it give bad results when it starts automatically at this stage. Right click the project root in the Project Explorer tab and select "Index &gt; Rebuild". You will now see "Indexing..." in the status bar at the bottom right. It will take 10 minutes or so on a decent developer machine for a full rebuild of the index.</p>
<div class="warning">Once the indexer has finished (keep an eye on the Progress tab), sanity check that everything went as it should have by right clicking the project in the Project Explorer tab and selecting "Index &gt; Search For Unresolved Includes". If you get many more than 2000 unresolved includes (as of May 2012), then things have gone pretty wrong. You should be able to use the search results to help figure out what the problem is.</div>
<p>Assuming everything went as expected, you should now find that Eclipse's code assistance works a whole lot better. :-) To test out the code assistance, see the code assistance tips in the Usage Tips section below.</p>
<p>To improve code assistance even more, see the "Headers are only parsed once" subsection in the "Known Issues" section below.</p>
<h3>Keeping the index up-to-date</h3>
<p>As the source changes from day-to-day, you'll want to update the index to keep the code assistance working well.</p>
<p>Since the compiler options used to build the source change relatively infrequently, the "build" step above doesn't need to be rerun all that often. Re-run it (and then rebuild the index) once a week or so, or as necessary when you start to notice unnusual code assistance issues that aren't fixed by rebuilding the index alone.</p>
<p>Rebuilding the index itself is required much more frequently, since the source changes more frequently. In principle you can set the index to rebuild automatically by opening the workspace preferences, selecting "C/C++ &gt; Indexer" and reenebling "Automatically update the index". However, you may find this too disruptive, since reindexing will then happen very frequently and code assistance can be broken while the index is rebuilding. The alternative is to leave that option disabled and update the index manually as necessary. To update the index manually, use the context menu in the Project Explorer tab on the left side of the window. To rebuild for changes in an individual directory (for example to take account of some changes that you yourself made) select "Index &gt; Freshen All Files" on that directory. To rebuild the entire index (for example when you update from mozilla-central) select "Index &gt; Rebuild" on the project root.</p>
<h2>Usage tips</h2>
<p>Below are some of the more useful user tips. (If you're thinking of adding tips, please first consider how widely useful they will be before adding to this already lengthy page.) For further documentation see the official <a class="external" href="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.user/gettingStarted/intro/overview.htm" title="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.platform.doc.user/gettingStarted/intro/overview.htm">Eclipse user guide</a> and <a class="external" href="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.cdt.doc.user/getting_started/cdt_o_tutorial.htm" title="http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.cdt.doc.user/getting_started/cdt_o_tutorial.htm">Eclipse CDT user guide</a>.</p>
<h3>Keyboard shortcuts</h3>
<p>Regarding key bindings (keyboard shortcuts), the bindings given below are the defaults. You can change the key bindings by opening the workspace preferences (Eclipse &gt; Preferences, or Window &gt; Preferences) and selecting "General &gt; Keys". You can set the scheme to "Emacs" or "Microsoft Visual Studio" if that's your thing, or change individual key bingings. When changing individual key bindings, <u>note that bindings are context sensitive, and that any changes you make may be ignored</u> if they conflict with existing bindings or if they are overriden by a binding for a more specific context. For example, changing the Find Next command to cmd-G/ctrl-G is not sufficient. For that to work you also either need to find the existing bindings for that key combination (using the Bindings column to sort by key combination helps with this) and remove them, or else you need to make your binding very specific by setting the "When" field to "C/C++ Editor" instead of the more general "Editing Text".</p>
<h3>Opening files</h3>
<p>You can quickly open a file by name using Cmd-Shift-R/Ctrl-Shift-R. Although Eclipse doesn't do fuzzy matching when you type a file name, it does allow you to use wildcards.</p>
<p>To quickly switch between a source file and its header file, use Ctrl-Tab.</p>
<p>To quickly switch to a recently viewed document use Cmd-F6/Ctrl-F6. If you want to change this awkward key binding, the command you need to rebind is "Next Editor".</p>
<p>To show a filterable list of open documents (similar to Emacs buffers), use Cmd-E/Ctrl-E.</p>
<p>If you click the yellow, double arrow button at the top of the Project Explorer tab on the left, it will keep the selected file in the Project Explorer tab in sync with the file that you're currently editing.</p>
<h3>Organizing views</h3>
<p>Use Ctrl-M to toggle maximization of the current editor view.</p>
<p>To tab to another view, use Cmd-F7/Ctrl-F7. This is useful if you have maximized the editor using Ctrl-M and you want to quickly see your search results, for example, without un-maximizing the editor.</p>
<p>To side-by-side edit the same file in two different tabs, select the tab of the file that you want to edit, then from the menu bar select "Window &gt; New Editor". This will open another tab containing the same file. Now simply drag that tab to position it beside, above or below the original. Changes you make in one editor will be immediately reflected in the other.</p>
<p>Note that the Search, Call Hierarchy, etc. tabs have a "Pin" button that allows you to open multiple tabs of the same type. This is useful if you want to keep your existing search results open, for example, and have a new search open its in a separate tab rather than overriding the contents of the existing Search tab.</p>
<h3>Code assistance</h3>
<div class="warning">Warning: indexing, by its very nature, is specific to a given compiler configuration. Be aware that when Eclipse gives results for any of the actions that follow, it will not include results for sections of the code that are ifdef'ed out by the configuration used to create your object directory. For example, if you are using Mac and you search for callers of nsDisplayListBuilder::IsInTransform, the results will not include the caller in nsObjectFrame.cpp because that caller is wrapped in "#ifndef XP_MACOSX". For most people this won't bite them too often, but be sure to use Try before you push when changing symbols. ;-)</div>
<p>To jump to the definition of a symbol (or the declaration of a symbol if already at the definition), hover over the symbol, hold down the Ctrl key, move the mouse slightly to linkify the symbol, then click on it.</p>
<p>To do a C++ symbol search select "Search &gt; C/C++" from the menubar, or use Ctrl-H and select the "C/C++" Search tab.</p>
<p>To get a list of autocomplete options in an editor, start typing the name of an identifier and then type Ctrl-Space. Unfortunately the autocomplete list cannot (currently) be configured to appear automatically as soon as you start typing a character that might be the start of an identifier name.</p>
<p>To see the callers of a method (and their callers, etc.), select the method and use the context menu to select "Open Call Hierarchy".</p>
<p>To see the inheritance tree for a class, select its name in an editor window and select "Open Type Hierarchy" from the context menu. Note that you can switch between "Show the Type Hierarchy", "Show the Supertype Hierarchy" and "Show the Subtype Hierarchy" using the buttons to the right of the "Type Hierarchy" tab.</p>
<p>To see the overrides of a virtual method, select that method's name in an editor window and select "Open Type Hierarchy" or "Quick Type Hierarchy" from the context menu. The results for "Open Type Hierarchy" will show all classes in the inheritance tree, and those methods that override the method will have a triangular red marker beside them. Select one of these classes and in the method pane to the right the method you searched for will be highlighted - double click to see its definition. The results for "Quick Type Hierarchy" will only show those classes in the inheritance tree that override the method. Double click on a class to go straight to its override's definition.</p>
<h2>Building from Eclipse</h2>
<div class="warning">In short, don't do this. Eclipse doesn't have good facilities for building incrementally in individual directories in the way that Mozilla developers generally require. More importantly, unless you're willing to screw up Eclipse's code assistance (in which case why bother using Eclipse) you're going to have to set Eclipse's "Build" step to do very slow, non-parallel, full rebuilds. (See the "Code assistance" section above.)</div>
<p>Nevertheless, if you understand the above warning and you still want to configure Eclipse's "Build" button to invoke a real bulid, then read on.</p>
<p>Basically you want to do something similar to the steps in the Initial project properties section above, but use "make -j1 -wB" (or just "make" if you don't care about keeping code assistance working) instead of using just-print-mozilla-build.py.</p>
<p>If you want to invoke "make -f client.mk" from your source directory instead of invoking make from your object directory, then in the "C/C++ Build" section of the project properties, set "Build command" to "make -f client.mk" and set "Build directory" to just "${ProjDirPath}" (this is the top of the source tree). Select the Behaviour tab and remove the "all" from the "Build (Incremental build)" field. Select "C/C++ Build &gt; Build Variables", and add a variable "MOZCONFIG" and set it to the top source directory relative path of the mozconfig file you want to buid with. Set any other environment variables you want to set for the build, then close the project properties window.</p>
<p>Now when you hit the Build button (the little hammer icon) you should see the source build in the Console tab at the bottom of the window.</p>
<p>The benefit of building from inside Eclipse is that build errors will appear in the Problems tab at the bottom of the window, and from there you can double click on the build error and it will take you straight to the source line where the problem occurred. For this to work reliably though, you need to build with similar make flags to those used to create the build log in the instructions above. Specifically, in order to reliabaly identify the problem source file, you should not do a parallel build, and you should pass the -w flag to make so that it outputs "Entering"/"Leaving" lines. It also used to be necessary to add the following two lines to your mozconfig to make the compiler output errors all on a single line, but that may not be needed any more:</p>
<pre>export CFLAGS="-fmessage-length=0"
export CPPFLAGS="-fmessage-length=0"
</pre>
<h2>Debugging</h2>
<p class="eval">To create a debug configuration, open the project properties window, and select "Run/Debug Settings" on the left. Click "New" then select "C/C++ Application". In the window that opens enter the path to your firefox binary (something like obj-debug/dist/NightlyDebug.app/Contents/MacOS/firefox) and select "Disable auto build". Select the Arguments tab and enter any args you want to pass to firefox (such as "--no-remote -p my-testing-profile"). If you're on Linux, you may also need to set the "Working directory" to "${ProjDirPath}/obj-debug/dist/bin", and then select the Environment tab and set LD_LIBRARY_PATH to ".:./plugins:.", and LIBRARY_PATH to ".:./components:.". (Is this really necessary? If so, why? Isn't LIBRARY_PATH for compile time, not run time, linking?)</p>
<p>In the workspace preferences, you may want to go to "C/C++ &gt; Debug &gt; GDB" and deselect "Stop on startup at" so that Eclipse won't automatically break in main() when it launches Firefox for debugging.</p>
<p>To debug, click the Debug button on the toolbar, or select "Run &gt; Debug" from the menu bar.</p>
<p>It's not obvious, but <a class="external" href="http://wiki.eclipse.org/CDT/User/FAQ#Since_the_debugger_is_gdb.2C_can_I_simply_access_the_gdb_command_line_interface_.28CLI.29.3F" title="http://wiki.eclipse.org/CDT/User/FAQ#Since_the_debugger_is_gdb.2C_can_I_simply_access_the_gdb_command_line_interface_.28CLI.29.3F">you can get a gdb prompt in the console</a> so that you can type gdb commands directly.</p>
<p>After you've finished debugging, you can get back to the C/C++ perspective via the menubar by selecting "Window &gt; Open Perspective &gt; C/C++".</p>
<h3>Upgrading GDB on Mac</h3>
<p>The ancient, barely maintained fork of GDB that comes with Xcode on Mac is really horrible. If you use Mac, you may want to <a class="external" href="http://sourceware.org/gdb/wiki/BuildingOnDarwin" title="http://sourceware.org/gdb/wiki/BuildingOnDarwin">build the latest FSF version of GDB</a> and set Eclipse to use that GDB for debugging. One suggested configuration for building GDB is '--prefix="$HOME" --disable-debug --with-python=/usr' (create an optimized build with <a class="external" href="http://sourceware.org/gdb/wiki/PythonGdbTutorial" title="http://sourceware.org/gdb/wiki/PythonGdbTutorial">support for Python</a> (so you can use python to much better control when you break etc.), and install it in $HOME/bin). That done, open the workspace preferences, select "C/C++ &gt; Debug &gt; GDB", and set "GDB Debugger" to the full path of your new gdb executable.</p>
<h3>GDB unexpectedly detaching</h3>
<p>If GDB starts ignoring your breakpoints, or unexpectedly terminates or detaches from the Firefox process, this may be caused by out of date breakpoints (breakpoints that you set during a previous debug session, after which you've since rebuilt). Remove any such breakpoints and restart your debug session.</p>
<h2>Known Issues</h2>
<p>There are various knows limitations and bugs when it comes to using Eclipse with Mozilla. Eclipse is open source, of course, so if anyone feels like doing a bit of Java hacking to fix these issues that'd be great. :-)</p>
<h3>Headers are only parsed once</h3>
<p>For performance reasons, Eclipse only processes header files that have include guards once, using the compiler options for the first source file it encounters that includes that header (<a class="link-https" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=380511" title="https://bugs.eclipse.org/bugs/show_bug.cgi?id=380511">Eclipse bug 380511</a>). This is responsible for most of the parse errors in the source files displayed in Eclipse. The problem is that the compiler options for the original source file may ifdef out sections of the header that would not be ifdef'ed out - and in fact are required by - source files in other parts of the tree.</p>
<p>For example, in content/svg/content/src/nsSVGEllipseElement.cpp Eclipse shows a parse error due to NS_DOM_INTERFACE_MAP_ENTRY_CLASSINFO not being defined. This define is in nsDOMClassInfoID.h, which is included via the following include chain:</p>
<pre>content/svg/content/src/nsSVGEllipseElement.cpp
 content/svg/content/src/nsSVGPathGeometryElement.h
  content/svg/content/src/nsSVGGraphicElement.h
   content/svg/content/src/nsSVGStylableElement.h
    content/svg/content/src/nsSVGElement.h
     content/base/src/nsGenericElement.h
      obj-debug/dist/include/nsDOMClassInfoID.h
</pre>
<p>In nsDOMClassInfoID.h the NS_DOM_INTERFACE_MAP_ENTRY_CLASSINFO define is behind an |ifdef _IMPL_NS_LAYOUT|. The properties for nsSVGEllipseElement.cpp show that this define was picked up by the build option discovery and set on nsSVGEllipseElement.cpp, but somehow it's not set for nsDOMClassInfoID.h. If you right click on nsDOMClassInfoID.h in the Project Explorer and select "Index &gt; Create Parser Log File", the log shows "Context" is set to "accessible/src/base/AccEvent.cpp" and if you check the properties for AccEvent.cpp, indeed it is not built with the _IMPL_NS_LAYOUT define.</p>
<p>One way to mitigate this problem is to manually define defines on problem directories. For example, to solve the _IMPL_NS_LAYOUT issue described above you would use the context menu for the 'layout' directory in the Project Explorer tab to open the directory's properties. Select "C/C++ General &gt; Prepocessor Include Paths, Macros etc.", and then select "GNU C++" and "CDT User Settings Entries". Click "Add", select "Preprocessor Macro" from the dropdown, then set Name to _IMPL_NS_LAYOUT and leave Value blank. Click OK twice to return to the main Eclipse window, and then use the context menu for the 'layout' directory to reindex the 'layout' directory and then to "Run C/C++ Code Analysis" on it.</p>
<p>This issue can also cause "Unresolved inclusion" errors in headers if the first time Eclipse sees the header is while indexing a file for which it doesn't have any build output parser data. (Since it then has no explicit include paths to search.) When this happens it causes a knock-on for all the files that include this header (directly or indirectly) since they too now have things missing. This problem is more important for people who have their object directory outside their source directory. When the object directory is inside the source directory (and not filtered out by a resource filter) then Eclipse's "Allow heuristic resolution of includes" (enabled by default) will generally allow the included headers to be found when processing source files that don't have build output parser data. When the object directory is outside the source directory though, the user needs to take extra steps to make sure the heuristic header resolution can find the headers. This is the reason that the instructions above instruct you to explicitly add {objdir}/dist/include to the project's "CDT User Setting Entries" if your object director is outside your source directory. Fixing <a class="link-https" href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=381601" title="https://bugs.eclipse.org/bugs/show_bug.cgi?id=381601">Eclipse bug 381601</a> would considerably reduce the impact of this issue.</p>
<h3>Searching</h3>
<p>Free text search is not backed by a database, so it is <em>extremely</em> slow. Furthermore the results are not saved, so if you immediately search for the exact same text again without any changes to the source files having occurred, Eclipse will do a slow search all over again.</p>
<p>It is not easy to restrict searches to an ad-hoc directory, which is pretty annoying given how slow free text search is.</p>
<p>Search history in a project is not preserved across restarts.</p>
<p>Duplicate searches in history - even consecutive ones - are not coalesced.</p>
<h3>Duplicate files</h3>
<p>Sometimes when searching for files or symbols you will be given the option between a file in the source tree, and a file with the same name under the object directory. (Some source and header files are copied to the object directory by the build process, so we end up with copies in both places.) This will happen if your object directory is inside the source directory. If you don't want to switch to building your object directory outside the source tree, then this is just one of those things that you'll have to put up with. (If you do switch, not the instructions that will then apply to you in the project configuration section above!) Since the indexer needs to be able to resolve header files in the object directory in order to produce good results we can't have Eclipse ignore the object directory. But then there's no easy way to tell Eclipse that any given file in the object directory is actually just a copy of a given file in the source directory, and that it should always show the user the copy in the source directory while using the file in the object directory for indexing.</p>
<h3>Building</h3>
<p>Eclipse's support for incremental builds is nonexistant. It would be nice if Eclipse could at least pass information about what files have changed to the build process, which could then decide on a faster way to do the build (e.g., "just make in layout/"). I (roc) have actually written a small change to the CDT Make builder that lets you specify that as an option, in which case Eclipse sends the names of all changed files to your build tool. The build tool is a Perl script that figures out if a faster build is possible and if so, does it.</p>
<h2>FAQ</h2>
<p>Here are some frequenty asked questions.</p>
<h3>Is there a Mercurial plugin for Eclipse?</h3>
<p>There is <a class="external" href="http://www.intland.com/products/mercurialeclipse/download" title="http://www.intland.com/products/mercurialeclipse/download">MercurialEclipse</a>, but probably most Mozilla developers will probably just prefer to use the command line. If you think we need our own documentation on MercurialEclipse, please consider adding a separate page for that tool since this page is long enough.</p>
<h3>How can I delete my Eclipse project and start over?</h3>
<p>If you followed the recommendation above of having one workspace per Mozilla tree, then this is easy. (If you didn't and you have projects for more than one source tree entangled in your workspace directory, well you're on your own.) Simply delete the <code>.project</code> and <code>.cproject</code> files and the <code>.settings</code> directory (if it exists) from the root of your Mozilla tree, and delete the workspace corresponding to the tree. That's it, you can now recreate an Eclipse project for your tree from scratch.</p>
<h3>Isn't there a better method of build option discovery?</h3>
<p>Yes, but Eclipse doesn't currently support it. Instead of reading build console output, Eclipse could use something like LD_PRELOAD to load its own little library into all the processes that are invoked as part of the build process. This library could then check whether the process is a compiler instance and, if so, use the processes' current working directory and the arguments that were passed to it to reliably obtain the information it needs for each source file that is compiled. This would simplify the instructions above since there would be no need to mess about with just-print-mozilla-build.py to avoid special non-parallelized, non-silenced builds. You could also build from Eclipse and get the benefits that brings.</p>
<h3>How can I run a more recent CDT version?</h3>
<p>If you have downloaded an <a class="external" href="http://www.eclipse.org/downloads/index-developer.php" title="http://www.eclipse.org/downloads/index-developer.php">Eclipse Developer build</a> then you can use Eclipse's software update mechanism to update your developer snapshot to the latest nightly for that developer branch. To do that, do the following.</p>
<p>From Eclipse's "Help" menu select "Install New Software...", then in the "Install" window that opens, click "Available Software Sites". In the window that opens, click "Add", and in the prompt set Name to something like "Nightly" and Location to something like "<a class=" external" href="http://download.eclipse.org/tools/cdt/builds/juno/nightly" rel="freelink">http://download.eclipse.org/tools/cd...s/juno/nightly</a>" (change "juno" to the current developer branch). Click "OK", then "OK" again. Type "Nightly" into the "Work with" field, and select the repository that you just added. (If it doesn't appear, close the window, reopen it from the Help menu, and try again.) A "CDT Main Features" option should now have been added in the area below. Tick this (<em>all</em> of its sub-options should then be ticked), click "Next" twice, accept the license agreement, and then click "Finish". Eclipse should now update itself and ask you to restart.</p>
<p><strong>Troubleshooting:</strong> If you get an error when trying to update, try clicking "Available Software Sites" in the "Install" window, make sure "Juno" is still unticked, that  "Nightly" is ticked, highlight "Nightly", click "Reload", "OK", and then try again.</p>
<h2>Troubleshooting</h2>
<p>Here is a list of problems people have encountered, and suggestions for solutions.</p>
<h3>Parser errors</h3>
<p>Parser errors/warnings are indicated by red/yellow markers on files in the Project Explorer tab, and in the bar down the right hand side of source files. In the case of the latter you can click on the marker to jump to the line with the problem and then hover over the "bug" icon to get an explanation of the problem.</p>
<p>The parser error indicators don't seem to show (reliably?) until you open a source file, then error markers will be added for that file. To force all markers to show for a directory, right click that directory in the Project Explorer and select "Run C/C++ Code Analysis". As well as adding the markers, this will give you a list of the issues in the Problems tab at the bottom of the window where you can double click to jump to the location of any given issue.</p>
<p>Other things you can try when trying to figure out parser errors include:</p>
<ol> <li>Select your project in the Project Explorer, then from the context menu select "Index &gt; Search for Unresolved Includes".</li> <li>For problematic source files, select the file in the Project Explorer and from the context menu select "Index &gt; Create Parser Log File".</li> <li>Select your project in the Project Explorer, then from the context menu select "Index &gt; Rebuild". When the indexing is done open the log using "Window &gt; Show View &gt; Other &gt; General &gt; Error Log" and check the summary and look for exceptions.</li>
</ol>
<h3>Problem Occurred (Java heap space)</h3>
<p>If Eclipse becomes glacially slow and then you get this error message, see the "Increasing memory limits" section above.</p>
<h3>Resource is out of sync with the file system</h3>
<p>If you get the message "Resource is out of sync with the file system", then you didn't set the "Refresh" options above in the "global configuration" section. Either set those, or else refresh the project (or an individual directory/file) manually using the Refresh item from the context menu in the Project Explorer tab.</p>
<h2>Old</h2>
<p>Everything that follows is old content that will be deleted (or integrated in).</p>
<h3>GDB Timeouts</h3>
<p>I don't think this is an issue any more in the last few Eclipse versions.</p>
<p>Out of the box, you may/will get GDB connection timeouts. This is because Eclipse is trying to push every subfolder in GDB's environment. The easiest way to resolve this issue is to remove any source entry from the debug configuration (Run-&gt;Open Debug Dialog...) in the Source tab. Doing so will unfortunately remove the binding between the binaries and the source code. To keep this feature working, you need to add a "Path Mapping" by clicking "Add..." in the Source tab. Once a "Path Mapping" is created, select "Edit..." and add an entry with these values</p>
<pre class="eval"> Compilation path: / 
 Local file system path: /
</pre>
<p>This is the only known workaround to bind binaries to source files. It has been tested and works perfectly under Eclipse Europa (3.3.2) with Eclipse-CDT (4.0.3).</p>
Revert to this revision